Classes

The AppLaunchContext type acts as a reference-counted owner of an underlying GdkAppLaunchContext instance. It provides the methods that can operate on this data type through AppLaunchContextProtocol conformance. Use AppLaunchContext as a strong reference or owner of a GdkAppLaunchContext instance.

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 ButtonEvent type acts as a reference-counted owner of an underlying GdkButtonEvent instance. It provides the methods that can operate on this data type through ButtonEventProtocol conformance. Use ButtonEvent as a strong reference or owner of a GdkButtonEvent instance.

An event related to a button on a pointer device.

The CairoContext type acts as a reference-counted owner of an underlying GdkCairoContext instance. It provides the methods that can operate on this data type through CairoContextProtocol conformance. Use CairoContext as a strong reference or owner of a GdkCairoContext instance.

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 Clipboard type acts as a reference-counted owner of an underlying GdkClipboard instance. It provides the methods that can operate on this data type through ClipboardProtocol conformance. Use Clipboard as a strong reference or owner of a GdkClipboard instance.

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 ContentDeserializer type acts as a reference-counted owner of an underlying GdkContentDeserializer instance. It provides the methods that can operate on this data type through ContentDeserializerProtocol conformance. Use ContentDeserializer as a strong reference or owner of a GdkContentDeserializer instance.

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 ContentProvider type acts as a reference-counted owner of an underlying GdkContentProvider instance. It provides the methods that can operate on this data type through ContentProviderProtocol conformance. Use ContentProvider as a strong reference or owner of a GdkContentProvider instance.

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 ContentSerializer type acts as a reference-counted owner of an underlying GdkContentSerializer instance. It provides the methods that can operate on this data type through ContentSerializerProtocol conformance. Use ContentSerializer as a strong reference or owner of a GdkContentSerializer instance.

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 CrossingEvent type acts as a reference-counted owner of an underlying GdkCrossingEvent instance. It provides the methods that can operate on this data type through CrossingEventProtocol conformance. Use CrossingEvent as a strong reference or owner of a GdkCrossingEvent instance.

An event caused by a pointing device moving between surfaces.

The Cursor type acts as a reference-counted owner of an underlying GdkCursor instance. It provides the methods that can operate on this data type through CursorProtocol conformance. Use Cursor as a strong reference or owner of a GdkCursor instance.

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 DNDEvent type acts as a reference-counted owner of an underlying GdkDNDEvent instance. It provides the methods that can operate on this data type through DNDEventProtocol conformance. Use DNDEvent as a strong reference or owner of a GdkDNDEvent instance.

An event related to drag and drop operations.

The ContentFormats type acts as a reference-counted owner of an underlying GdkContentFormats instance. It provides the methods that can operate on this data type through ContentFormatsProtocol conformance. Use ContentFormats as a strong reference or owner of a GdkContentFormats instance.

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 ContentFormatsBuilder type acts as a reference-counted owner of an underlying GdkContentFormatsBuilder instance. It provides the methods that can operate on this data type through ContentFormatsBuilderProtocol conformance. Use ContentFormatsBuilder as a strong reference or owner of a GdkContentFormatsBuilder instance.

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

The DeleteEvent type acts as a reference-counted owner of an underlying GdkDeleteEvent instance. It provides the methods that can operate on this data type through DeleteEventProtocol conformance. Use DeleteEvent as a strong reference or owner of a GdkDeleteEvent instance.

An event related to closing a top-level surface.

The Device type acts as a reference-counted owner of an underlying GdkDevice instance. It provides the methods that can operate on this data type through DeviceProtocol conformance. Use Device as a strong reference or owner of a GdkDevice instance.

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 DeviceTool type acts as a reference-counted owner of an underlying GdkDeviceTool instance. It provides the methods that can operate on this data type through DeviceToolProtocol conformance. Use DeviceTool as a strong reference or owner of a GdkDeviceTool instance.

A physical tool associated to a GdkDevice.

The Display type acts as a reference-counted owner of an underlying GdkDisplay instance. It provides the methods that can operate on this data type through DisplayProtocol conformance. Use Display as a strong reference or owner of a GdkDisplay instance.

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 DisplayManager type acts as a reference-counted owner of an underlying GdkDisplayManager instance. It provides the methods that can operate on this data type through DisplayManagerProtocol conformance. Use DisplayManager as a strong reference or owner of a GdkDisplayManager instance.

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 Drag type acts as a reference-counted owner of an underlying GdkDrag instance. It provides the methods that can operate on this data type through DragProtocol conformance. Use Drag as a strong reference or owner of a GdkDrag instance.

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 DrawContext type acts as a reference-counted owner of an underlying GdkDrawContext instance. It provides the methods that can operate on this data type through DrawContextProtocol conformance. Use DrawContext as a strong reference or owner of a GdkDrawContext instance.

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 Drop type acts as a reference-counted owner of an underlying GdkDrop instance. It provides the methods that can operate on this data type through DropProtocol conformance. Use Drop as a strong reference or owner of a GdkDrop instance.

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 Event type acts as a reference-counted owner of an underlying GdkEvent instance. It provides the methods that can operate on this data type through EventProtocol conformance. Use Event as a strong reference or owner of a GdkEvent instance.

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 DevicePad type acts as a reference-counted owner of an underlying GdkDevicePad instance. It provides the methods that can operate on this data type through DevicePadProtocol conformance. Use DevicePad as a strong reference or owner of a GdkDevicePad instance.

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 DragSurface type acts as a reference-counted owner of an underlying GdkDragSurface instance. It provides the methods that can operate on this data type through DragSurfaceProtocol conformance. Use DragSurface as a strong reference or owner of a GdkDragSurface instance.

A GdkDragSurface is an interface for surfaces used during DND.

The Paintable type acts as an owner of an underlying GdkPaintable instance. It provides the methods that can operate on this data type through PaintableProtocol conformance. Use Paintable as a strong reference or owner of a GdkPaintable instance.

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 EventSequence type acts as an owner of an underlying GdkEventSequence instance. It provides the methods that can operate on this data type through EventSequenceProtocol conformance. Use EventSequence as a strong reference or owner of a GdkEventSequence instance.

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

The FocusEvent type acts as a reference-counted owner of an underlying GdkFocusEvent instance. It provides the methods that can operate on this data type through FocusEventProtocol conformance. Use FocusEvent as a strong reference or owner of a GdkFocusEvent instance.

An event related to a keyboard focus change.

The FrameClock type acts as a reference-counted owner of an underlying GdkFrameClock instance. It provides the methods that can operate on this data type through FrameClockProtocol conformance. Use FrameClock as a strong reference or owner of a GdkFrameClock instance.

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 GLContext type acts as a reference-counted owner of an underlying GdkGLContext instance. It provides the methods that can operate on this data type through GLContextProtocol conformance. Use GLContext as a strong reference or owner of a GdkGLContext instance.

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 FrameTimings type acts as a reference-counted owner of an underlying GdkFrameTimings instance. It provides the methods that can operate on this data type through FrameTimingsProtocol conformance. Use FrameTimings as a strong reference or owner of a GdkFrameTimings instance.

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 GLTexture type acts as a reference-counted owner of an underlying GdkGLTexture instance. It provides the methods that can operate on this data type through GLTextureProtocol conformance. Use GLTexture as a strong reference or owner of a GdkGLTexture instance.

A GdkTexture representing a GL texture object.

The GrabBrokenEvent type acts as a reference-counted owner of an underlying GdkGrabBrokenEvent instance. It provides the methods that can operate on this data type through GrabBrokenEventProtocol conformance. Use GrabBrokenEvent as a strong reference or owner of a GdkGrabBrokenEvent instance.

An event related to a broken windowing system grab.

The KeyEvent type acts as a reference-counted owner of an underlying GdkKeyEvent instance. It provides the methods that can operate on this data type through KeyEventProtocol conformance. Use KeyEvent as a strong reference or owner of a GdkKeyEvent instance.

An event related to a key-based device.

The KeymapKey type acts as an owner of an underlying GdkKeymapKey instance. It provides the methods that can operate on this data type through KeymapKeyProtocol conformance. Use KeymapKey as a strong reference or owner of a GdkKeymapKey instance.

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

The MemoryTexture type acts as a reference-counted owner of an underlying GdkMemoryTexture instance. It provides the methods that can operate on this data type through MemoryTextureProtocol conformance. Use MemoryTexture as a strong reference or owner of a GdkMemoryTexture instance.

A GdkTexture representing image data in memory.

The Monitor type acts as a reference-counted owner of an underlying GdkMonitor instance. It provides the methods that can operate on this data type through MonitorProtocol conformance. Use Monitor as a strong reference or owner of a GdkMonitor instance.

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 MotionEvent type acts as a reference-counted owner of an underlying GdkMotionEvent instance. It provides the methods that can operate on this data type through MotionEventProtocol conformance. Use MotionEvent as a strong reference or owner of a GdkMotionEvent instance.

An event related to a pointer or touch device motion.

The PadEvent type acts as a reference-counted owner of an underlying GdkPadEvent instance. It provides the methods that can operate on this data type through PadEventProtocol conformance. Use PadEvent as a strong reference or owner of a GdkPadEvent instance.

An event related to a pad-based device.

The Popup type acts as a reference-counted owner of an underlying GdkPopup instance. It provides the methods that can operate on this data type through PopupProtocol conformance. Use Popup as a strong reference or owner of a GdkPopup instance.

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 Toplevel type acts as a reference-counted owner of an underlying GdkToplevel instance. It provides the methods that can operate on this data type through ToplevelProtocol conformance. Use Toplevel as a strong reference or owner of a GdkToplevel instance.

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 PopupLayout type acts as a reference-counted owner of an underlying GdkPopupLayout instance. It provides the methods that can operate on this data type through PopupLayoutProtocol conformance. Use PopupLayout as a strong reference or owner of a GdkPopupLayout instance.

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 RGBA type acts as an owner of an underlying GdkRGBA instance. It provides the methods that can operate on this data type through RGBAProtocol conformance. Use RGBA as a strong reference or owner of a GdkRGBA instance.

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 ProximityEvent type acts as a reference-counted owner of an underlying GdkProximityEvent instance. It provides the methods that can operate on this data type through ProximityEventProtocol conformance. Use ProximityEvent as a strong reference or owner of a GdkProximityEvent instance.

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

The ScrollEvent type acts as a reference-counted owner of an underlying GdkScrollEvent instance. It provides the methods that can operate on this data type through ScrollEventProtocol conformance. Use ScrollEvent as a strong reference or owner of a GdkScrollEvent instance.

An event related to a scrolling motion.

The Rectangle type acts as an owner of an underlying GdkRectangle instance. It provides the methods that can operate on this data type through RectangleProtocol conformance. Use Rectangle as a strong reference or owner of a GdkRectangle instance.

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 Seat type acts as a reference-counted owner of an underlying GdkSeat instance. It provides the methods that can operate on this data type through SeatProtocol conformance. Use Seat as a strong reference or owner of a GdkSeat instance.

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

The Snapshot type acts as a reference-counted owner of an underlying GdkSnapshot instance. It provides the methods that can operate on this data type through SnapshotProtocol conformance. Use Snapshot as a strong reference or owner of a GdkSnapshot instance.

Base type for snapshot operations.

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

The Surface type acts as a reference-counted owner of an underlying GdkSurface instance. It provides the methods that can operate on this data type through SurfaceProtocol conformance. Use Surface as a strong reference or owner of a GdkSurface instance.

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 Texture type acts as a reference-counted owner of an underlying GdkTexture instance. It provides the methods that can operate on this data type through TextureProtocol conformance. Use Texture as a strong reference or owner of a GdkTexture instance.

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 TimeCoord type acts as an owner of an underlying GdkTimeCoord instance. It provides the methods that can operate on this data type through TimeCoordProtocol conformance. Use TimeCoord as a strong reference or owner of a GdkTimeCoord instance.

A GdkTimeCoord stores a single event in a motion history.

The ToplevelLayout type acts as a reference-counted owner of an underlying GdkToplevelLayout instance. It provides the methods that can operate on this data type through ToplevelLayoutProtocol conformance. Use ToplevelLayout as a strong reference or owner of a GdkToplevelLayout instance.

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 ToplevelSize type acts as an owner of an underlying GdkToplevelSize instance. It provides the methods that can operate on this data type through ToplevelSizeProtocol conformance. Use ToplevelSize as a strong reference or owner of a GdkToplevelSize instance.

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

The TouchEvent type acts as a reference-counted owner of an underlying GdkTouchEvent instance. It provides the methods that can operate on this data type through TouchEventProtocol conformance. Use TouchEvent as a strong reference or owner of a GdkTouchEvent instance.

An event related to a touch-based device.

The TouchpadEvent type acts as a reference-counted owner of an underlying GdkTouchpadEvent instance. It provides the methods that can operate on this data type through TouchpadEventProtocol conformance. Use TouchpadEvent as a strong reference or owner of a GdkTouchpadEvent instance.

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 VulkanContext type acts as a reference-counted owner of an underlying GdkVulkanContext instance. It provides the methods that can operate on this data type through VulkanContextProtocol conformance. Use VulkanContext as a strong reference or owner of a GdkVulkanContext instance.

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.