gdk.c.types

Positioning hints for aligning a surface relative to a rectangle.

These hints determine how the surface should be positioned in the case that the surface would fall off-screen if placed in its ideal position.

For example, [gdk.types.AnchorHints.FlipX] will replace [gdk.types.Gravity.NorthWest] with [gdk.types.Gravity.NorthEast] and vice versa if the surface extends beyond the left or right edges of the monitor.

If [gdk.types.AnchorHints.SlideX] is set, the surface can be shifted horizontally to fit on-screen. If [gdk.types.AnchorHints.ResizeX] is set, the surface can be shrunken horizontally to fit.

In general, when multiple flags are set, flipping should take precedence over sliding, which should take precedence over resizing.

Flags describing the current capabilities of a device/tool.

Defines how device axes are interpreted by GTK.

Note that the X and Y axes are not really needed; pointer devices report their location via the x/y members of events regardless. Whether X and Y are present as axes depends on the GDK backend.

Specifies the crossing mode for enter and leave events.

A pad feature.

Indicates the specific type of tool being used being a tablet. Such as an airbrush, pencil, etc.

Error enumeration for [gdk.dmabuf_texture.DmabufTexture].

Used in [gdk.drop.Drop] and [gdk.drag.Drag] to indicate the actions that the destination can and should do with the dropped data.

Used in [gdk.drag.Drag] to the reason of a cancelled DND operation.

Specifies the type of the event.

Used to represent the different paint clock phases that can be requested.

The elements of the enumeration correspond to the signals of [gdk.frame_clock.FrameClock].

Indicates which monitor a surface should span over when in fullscreen mode.

The list of the different APIs that GdkGLContext can potentially support.

Error enumeration for [gdk.glcontext.GLContext].

Defines the reference point of a surface and is used in [gdk.popup_layout.PopupLayout].

An enumeration describing the type of an input device in general terms.

Describes how well an event matches a given keyval and modifiers.

[gdk.types.KeyMatch] values are returned by [gdk.key_event.KeyEvent.matches].

[gdk.types.MemoryFormat] describes formats that image data can have in memory.

It describes formats by listing the contents of the memory passed to it. So [gdk.types.MemoryFormat.A8r8g8b8] will be 1 byte (8 bits) of alpha, followed by a byte each of red, green and blue. It is not endian-dependent, so [cairo.types.Format.Argb32] is represented by different GdkMemoryFormats on architectures with different endiannesses.

Its naming is modelled after

for details).

Flags to indicate the state of modifier keys and mouse buttons in events.

Typical modifier keys are Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock or ShiftLock.

Note that GDK may add internal values to events which include values outside of this enumeration. Your code should preserve and ignore them. You can use [gdk.types.MODIFIER_MASK] to remove all private values.

Specifies the kind of crossing for enter and leave events.

See the X11 protocol specification of LeaveNotify for full details of crossing event generation.

Flags about a paintable object.

Implementations use these for optimizations such as caching.

Specifies the direction for scroll events.

Specifies the unit of scroll deltas.

When you get [gdk.types.ScrollUnit.Wheel], a delta of 1.0 means 1 wheel detent click in the south direction, 2.0 means 2 wheel detent clicks in the south direction... This is the same logic for negative values but in the north direction.

If you get [gdk.types.ScrollUnit.Surface], are managing a scrollable view and get a value of 123, you have to scroll 123 surface logical pixels right if it's @delta_x or down if it's @delta_y. This is the same logic for negative values but you have to scroll left instead of right if it's @delta_x and up instead of down if it's @delta_y.

1 surface logical pixel is equal to 1 real screen pixel multiplied by the final scale factor of your graphical interface (the product of the desktop scale factor and eventually a custom scale factor in your app).

Flags describing the seat capabilities.

This enumeration describes how the red, green and blue components of physical pixels on an output device are laid out.

Determines a surface edge or corner.

Possible errors that can be returned by [gdk.texture.Texture] constructors.

Specifies the state of a toplevel surface.

On platforms that support information about individual edges, the [gdk.types.ToplevelState.Tiled] state will be set whenever any of the individual tiled states is set. On platforms that lack that support, the tiled state will give an indication of tiledness without any of the per-edge states being set.

Specifies the current state of a touchpad gesture.

All gestures are guaranteed to begin with an event with phase [gdk.types.TouchpadGesturePhase.Begin], followed by 0 or several events with phase [gdk.types.TouchpadGesturePhase.Update].

A finished gesture may have 2 possible outcomes, an event with phase [gdk.types.TouchpadGesturePhase.End] will be emitted when the gesture is considered successful, this should be used as the hint to perform any permanent changes.

Cancelled gestures may be so for a variety of reasons, due to hardware or the compositor, or due to the gesture recognition layers hinting the gesture did not finish resolutely (eg. a 3rd finger being added during a pinch gesture). In these cases, the last event will report the phase [gdk.types.TouchpadGesturePhase.Cancel], this should be used as a hint to undo any visible/permanent changes that were done throughout the progress of the gesture.

Error enumeration for [gdk.vulkan_context.VulkanContext].

[gdk.app_launch_context.AppLaunchContext] handles launching an application in a graphical context.

It is an implementation of [gio.app_launch_context.AppLaunchContext] that provides startup notification and allows to launch applications on a specific workspace.

Launching an application

GdkAppLaunchContext *context;

context = gdk_display_get_app_launch_context (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);

An event related to a button on a pointer device.

[gdk.cairo_context.CairoContext] is an object representing the platform-specific draw context.

[gdk.cairo_context.CairoContext]s are created for a surface using [gdk.surface.Surface.createCairoContext], and the context can then be used to draw on that surface.

The [gdk.clipboard.Clipboard] object represents data shared between applications or inside an application.

To get a [gdk.clipboard.Clipboard] object, use [gdk.display.Display.getClipboard] or [gdk.display.Display.getPrimaryClipboard]. You can find out about the data that is currently available in a clipboard using [gdk.clipboard.Clipboard.getFormats].

To make text or image data available in a clipboard, use [gdk.clipboard.Clipboard.setText] or [gdk.clipboard.Clipboard.setTexture]. For other data, you can use [gdk.clipboard.Clipboard.setContent], which takes a [gdk.content_provider.ContentProvider] object.

To read textual or image data from a clipboard, use [gdk.clipboard.Clipboard.readTextAsync] or [gdk.clipboard.Clipboard.readTextureAsync]. For other data, use [gdk.clipboard.Clipboard.readAsync], which provides a [gio.input_stream.InputStream] object.

A [gdk.content_deserializer.ContentDeserializer] is used to deserialize content received via inter-application data transfers.

The [gdk.content_deserializer.ContentDeserializer] 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 func@content_register_deserializer.

Also see [gdk.content_serializer.ContentSerializer].

The [gdk.content_formats.ContentFormats] structure is used to advertise and negotiate the format of content.

You will encounter [gdk.content_formats.ContentFormats] when interacting with objects controlling operations that pass data between different widgets, window or application, like [gdk.drag.Drag], [gdk.drop.Drop], [gdk.clipboard.Clipboard] or [gdk.content_provider.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, [gdk.content_serializer.ContentSerializer] and [gdk.content_deserializer.ContentDeserializer] are used.

A [gdk.content_formats.ContentFormats] 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 [gdk.content_formats.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 [gdk.content_formats.ContentFormats.toString_] exists. It will print a comma-separated list of formats from most important to least important.

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

A [gdk.content_formats_builder.ContentFormatsBuilder] is an auxiliary struct used to create new [gdk.content_formats.ContentFormats], and should not be kept around.

A [gdk.content_provider.ContentProvider] is used to provide content for the clipboard or for drag-and-drop operations in a number of formats.

To create a [gdk.content_provider.ContentProvider], use [gdk.content_provider.ContentProvider.newForValue] or [gdk.content_provider.ContentProvider.newForBytes].

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

Class structure for [gdk.content_provider.ContentProvider].

A [gdk.content_serializer.ContentSerializer] is used to serialize content for inter-application data transfers.

The [gdk.content_serializer.ContentSerializer] 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 func@Gdk.content_register_serializer.

Also see [gdk.content_deserializer.ContentDeserializer].

An event caused by a pointing device moving between surfaces.

[gdk.cursor.Cursor] 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 [gdk.surface.Surface.setCursor] or [gdk.surface.Surface.setDeviceCursor]. Applications will typically use higher-level GTK functions such as [[gtk.widget.Widget.setCursor]](../gtk4/method.Widget.set_cursor.html) instead.

Cursors are not bound to a given [gdk.display.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 [gdk.cursor.Cursor.newFromName]. 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 [gdk.cursor.Cursor.newFromTexture] and provide an image to use for the cursor.

To ease work with unsupported cursors, a fallback cursor can be provided. If a [gdk.surface.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.

An event related to drag and drop operations.

An event related to closing a top-level surface.

The [gdk.device.Device] object represents an input device, such as a keyboard, a mouse, or a touchpad.

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

[gdk.device_pad.DevicePad] is an interface implemented by devices of type [gdk.types.InputSource.TabletPad]

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. [gdk.device_pad.DevicePad.getNGroups] can be used to obtain the number of groups, [gdk.device_pad.DevicePad.getNFeatures] and [gdk.device_pad.DevicePad.getFeatureGroup] 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 [gdk.device_pad.DevicePad.getGroupNModes], and the current mode for a given group will be notified through events of type [gdk.types.EventType.PadGroupMode].

A physical tool associated to a [gdk.device.Device].

[gdk.display.Display] 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 [gdk.seat.Seat] objects. Every display has a one or more seats, which can be accessed with [gdk.display.Display.getDefaultSeat] and [gdk.display.Display.listSeats].

Output devices are represented by [gdk.monitor.MonitorWrap] objects, which can be accessed with [gdk.display.Display.getMonitorAtSurface] and similar APIs.

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

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

The GDK library can be built with support for multiple backends. The [gdk.display_manager.DisplayManager] 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 func@Gdk.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 [gdk.dmabuf_formats.DmabufFormats] struct provides information about supported DMA buffer formats.

You can query whether a given format is supported with [gdk.dmabuf_formats.DmabufFormats.contains] and you can iterate over the list of all supported formats with [gdk.dmabuf_formats.DmabufFormats.getNFormats] and [gdk.dmabuf_formats.DmabufFormats.getFormat].

The list of supported formats is sorted by preference, with the best formats coming first.

The list may contains (format, modifier) pairs where the modifier is DMA_FORMAT_MOD_INVALID, indicating that _implicit modifiers_ may be used with this format.

See [gdk.dmabuf_texture_builder.DmabufTextureBuilder] for more information about DMA buffers.

Note that DMA buffers only exist on Linux.

A [gdk.texture.Texture] representing a DMA buffer.

To create a [gdk.dmabuf_texture.DmabufTexture], use the auxiliary [gdk.dmabuf_texture_builder.DmabufTextureBuilder] object.

Dma-buf textures can only be created on Linux.

[gdk.dmabuf_texture_builder.DmabufTextureBuilder] is a builder used to construct [gdk.texture.Texture] objects from DMA buffers.

DMA buffers are commonly called _dma-bufs_.

DMA buffers are a feature of the Linux kernel to enable efficient buffer and memory sharing between hardware such as codecs, GPUs, displays, cameras and the kernel drivers controlling them. For example, a decoder may want its output to be directly shared with the display server for rendering without a copy.

Any device driver which participates in DMA buffer sharing, can do so as either the exporter or importer of buffers (or both).

The memory that is shared via DMA buffers is usually stored in non-system memory (maybe in device's local memory or something else not directly accessible by the CPU), and accessing this memory from the CPU may have higher-than-usual overhead.

In particular for graphics data, it is not uncommon that data consists of multiple separate blocks of memory, for example one block for each of the red, green and blue channels. These blocks are called _planes_. DMA buffers can have up to four planes. Even if the memory is a single block, the data can be organized in multiple planes, by specifying offsets from the beginning of the data.

DMA buffers are exposed to user-space as file descriptors allowing to pass them between processes. If a DMA buffer has multiple planes, there is one file descriptor per plane.

The format of the data (for graphics data, essentially its colorspace) is described by a 32-bit integer. These format identifiers are defined in the header file drm_fourcc.h and commonly referred to as _fourcc_ values, since they are identified by 4 ASCII characters. Additionally, each DMA buffer has a _modifier_, which is a 64-bit integer that describes driver-specific details of the memory layout, such as tiling or compression.

For historical reasons, some producers of dma-bufs don't provide an explicit modifier, but instead return DMA_FORMAT_MOD_INVALID to indicate that their modifier is _implicit_. GTK tries to accommodate this situation by accepting DMA_FORMAT_MOD_INVALID as modifier.

The operation of [gdk.dmabuf_texture_builder.DmabufTextureBuilder] is quite simple: Create a texture builder, set all the necessary properties, and then call [gdk.dmabuf_texture_builder.DmabufTextureBuilder.build] to create the new texture.

The required properties for a dma-buf texture are

• The width and height in pixels

• The fourcc code and modifier which identify the format and memory layout of the dma-buf

• The file descriptor, offset and stride for each of the planes

[gdk.dmabuf_texture_builder.DmabufTextureBuilder] can be used for quick one-shot construction of textures as well as kept around and reused to construct multiple textures.

For further information, see

• The Linux kernel documentation

• The header file drm_fourcc.h

The [gdk.drag.Drag] object represents the source of an ongoing DND operation.

A [gdk.drag.Drag] is created when a drag is started, and stays alive for duration of the DND operation. After a drag has been started with [gdk.drag.Drag.begin], the caller gets informed about the status of the ongoing drag operation with signals on the [gdk.drag.Drag] 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.

A [gdk.drag_surface.DragSurface] is an interface for surfaces used during DND.

The [gdk.types.DragSurfaceInterface] implementation is private to GDK.

The [gdk.drag_surface_size.DragSurfaceSize] struct contains information that is useful to compute the size of a drag surface.

Base class for objects implementing different rendering methods.

[gdk.draw_context.DrawContext] is the base object used by contexts implementing different rendering methods, such as [gdk.cairo_context.CairoContext] or [gdk.glcontext.GLContext]. It provides shared functionality between those contexts.

You will always interact with one of those subclasses.

A [gdk.draw_context.DrawContext] is always associated with a single toplevel surface.

The [gdk.drop.Drop] 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.types.EventType.DragEnter], [gdk.types.EventType.DragLeave], [gdk.types.EventType.DragMotion] and [gdk.types.EventType.DropStart]. The [gdk.drop.Drop] object can be obtained from these [gdk.event.Event] types using [gdk.dndevent.DNDEvent.getDrop].

The actual data transfer is initiated from the target side via an async read, using one of the [gdk.drop.Drop] methods for this purpose: [gdk.drop.Drop.readAsync] or [gdk.drop.Drop.readValueAsync].

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.

[gdk.event.Event]s 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 [gdk.event.Event] and its related API is rarely needed.

[gdk.event_sequence.EventSequence] is an opaque type representing a sequence of related touch events.

An opaque type representing a list of files.

An event related to a keyboard focus change.

A [gdk.frame_clock.FrameClock] 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.

[gdk.frame_clock.FrameClock] 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 [gdk.frame_clock.FrameClock.requestPhase]. 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 [gdk.frame_clock.FrameClock] class for documentation of the phases. [gdk.types.FrameClockPhase.Update] and the [gdk.frame_clock.FrameClock.update] signal are most interesting for application writers, and are used to update the animations, using the frame time given by [gdk.frame_clock.FrameClock.getFrameTime].

The frame time is reported in microseconds and generally in the same timescale as [glib.global.getMonotonicTime], however, it is not the same as [glib.global.getMonotonicTime]. 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 [gdk.frame_clock.FrameClock.getFrameTime] 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 [gdk.frame_clock.FrameClock.getFrameTime] and the value inside the [gdk.frame_clock.FrameClock.update] signal of the clock, they will stay exactly synchronized.

A [gdk.frame_timings.FrameTimings] object holds timing information for a single frame of the application’s displays.

To retrieve [gdk.frame_timings.FrameTimings] objects, use [gdk.frame_clock.FrameClock.getTimings] or [gdk.frame_clock.FrameClock.getCurrentTimings]. The information in [gdk.frame_timings.FrameTimings] 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.

[gdk.glcontext.GLContext] is an object representing a platform-specific OpenGL draw context.

[gdk.glcontext.GLContext]s are created for a surface using [gdk.surface.Surface.createGlContext], and the context will match the characteristics of the surface.

A [gdk.glcontext.GLContext] 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 func@cairo_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 [gdk.glcontext.GLContext] is platform-specific and context creation can fail, returning null context.

A [gdk.glcontext.GLContext] 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 [gdk.glcontext.GLContext] instance you need a [gdk.surface.Surface], which you typically get during the realize call of a widget.

A [gdk.glcontext.GLContext] is not realized until either [gdk.glcontext.GLContext.makeCurrent] or [gdk.glcontext.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 [gdk.surface.Surface.createGlContext] by calling [gdk.glcontext.GLContext.realize]. If the realization fails you have the option to change the settings of the [gdk.glcontext.GLContext] and try again.

Using a GdkGLContext

You will need to make the [gdk.glcontext.GLContext] 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 [gdk.glcontext.GLContext] is the current one by using [gdk.glcontext.GLContext.getCurrent]; you can also unset any [gdk.glcontext.GLContext] that is currently set by calling [gdk.glcontext.GLContext.clearCurrent].

A GdkTexture representing a GL texture object.

[gdk.gltexture_builder.GLTextureBuilder] is a builder used to construct [gdk.texture.Texture] objects from GL textures.

The operation is quite simple: Create a texture builder, set all the necessary properties - keep in mind that the properties [gdk.gltexture_builder.GLTextureBuilder.context], [gdk.gltexture_builder.GLTextureBuilder.id], [gdk.gltexture_builder.GLTextureBuilder.width], and [gdk.gltexture_builder.GLTextureBuilder.height] are mandatory - and then call [gdk.gltexture_builder.GLTextureBuilder.build] to create the new texture.

[gdk.gltexture_builder.GLTextureBuilder] can be used for quick one-shot construction of textures as well as kept around and reused to construct multiple textures.

An event related to a broken windowing system grab.

An event related to a key-based device.

A [gdk.types.KeymapKey] is a hardware key that can be mapped to a keyval.

A [gdk.texture.Texture] representing image data in memory.

[gdk.monitor.MonitorWrap] objects represent the individual outputs that are associated with a [gdk.display.Display].

[gdk.display.Display] keeps a [gio.list_model.ListModel] to enumerate and monitor monitors with [gdk.display.Display.getMonitors]. You can use [gdk.display.Display.getMonitorAtSurface] to find a particular monitor.

An event related to a pointer or touch device motion.

An event related to a pad-based device.

[gdk.paintable.Paintable] is a simple interface used by GTK to represent content that can be painted.

The content of a [gdk.paintable.Paintable] can be painted anywhere at any size without requiring any sort of layout. The interface is inspired by similar concepts elsewhere, such as

or SVG Paint Servers.

A [gdk.paintable.Paintable] can be snapshot at any time and size using [gdk.paintable.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 [gdk.paintable.Paintable] and don't know what to do, it is suggested that you scale your paintable ignoring any potential aspect ratio.

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

A [gdk.paintable.Paintable] may change its contents, meaning that it will now produce a different output with the same snapshot. Once that happens, it will call [gdk.paintable.Paintable.invalidateContents] which will emit the signal@Gdk.Paintable::invalidate-contents signal. If a paintable is known to never change its contents, it will set the [gdk.types.PaintableFlags.Contents] flag. If a consumer cannot deal with changing contents, it may call [gdk.paintable.Paintable.getCurrentImage] 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 [gdk.paintable.Paintable.invalidateSize] which will emit the signal@Gdk.Paintable::invalidate-size signal. And just like for contents, if a paintable is known to never change its size, it will set the [gdk.types.PaintableFlags.Size] flag.

Besides API for applications, there are some functions that are only useful for implementing subclasses and should not be used by applications: [gdk.paintable.Paintable.invalidateContents], [gdk.paintable.Paintable.invalidateSize], [gdk.paintable.Paintable.newEmpty].

The list of functions that can be implemented for the [gdk.paintable.Paintable] interface.

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

A [gdk.popup.Popup] is a surface that is attached to another surface.

The [gdk.popup.Popup] is positioned relative to its parent surface.

[gdk.popup.Popup]s are typically used to implement menus and similar popups. They can be modal, which is indicated by the [gdk.popup.Popup.autohide] property.

The [gdk.popup_layout.PopupLayout] struct contains information that is necessary position a [gdk.popup.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.

!Popup anchors

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.

!Flipping popups

!Sliding popups

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 [gdk.popup.Popup.getPositionX], [gdk.popup.Popup.getPositionY], [gdk.popup.Popup.getRectAnchor] and [gdk.popup.Popup.getSurfaceAnchor] after the popup has been presented. This can be used to adjust the rendering. For example, GtkPopover 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.

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

A [gdk.rgba.RGBA] is used to represent a color, in a way that is compatible with cairo’s notion of color.

[gdk.rgba.RGBA] 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.

A [gtk.types.Rectangle] data type for representing rectangles.

[gtk.types.Rectangle] is identical to [cairo.types.Rectangle]. Together with Cairo’s [cairo.region.Region] data type, these are the central types for representing sets of pixels.

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

The [cairo.region.Region] 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.

An event related to a scrolling motion.

The [gdk.seat.Seat] object represents a collection of input devices that belong to a user.

Base type for snapshot operations.

The subclass of [gdk.snapshot.Snapshot] used by GTK is GtkSnapshot.

A [gdk.surface.Surface] is a rectangular region on the screen.

It’s a low-level object, used to implement high-level objects such as GtkWindow.

The surfaces you see in practice are either [gdk.toplevel.Toplevel] or [gdk.popup.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.

[gdk.texture.Texture] 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 [gdk.texture.Texture] objects from a [gdkpixbuf.pixbuf.Pixbuf], or from bytes stored in memory, a file, or a [gio.resource.Resource].

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

[gdk.texture.Texture] is an immutable object: That means you cannot change anything about it other than increasing the reference count via [gobject.object.ObjectWrap.ref_], and consequently, it is a thread-safe object.

The [gdk.texture_downloader.TextureDownloader] is used to download the contents of a [gdk.texture.Texture].

It is intended to be created as a short-term object for a single download, but can be used for multiple downloads of different textures or with different settings.

[gdk.texture_downloader.TextureDownloader] can be used to convert data between different formats. Create a [gdk.texture.Texture] for the existing format and then download it in a different format.

A [gdk.types.TimeCoord] stores a single event in a motion history.

To check whether an axis is present, check whether the corresponding flag from the [gdk.types.AxisFlags] enumeration is set in the @flags To access individual axis values, use the values of the values of the [gdk.types.AxisUse] enumerations as indices.

A [gdk.toplevel.Toplevel] is a freestanding toplevel surface.

The [gdk.toplevel.Toplevel] 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 [gdk.toplevel_layout.ToplevelLayout] struct contains information that is necessary to present a sovereign window on screen.

The [gdk.toplevel_layout.ToplevelLayout] struct is necessary for using [gdk.toplevel.Toplevel.present].

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

The [gdk.toplevel_size.ToplevelSize] struct contains information that is useful to compute the size of a toplevel.

An event related to a touch-based device.

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.

[gdk.vulkan_context.VulkanContext] is an object representing the platform-specific Vulkan draw context.

[gdk.vulkan_context.VulkanContext]s are created for a surface using [gdk.surface.Surface.createVulkanContext], and the context will match the characteristics of the surface.

Support for [gdk.vulkan_context.VulkanContext] is platform-specific and context creation can fail, returning null context.