Protocols

The AppLaunchContextProtocol protocol exposes the methods and properties of an underlying GdkAppLaunchContext instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see AppLaunchContext. Alternatively, use AppLaunchContextRef as a lighweight, unowned reference if you already have an instance you just want to use.

GdkAppLaunchContext handles launching an application in a graphical context.

It is an implementation of GAppLaunchContext that provides startup notification and allows to launch applications on a specific screen or workspace.

Launching an application

GdkAppLaunchContext *context;

context = gdk_display_get_app_launch_context (display);

gdk_app_launch_context_set_display (display);
gdk_app_launch_context_set_timestamp (gdk_event_get_time (event));

if (!g_app_info_launch_default_for_uri ("http://www.gtk.org", context, &error))
  g_warning ("Launching failed: `s`\n", error->message);

g_object_unref (context);

The ButtonEventProtocol protocol exposes the methods and properties of an underlying GdkButtonEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ButtonEvent. Alternatively, use ButtonEventRef as a lighweight, unowned reference if you already have an instance you just want to use.

An event related to a button on a pointer device.

The CairoContextProtocol protocol exposes the methods and properties of an underlying GdkCairoContext instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see CairoContext. Alternatively, use CairoContextRef as a lighweight, unowned reference if you already have an instance you just want to use.

GdkCairoContext is an object representing the platform-specific draw context.

GdkCairoContexts are created for a surface using [methodGdk.Surface.create_cairo_context], and the context can then be used to draw on that surface.

The ClipboardProtocol protocol exposes the methods and properties of an underlying GdkClipboard instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Clipboard. Alternatively, use ClipboardRef as a lighweight, unowned reference if you already have an instance you just want to use.

The GdkClipboard object represents data shared between applications or inside an application.

To get a GdkClipboard object, use [methodGdk.Display.get_clipboard] or [methodGdk.Display.get_primary_clipboard]. You can find out about the data that is currently available in a clipboard using [methodGdk.Clipboard.get_formats].

To make text or image data available in a clipboard, use [methodGdk.Clipboard.set_text] or [methodGdk.Clipboard.set_texture]. For other data, you can use [methodGdk.Clipboard.set_content], which takes a [classGdk.ContentProvider] object.

To read textual or image data from a clipboard, use [methodGdk.Clipboard.read_text_async] or [methodGdk.Clipboard.read_texture_async]. For other data, use [methodGdk.Clipboard.read_async], which provides a GInputStream object.

The ContentDeserializerProtocol protocol exposes the methods and properties of an underlying GdkContentDeserializer instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ContentDeserializer. Alternatively, use ContentDeserializerRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkContentDeserializer is used to deserialize content received via inter-application data transfers.

The GdkContentDeserializer transforms serialized content that is identified by a mime type into an object identified by a GType.

GTK provides serializers and deserializers for common data types such as text, colors, images or file lists. To register your own deserialization functions, use [funccontent_register_deserializer].

Also see [classGdk.ContentSerializer].

The ContentProviderProtocol protocol exposes the methods and properties of an underlying GdkContentProvider instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ContentProvider. Alternatively, use ContentProviderRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkContentProvider is used to provide content for the clipboard or for drag-and-drop operations in a number of formats.

To create a GdkContentProvider, use [ctorGdk.ContentProvider.new_for_value] or [ctorGdk.ContentProvider.new_for_bytes].

GDK knows how to handle common text and image formats out-of-the-box. See [classGdk.ContentSerializer] and [classGdk.ContentDeserializer] if you want to add support for application-specific data formats.

The ContentSerializerProtocol protocol exposes the methods and properties of an underlying GdkContentSerializer instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ContentSerializer. Alternatively, use ContentSerializerRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkContentSerializer is used to serialize content for inter-application data transfers.

The GdkContentSerializer transforms an object that is identified by a GType into a serialized form (i.e. a byte stream) that is identified by a mime type.

GTK provides serializers and deserializers for common data types such as text, colors, images or file lists. To register your own serialization functions, use [funccontent_register_serializer].

Also see [classGdk.ContentDeserializer].

The CrossingEventProtocol protocol exposes the methods and properties of an underlying GdkCrossingEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see CrossingEvent. Alternatively, use CrossingEventRef as a lighweight, unowned reference if you already have an instance you just want to use.

An event caused by a pointing device moving between surfaces.

The CursorProtocol protocol exposes the methods and properties of an underlying GdkCursor instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Cursor. Alternatively, use CursorRef as a lighweight, unowned reference if you already have an instance you just want to use.

GdkCursor is used to create and destroy cursors.

Cursors are immutable objects, so once you created them, there is no way to modify them later. You should create a new cursor when you want to change something about it.

Cursors by themselves are not very interesting: they must be bound to a window for users to see them. This is done with [methodGdk.Surface.set_cursor] or [methodGdk.Surface.set_device_cursor]. Applications will typically use higher-level GTK functions such as [methodGtk.Widget.set_cursor]` instead.

Cursors are not bound to a given [classGdk.Display], so they can be shared. However, the appearance of cursors may vary when used on different platforms.

Named and texture cursors

There are multiple ways to create cursors. The platform’s own cursors can be created with [ctorGdk.Cursor.new_from_name]. That function lists the commonly available names that are shared with the CSS specification. Other names may be available, depending on the platform in use. On some platforms, what images are used for named cursors may be influenced by the cursor theme.

Another option to create a cursor is to use [ctorGdk.Cursor.new_from_texture] and provide an image to use for the cursor.

To ease work with unsupported cursors, a fallback cursor can be provided. If a [classGdk.Surface] cannot use a cursor because of the reasons mentioned above, it will try the fallback cursor. Fallback cursors can themselves have fallback cursors again, so it is possible to provide a chain of progressively easier to support cursors. If none of the provided cursors can be supported, the default cursor will be the ultimate fallback.

The DNDEventProtocol protocol exposes the methods and properties of an underlying GdkDNDEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see DNDEvent. Alternatively, use DNDEventRef as a lighweight, unowned reference if you already have an instance you just want to use.

An event related to drag and drop operations.

The ContentFormatsProtocol protocol exposes the methods and properties of an underlying GdkContentFormats instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ContentFormats. Alternatively, use ContentFormatsRef as a lighweight, unowned reference if you already have an instance you just want to use.

The GdkContentFormats structure is used to advertise and negotiate the format of content.

You will encounter GdkContentFormats when interacting with objects controlling operations that pass data between different widgets, window or application, like [classGdk.Drag], [classGdk.Drop], [classGdk.Clipboard] or [classGdk.ContentProvider].

GDK supports content in 2 forms: GType and mime type. Using GTypes is meant only for in-process content transfers. Mime types are meant to be used for data passing both in-process and out-of-process. The details of how data is passed is described in the documentation of the actual implementations. To transform between the two forms, [classGdk.ContentSerializer] and [classGdk.ContentDeserializer] are used.

A GdkContentFormats describes a set of possible formats content can be exchanged in. It is assumed that this set is ordered. GTypes are more important than mime types. Order between different GTypes or mime types is the order they were added in, most important first. Functions that care about order, such as [methodGdk.ContentFormats.union], will describe in their documentation how they interpret that order, though in general the order of the first argument is considered the primary order of the result, followed by the order of further arguments.

For debugging purposes, the function [methodGdk.ContentFormats.to_string] exists. It will print a comma-separated list of formats from most important to least important.

GdkContentFormats is an immutable struct. After creation, you cannot change the types it represents. Instead, new GdkContentFormats have to be created. The [structGdk.ContentFormatsBuilder]` structure is meant to help in this endeavor.

The ContentFormatsBuilderProtocol protocol exposes the methods and properties of an underlying GdkContentFormatsBuilder instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ContentFormatsBuilder. Alternatively, use ContentFormatsBuilderRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkContentFormatsBuilder is an auxiliary struct used to create new GdkContentFormats, and should not be kept around.

The ContentProviderClassProtocol protocol exposes the methods and properties of an underlying GdkContentProviderClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ContentProviderClass. Alternatively, use ContentProviderClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

Class structure for GdkContentProvider.

The DevicePadInterfaceProtocol protocol exposes the methods and properties of an underlying GdkDevicePadInterface instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see DevicePadInterface. Alternatively, use DevicePadInterfaceRef as a lighweight, unowned reference if you already have an instance you just want to use.

The DeleteEventProtocol protocol exposes the methods and properties of an underlying GdkDeleteEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see DeleteEvent. Alternatively, use DeleteEventRef as a lighweight, unowned reference if you already have an instance you just want to use.

An event related to closing a top-level surface.

The DeviceProtocol protocol exposes the methods and properties of an underlying GdkDevice instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Device. Alternatively, use DeviceRef as a lighweight, unowned reference if you already have an instance you just want to use.

The GdkDevice object represents an input device, such as a keyboard, a mouse, or a touchpad.

See the [classGdk.Seat] documentation for more information about the various kinds of devices, and their relationships.

The DeviceToolProtocol protocol exposes the methods and properties of an underlying GdkDeviceTool instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see DeviceTool. Alternatively, use DeviceToolRef as a lighweight, unowned reference if you already have an instance you just want to use.

A physical tool associated to a GdkDevice.

The DisplayProtocol protocol exposes the methods and properties of an underlying GdkDisplay instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Display. Alternatively, use DisplayRef as a lighweight, unowned reference if you already have an instance you just want to use.

GdkDisplay objects are the GDK representation of a workstation.

Their purpose are two-fold:

• To manage and provide information about input devices (pointers, keyboards, etc)
• To manage and provide information about output devices (monitors, projectors, etc)

Most of the input device handling has been factored out into separate [classGdk.Seat] objects. Every display has a one or more seats, which can be accessed with [methodGdk.Display.get_default_seat] and [methodGdk.Display.list_seats].

Output devices are represented by [classGdk.Monitor] objects, which can be accessed with [methodGdk.Display.get_monitor_at_surface] and similar APIs.

The DisplayManagerProtocol protocol exposes the methods and properties of an underlying GdkDisplayManager instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see DisplayManager. Alternatively, use DisplayManagerRef as a lighweight, unowned reference if you already have an instance you just want to use.

A singleton object that offers notification when displays appear or disappear.

You can use [funcGdk.DisplayManager.get] to obtain the GdkDisplayManager singleton, but that should be rarely necessary. Typically, initializing GTK opens a display that you can work with without ever accessing the GdkDisplayManager.

The GDK library can be built with support for multiple backends. The GdkDisplayManager object determines which backend is used at runtime.

In the rare case that you need to influence which of the backends is being used, you can use [funcGdk.set_allowed_backends]. Note that you need to call this function before initializing GTK.

Backend-specific code

When writing backend-specific code that is supposed to work with multiple GDK backends, you have to consider both compile time and runtime. At compile time, use the GDK_WINDOWING_X11, GDK_WINDOWING_WIN32 macros, etc. to find out which backends are present in the GDK library you are building your application against. At runtime, use type-check macros like GDK_IS_X11_DISPLAY() to find out which backend is in use:

`ifdef` GDK_WINDOWING_X11
  if (GDK_IS_X11_DISPLAY (display))
    {
      // make X11-specific calls here
    }
  else
`endif`
`ifdef` GDK_WINDOWING_MACOS
  if (GDK_IS_MACOS_DISPLAY (display))
    {
      // make Quartz-specific calls here
    }
  else
`endif`
  g_error ("Unsupported GDK backend");

The DragProtocol protocol exposes the methods and properties of an underlying GdkDrag instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Drag. Alternatively, use DragRef as a lighweight, unowned reference if you already have an instance you just want to use.

The GdkDrag object represents the source of an ongoing DND operation.

A GdkDrag is created when a drag is started, and stays alive for duration of the DND operation. After a drag has been started with [funcGdk.Drag.begin], the caller gets informed about the status of the ongoing drag operation with signals on the GdkDrag object.

GTK provides a higher level abstraction based on top of these functions, and so they are not normally needed in GTK applications. See the “Drag and Drop” section of the GTK documentation for more information.

The DrawContextProtocol protocol exposes the methods and properties of an underlying GdkDrawContext instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see DrawContext. Alternatively, use DrawContextRef as a lighweight, unowned reference if you already have an instance you just want to use.

Base class for objects implementing different rendering methods.

GdkDrawContext is the base object used by contexts implementing different rendering methods, such as [classGdk.CairoContext] or [classGdk.GLContext]. It provides shared functionality between those contexts.

You will always interact with one of those subclasses.

A GdkDrawContext is always associated with a single toplevel surface.

The DropProtocol protocol exposes the methods and properties of an underlying GdkDrop instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Drop. Alternatively, use DropRef as a lighweight, unowned reference if you already have an instance you just want to use.

The GdkDrop object represents the target of an ongoing DND operation.

Possible drop sites get informed about the status of the ongoing drag operation with events of type GDK_DRAG_ENTER, GDK_DRAG_LEAVE, GDK_DRAG_MOTION and GDK_DROP_START. The GdkDrop object can be obtained from these [classGdk.Event] types using [methodGdk.DNDEvent.get_drop].

The actual data transfer is initiated from the target side via an async read, using one of the GdkDrop methods for this purpose: [methodGdk.Drop.read_async] or [methodGdk.Drop.read_value_async].

GTK provides a higher level abstraction based on top of these functions, and so they are not normally needed in GTK applications. See the “Drag and Drop” section of the GTK documentation for more information.

The EventProtocol protocol exposes the methods and properties of an underlying GdkEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Event. Alternatively, use EventRef as a lighweight, unowned reference if you already have an instance you just want to use.

GdkEvents are immutable data structures, created by GDK to represent windowing system events.

In GTK applications the events are handled automatically by toplevel widgets and passed on to the event controllers of appropriate widgets, so using GdkEvent and its related API is rarely needed.

The DevicePadProtocol protocol exposes the methods and properties of an underlying GdkDevicePad instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see DevicePad. Alternatively, use DevicePadRef as a lighweight, unowned reference if you already have an instance you just want to use.

GdkDevicePad is an interface implemented by devices of type GDK_SOURCE_TABLET_PAD

It allows querying the features provided by the pad device.

Tablet pads may contain one or more groups, each containing a subset of the buttons/rings/strips available. [methodGdk.DevicePad.get_n_groups] can be used to obtain the number of groups, [methodGdk.DevicePad.get_n_features] and [methodGdk.DevicePad.get_feature_group] can be combined to find out the number of buttons/rings/strips the device has, and how are they grouped.

Each of those groups have different modes, which may be used to map each individual pad feature to multiple actions. Only one mode is effective (current) for each given group, different groups may have different current modes. The number of available modes in a group can be found out through [methodGdk.DevicePad.get_group_n_modes], and the current mode for a given group will be notified through events of type GDK_PAD_GROUP_MODE.

The DragSurfaceProtocol protocol exposes the methods and properties of an underlying GdkDragSurface instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see DragSurface. Alternatively, use DragSurfaceRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkDragSurface is an interface for surfaces used during DND.

The PaintableProtocol protocol exposes the methods and properties of an underlying GdkPaintable instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Paintable. Alternatively, use PaintableRef as a lighweight, unowned reference if you already have an instance you just want to use.

GdkPaintable is a simple interface used by GTK to represent content that can be painted.

The content of a GdkPaintable can be painted anywhere at any size without requiring any sort of layout. The interface is inspired by similar concepts elsewhere, such as ClutterContent, HTML/CSS Paint Sources, or SVG Paint Servers.

A GdkPaintable can be snapshot at any time and size using [methodGdk.Paintable.snapshot]. How the paintable interprets that size and if it scales or centers itself into the given rectangle is implementation defined, though if you are implementing a GdkPaintable and don’t know what to do, it is suggested that you scale your paintable ignoring any potential aspect ratio.

The contents that a GdkPaintable produces may depend on the [classGdkSnapshot] passed to it. For example, paintables may decide to use more detailed images on higher resolution screens or when OpenGL is available. A GdkPaintable will however always produce the same output for the same snapshot.

A GdkPaintable may change its contents, meaning that it will now produce a different output with the same snapshot. Once that happens, it will call [methodGdk.Paintable.invalidate_contents] which will emit the [signalGdkPaintable::invalidate-contents] signal. If a paintable is known to never change its contents, it will set the GDK_PAINTABLE_STATIC_CONTENTS flag. If a consumer cannot deal with changing contents, it may call [methodGdk.Paintable.get_current_image] which will return a static paintable and use that.

A paintable can report an intrinsic (or preferred) size or aspect ratio it wishes to be rendered at, though it doesn’t have to. Consumers of the interface can use this information to layout thepaintable appropriately. Just like the contents, the size of a paintable can change. A paintable will indicate this by calling [methodGdk.Paintable.invalidate_size] which will emit the [signalGdkPaintable::invalidate-size] signal. And just like for contents, if a paintable is known to never change its size, it will set the GDK_PAINTABLE_STATIC_SIZE flag.

Besides API for applications, there are some functions that are only useful for implementing subclasses and should not be used by applications: [methodGdk.Paintable.invalidate_contents], [methodGdk.Paintable.invalidate_size], [funcGdk.Paintable.new_empty].

The DragSurfaceInterfaceProtocol protocol exposes the methods and properties of an underlying GdkDragSurfaceInterface instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see DragSurfaceInterface. Alternatively, use DragSurfaceInterfaceRef as a lighweight, unowned reference if you already have an instance you just want to use.

The GdkDragSurfaceInterface implementation is private to GDK.

The EventSequenceProtocol protocol exposes the methods and properties of an underlying GdkEventSequence instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see EventSequence. Alternatively, use EventSequenceRef as a lighweight, unowned reference if you already have an instance you just want to use.

GdkEventSequence is an opaque type representing a sequence of related touch events.

The FocusEventProtocol protocol exposes the methods and properties of an underlying GdkFocusEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FocusEvent. Alternatively, use FocusEventRef as a lighweight, unowned reference if you already have an instance you just want to use.

An event related to a keyboard focus change.

The FrameClockProtocol protocol exposes the methods and properties of an underlying GdkFrameClock instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FrameClock. Alternatively, use FrameClockRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkFrameClock tells the application when to update and repaint a surface.

This may be synced to the vertical refresh rate of the monitor, for example. Even when the frame clock uses a simple timer rather than a hardware-based vertical sync, the frame clock helps because it ensures everything paints at the same time (reducing the total number of frames).

The frame clock can also automatically stop painting when it knows the frames will not be visible, or scale back animation framerates.

GdkFrameClock is designed to be compatible with an OpenGL-based implementation or with mozRequestAnimationFrame in Firefox, for example.

A frame clock is idle until someone requests a frame with [methodGdk.FrameClock.request_phase]. At some later point that makes sense for the synchronization being implemented, the clock will process a frame and emit signals for each phase that has been requested. (See the signals of the GdkFrameClock class for documentation of the phases. GDK_FRAME_CLOCK_PHASE_UPDATE and the [signalGdkFrameClock::update] signal are most interesting for application writers, and are used to update the animations, using the frame time given by [metohdGdk.FrameClock.get_frame_time].

The frame time is reported in microseconds and generally in the same timescale as g_get_monotonic_time(), however, it is not the same as g_get_monotonic_time(). The frame time does not advance during the time a frame is being painted, and outside of a frame, an attempt is made so that all calls to [methodGdk.FrameClock.get_frame_time] that are called at a “similar” time get the same value. This means that if different animations are timed by looking at the difference in time between an initial value from [methodGdk.FrameClock.get_frame_time] and the value inside the [signalGdkFrameClock::update] signal of the clock, they will stay exactly synchronized.

The GLContextProtocol protocol exposes the methods and properties of an underlying GdkGLContext instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see GLContext. Alternatively, use GLContextRef as a lighweight, unowned reference if you already have an instance you just want to use.

GdkGLContext is an object representing a platform-specific OpenGL draw context.

GdkGLContexts are created for a surface using [methodGdk.Surface.create_gl_context], and the context will match the the characteristics of the surface.

A GdkGLContext is not tied to any particular normal framebuffer. For instance, it cannot draw to the surface back buffer. The GDK repaint system is in full control of the painting to that. Instead, you can create render buffers or textures and use [funccairo_draw_from_gl] in the draw function of your widget to draw them. Then GDK will handle the integration of your rendering with that of other widgets.

Support for GdkGLContext is platform-specific and context creation can fail, returning nil context.

A GdkGLContext has to be made “current” in order to start using it, otherwise any OpenGL call will be ignored.

Creating a new OpenGL context

In order to create a new GdkGLContext instance you need a GdkSurface, which you typically get during the realize call of a widget.

A GdkGLContext is not realized until either [methodGdk.GLContext.make_current] or [methodGdk.GLContext.realize] is called. It is possible to specify details of the GL context like the OpenGL version to be used, or whether the GL context should have extra state validation enabled after calling [methodGdk.Surface.create_gl_context] by calling [methodGdk.GLContext.realize]. If the realization fails you have the option to change the settings of the GdkGLContext and try again.

Using a GdkGLContext

You will need to make the GdkGLContext the current context before issuing OpenGL calls; the system sends OpenGL commands to whichever context is current. It is possible to have multiple contexts, so you always need to ensure that the one which you want to draw with is the current one before issuing commands:

gdk_gl_context_make_current (context);

You can now perform your drawing using OpenGL commands.

You can check which GdkGLContext is the current one by using [funcGdk.GLContext.get_current]; you can also unset any GdkGLContext that is currently set by calling [funcGdk.GLContext.clear_current].

The FrameClockClassProtocol protocol exposes the methods and properties of an underlying GdkFrameClockClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FrameClockClass. Alternatively, use FrameClockClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

The FrameTimingsProtocol protocol exposes the methods and properties of an underlying GdkFrameTimings instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FrameTimings. Alternatively, use FrameTimingsRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkFrameTimings object holds timing information for a single frame of the application’s displays.

To retrieve GdkFrameTimings objects, use [methodGdk.FrameClock.get_timings] or [methodGdk.FrameClock.get_current_timings]. The information in GdkFrameTimings is useful for precise synchronization of video with the event or audio streams, and for measuring quality metrics for the application’s display, such as latency and jitter.

The GLTextureClassProtocol protocol exposes the methods and properties of an underlying GdkGLTextureClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see GLTextureClass. Alternatively, use GLTextureClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

The GLTextureProtocol protocol exposes the methods and properties of an underlying GdkGLTexture instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see GLTexture. Alternatively, use GLTextureRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkTexture representing a GL texture object.

The GrabBrokenEventProtocol protocol exposes the methods and properties of an underlying GdkGrabBrokenEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see GrabBrokenEvent. Alternatively, use GrabBrokenEventRef as a lighweight, unowned reference if you already have an instance you just want to use.

An event related to a broken windowing system grab.

The KeyEventProtocol protocol exposes the methods and properties of an underlying GdkKeyEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see KeyEvent. Alternatively, use KeyEventRef as a lighweight, unowned reference if you already have an instance you just want to use.

An event related to a key-based device.

The KeymapKeyProtocol protocol exposes the methods and properties of an underlying GdkKeymapKey instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see KeymapKey. Alternatively, use KeymapKeyRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkKeymapKey is a hardware key that can be mapped to a keyval.

The MemoryTextureClassProtocol protocol exposes the methods and properties of an underlying GdkMemoryTextureClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see MemoryTextureClass. Alternatively, use MemoryTextureClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

The MemoryTextureProtocol protocol exposes the methods and properties of an underlying GdkMemoryTexture instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see MemoryTexture. Alternatively, use MemoryTextureRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkTexture representing image data in memory.

The MonitorProtocol protocol exposes the methods and properties of an underlying GdkMonitor instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Monitor. Alternatively, use MonitorRef as a lighweight, unowned reference if you already have an instance you just want to use.

GdkMonitor objects represent the individual outputs that are associated with a GdkDisplay.

GdkDisplay keeps a GListModel to enumerate and monitor monitors with [methodGdk.Display.get_monitors]. You can use [methodGdk.Display.get_monitor_at_surface] to find a particular monitor.

The MotionEventProtocol protocol exposes the methods and properties of an underlying GdkMotionEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see MotionEvent. Alternatively, use MotionEventRef as a lighweight, unowned reference if you already have an instance you just want to use.

An event related to a pointer or touch device motion.

The PadEventProtocol protocol exposes the methods and properties of an underlying GdkPadEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PadEvent. Alternatively, use PadEventRef as a lighweight, unowned reference if you already have an instance you just want to use.

An event related to a pad-based device.

The MonitorClassProtocol protocol exposes the methods and properties of an underlying GdkMonitorClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see MonitorClass. Alternatively, use MonitorClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PaintableInterfaceProtocol protocol exposes the methods and properties of an underlying GdkPaintableInterface instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PaintableInterface. Alternatively, use PaintableInterfaceRef as a lighweight, unowned reference if you already have an instance you just want to use.

The list of functions that can be implemented for the GdkPaintable interface.

Note that apart from the GdkPaintableInterface.snapshot() function, no virtual function of this interface is mandatory to implement, though it is a good idea to implement GdkPaintableInterface.get_current_image() for non-static paintables and GdkPaintableInterface.get_flags() if the image is not dynamic as the default implementation returns no flags and that will make the implementation likely quite slow.

The PopupProtocol protocol exposes the methods and properties of an underlying GdkPopup instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Popup. Alternatively, use PopupRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkPopup is a surface that is attached to another surface.

The GdkPopup is positioned relative to its parent surface.

GdkPopups are typically used to implement menus and similar popups. They can be modal, which is indicated by the [propertyGdkPopup:autohide] property.

The ToplevelProtocol protocol exposes the methods and properties of an underlying GdkToplevel instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Toplevel. Alternatively, use ToplevelRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkToplevel is a freestanding toplevel surface.

The GdkToplevel interface provides useful APIs for interacting with the windowing system, such as controlling maximization and size of the surface, setting icons and transient parents for dialogs.

The PopupInterfaceProtocol protocol exposes the methods and properties of an underlying GdkPopupInterface instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PopupInterface. Alternatively, use PopupInterfaceRef as a lighweight, unowned reference if you already have an instance you just want to use.

The PopupLayoutProtocol protocol exposes the methods and properties of an underlying GdkPopupLayout instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see PopupLayout. Alternatively, use PopupLayoutRef as a lighweight, unowned reference if you already have an instance you just want to use.

The GdkPopupLayout struct contains information that is necessary position a [interfaceGdk.Popup] relative to its parent.

The positioning requires a negotiation with the windowing system, since it depends on external constraints, such as the position of the parent surface, and the screen dimensions.

The basic ingredients are a rectangle on the parent surface, and the anchor on both that rectangle and the popup. The anchors specify a side or corner to place next to each other.

For cases where placing the anchors next to each other would make the popup extend offscreen, the layout includes some hints for how to resolve this problem. The hints may suggest to flip the anchor position to the other side, or to ‘slide’ the popup along a side, or to resize it.

These hints may be combined.

Ultimatively, it is up to the windowing system to determine the position and size of the popup. You can learn about the result by calling [methodGdk.Popup.get_position_x], [methodGdk.Popup.get_position_y], [methodGdk.Popup.get_rect_anchor] and [methodGdk.Popup.get_surface_anchor] after the popup has been presented. This can be used to adjust the rendering. For example, [classGtk.Popover] changes its arrow position accordingly. But you have to be careful avoid changing the size of the popover, or it has to be presented again.

The RGBAProtocol protocol exposes the methods and properties of an underlying GdkRGBA instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see RGBA. Alternatively, use RGBARef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkRGBA is used to represent a color, in a way that is compatible with cairo’s notion of color.

GdkRGBA is a convenient way to pass colors around. It’s based on cairo’s way to deal with colors and mirrors its behavior. All values are in the range from 0.0 to 1.0 inclusive. So the color (0.0, 0.0, 0.0, 0.0) represents transparent black and (1.0, 1.0, 1.0, 1.0) is opaque white. Other values will be clamped to this range when drawing.

The ProximityEventProtocol protocol exposes the methods and properties of an underlying GdkProximityEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ProximityEvent. Alternatively, use ProximityEventRef as a lighweight, unowned reference if you already have an instance you just want to use.

An event related to the proximity of a tool to a device.

The ScrollEventProtocol protocol exposes the methods and properties of an underlying GdkScrollEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ScrollEvent. Alternatively, use ScrollEventRef as a lighweight, unowned reference if you already have an instance you just want to use.

An event related to a scrolling motion.

The RectangleProtocol protocol exposes the methods and properties of an underlying GdkRectangle instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Rectangle. Alternatively, use RectangleRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkRectangle data type for representing rectangles.

GdkRectangle is identical to cairo_rectangle_t. Together with Cairo’s cairo_region_t data type, these are the central types for representing sets of pixels.

The intersection of two rectangles can be computed with [methodGdk.Rectangle.intersect]; to find the union of two rectangles use [methodGdk.Rectangle.union].

The cairo_region_t type provided by Cairo is usually used for managing non-rectangular clipping of graphical operations.

The Graphene library has a number of other data types for regions and volumes in 2D and 3D.

The SnapshotClassProtocol protocol exposes the methods and properties of an underlying GdkSnapshotClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see SnapshotClass. Alternatively, use SnapshotClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

The SeatProtocol protocol exposes the methods and properties of an underlying GdkSeat instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Seat. Alternatively, use SeatRef as a lighweight, unowned reference if you already have an instance you just want to use.

The GdkSeat object represents a collection of input devices that belong to a user.

The SnapshotProtocol protocol exposes the methods and properties of an underlying GdkSnapshot instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Snapshot. Alternatively, use SnapshotRef as a lighweight, unowned reference if you already have an instance you just want to use.

Base type for snapshot operations.

The subclass of GdkSnapshot used by GTK is [classGtk.Snapshot].

The SurfaceProtocol protocol exposes the methods and properties of an underlying GdkSurface instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Surface. Alternatively, use SurfaceRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkSurface is a rectangular region on the screen.

It’s a low-level object, used to implement high-level objects such as [classGtk.Window] or [classGtk.Dialog] in GTK.

The surfaces you see in practice are either [classGdk.Toplevel] or [classGdk.Popup], and those interfaces provide much of the required API to interact with these surfaces. Other, more specialized surface types exist, but you will rarely interact with them directly.

The TextureProtocol protocol exposes the methods and properties of an underlying GdkTexture instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Texture. Alternatively, use TextureRef as a lighweight, unowned reference if you already have an instance you just want to use.

GdkTexture is the basic element used to refer to pixel data.

It is primarily meant for pixel data that will not change over multiple frames, and will be used for a long time.

There are various ways to create GdkTexture objects from a GdkPixbuf, or a Cairo surface, or other pixel data.

The ownership of the pixel data is transferred to the GdkTexture instance; you can only make a copy of it, via [methodGdk.Texture.download].

GdkTexture is an immutable object: That means you cannot change anything about it other than increasing the reference count via g_object_ref().

The SurfaceClassProtocol protocol exposes the methods and properties of an underlying GdkSurfaceClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see SurfaceClass. Alternatively, use SurfaceClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

The TextureClassProtocol protocol exposes the methods and properties of an underlying GdkTextureClass instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see TextureClass. Alternatively, use TextureClassRef as a lighweight, unowned reference if you already have an instance you just want to use.

The TimeCoordProtocol protocol exposes the methods and properties of an underlying GdkTimeCoord instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see TimeCoord. Alternatively, use TimeCoordRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkTimeCoord stores a single event in a motion history.

The ToplevelInterfaceProtocol protocol exposes the methods and properties of an underlying GdkToplevelInterface instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ToplevelInterface. Alternatively, use ToplevelInterfaceRef as a lighweight, unowned reference if you already have an instance you just want to use.

The ToplevelLayoutProtocol protocol exposes the methods and properties of an underlying GdkToplevelLayout instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ToplevelLayout. Alternatively, use ToplevelLayoutRef as a lighweight, unowned reference if you already have an instance you just want to use.

The GdkToplevelLayout struct contains information that is necessary to present a sovereign window on screen.

The GdkToplevelLayout struct is necessary for using [methodGdk.Toplevel.present].

Toplevel surfaces are sovereign windows that can be presented to the user in various states (maximized, on all workspaces, etc).

The ToplevelSizeProtocol protocol exposes the methods and properties of an underlying GdkToplevelSize instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see ToplevelSize. Alternatively, use ToplevelSizeRef as a lighweight, unowned reference if you already have an instance you just want to use.

The GdkToplevelSize struct contains information that is useful to compute the size of a toplevel.

The TouchEventProtocol protocol exposes the methods and properties of an underlying GdkTouchEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see TouchEvent. Alternatively, use TouchEventRef as a lighweight, unowned reference if you already have an instance you just want to use.

An event related to a touch-based device.

The TouchpadEventProtocol protocol exposes the methods and properties of an underlying GdkTouchpadEvent instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see TouchpadEvent. Alternatively, use TouchpadEventRef as a lighweight, unowned reference if you already have an instance you just want to use.

An event related to a gesture on a touchpad device.

Unlike touchscreens, where the windowing system sends basic sequences of begin, update, end events, and leaves gesture recognition to the clients, touchpad gestures are typically processed by the system, resulting in these events.

The VulkanContextProtocol protocol exposes the methods and properties of an underlying GdkVulkanContext instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see VulkanContext. Alternatively, use VulkanContextRef as a lighweight, unowned reference if you already have an instance you just want to use.

GdkVulkanContext is an object representing the platform-specific Vulkan draw context.

GdkVulkanContexts are created for a surface using [methodGdk.Surface.create_vulkan_context], and the context will match the the characteristics of the surface.

Support for GdkVulkanContext is platform-specific and context creation can fail, returning nil context.