Used to represent native events (XEvents for the X11 backend, MSGs for Win32).

Positioning hints for aligning a window relative to a rectangle.

These hints determine how the window should be positioned in the case that the window 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 window extends beyond the left or right edges of the monitor.

If [gdk.types.AnchorHints.SlideX] is set, the window can be shifted horizontally to fit on-screen. If [gdk.types.AnchorHints.ResizeX] is set, the window 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.

An enumeration describing the way in which a device axis (valuator) maps onto the predefined valuator types that GTK+ understands.

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.

A set of values describing the possible byte-orders for storing pixel values in memory.

Specifies the crossing mode for #GdkEventCrossing.

Predefined cursors.

Note that these IDs are directly taken from the X cursor font, and many of these cursors are either not useful, or are not available on other platforms.

The recommended way to create cursors is to use [gdk.cursor.Cursor.newFromName].

A pad feature.

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

Indicates the device type. See [above][GdkDeviceManager.description] for more information about the meaning of these device types.

Used in #GdkDragContext to indicate what the destination should do with the dropped data.

Used in #GdkDragContext to the reason of a cancelled DND operation.

Used in #GdkDragContext to indicate the protocol according to which DND is done.

A set of bit-flags to indicate which events a window is to receive. Most of these masks map onto one or more of the #GdkEventType event types above.

See the [input handling overview][chap-input-handling] for details of [event masks][event-masks] and [event propagation][event-propagation].

[gdk.types.EventMask.PointerMotionHintMask] is deprecated. It is a special mask to reduce the number of [gdk.types.EventType.MotionNotify] events received. When using [gdk.types.EventMask.PointerMotionHintMask], fewer [gdk.types.EventType.MotionNotify] events will be sent, some of which are marked as a hint (the is_hint member is true). To receive more motion events after a motion hint event, the application needs to asks for more, by calling [gdk.event.Event.requestMotions].

Since GTK 3.8, motion events are already compressed by default, independent of this mechanism. This compression can be disabled with [gdk.window.Window.setEventCompression]. See the documentation of that function for details.

If [gdk.types.EventMask.TouchMask] is enabled, the window will receive touch events from touch-enabled devices. Those will come as sequences of #GdkEventTouch with type [gdk.types.EventType.TouchUpdate], enclosed by two events with type [gdk.types.EventType.TouchBegin] and [gdk.types.EventType.TouchEnd] (or [gdk.types.EventType.TouchCancel]). [gdk.event.Event.getEventSequence] returns the event sequence for these events, so different sequences may be distinguished.

Specifies the type of the event.

Do not confuse these events with the signals that GTK+ widgets emit. Although many of these events result in corresponding signals being emitted, the events are often transformed or filtered along the way.

In some language bindings, the values [gdk.types.EventType._2buttonPress] and [gdk.types.EventType._3buttonPress] would translate into something syntactically invalid (eg Gdk.EventType.2ButtonPress, where a symbol is not allowed to start with a number). In that case, the aliases [gdk.types.EventType.DoubleButtonPress] and [gdk.types.EventType.TripleButtonPress] can be used instead.

Specifies the result of applying a #GdkFilterFunc to a native event.

#GdkFrameClockPhase is used to represent the different paint clock phases that can be requested. The elements of the enumeration correspond to the signals of #GdkFrameClock.

Indicates which monitor (in a multi-head setup) a window should span over when in fullscreen mode.

Error enumeration for #GdkGLContext.

Defines how device grabs interact with other devices.

Returned by [gdk.device.Device.grab], [gdk.global.pointerGrab] and [gdk.global.keyboardGrab] to indicate success or the reason for the failure of the grab attempt.

Defines the reference point of a window and the meaning of coordinates passed to [gtk.window.Window.move]. See [gtk.window.Window.move] and the "implementation notes" section of the

specification for more details.

An enumeration that describes the mode of an input device.

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

This enum is used with [gdk.keymap.Keymap.getModifierMask] in order to determine what modifiers the currently used windowing system backend uses for particular purposes. For example, on X11/Windows, the Control key is used for invoking menu shortcuts (accelerators), whereas on Apple computers it’s the Command key (which correspond to [gdk.types.ModifierType.ControlMask] and [gdk.types.ModifierType.Mod2Mask], respectively).

A set of bit-flags to indicate the state of modifier keys and mouse buttons in various event types. Typical modifier keys are Shift, Control, Meta, Super, Hyper, Alt, Compose, Apple, CapsLock or ShiftLock.

Like the X Window System, GDK supports 8 modifier keys and 5 mouse buttons.

Since 2.10, GDK recognizes which of the Meta, Super or Hyper keys are mapped to Mod2 - Mod5, and indicates this by setting [gdk.types.ModifierType.SuperMask], [gdk.types.ModifierType.HyperMask] or [gdk.types.ModifierType.MetaMask] in the state field of key events.

Note that GDK may add internal values to events which include reserved values such as [gdk.types.ModifierType.ModifierReserved13Mask]. Your code should preserve and ignore them. You can use [gdk.types.MODIFIER_MASK] to remove all reserved values.

Also note that the GDK X backend interprets button press events for button 4-7 as scroll events, so [gdk.types.ModifierType.Button4Mask] and [gdk.types.ModifierType.Button5Mask] will never be set.

Specifies the kind of crossing for #GdkEventCrossing.

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

Specifies why a selection ownership was changed.

Describes how existing data is combined with new data when using [gdk.global.propertyChange].

Specifies the type of a property change for a #GdkEventProperty.

Specifies the direction for #GdkEventScroll.

Flags describing the seat capabilities.

Specifies the kind of modification applied to a setting in a #GdkEventSetting.

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

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.

See also #GdkEventTouchpadSwipe and #GdkEventTouchpadPinch.

Specifies the visiblity status of a window for a #GdkEventVisibility.

A set of values that describe the manner in which the pixel values for a visual are converted into RGB values for display.

These are hints originally defined by the Motif toolkit. The window manager can use them when determining how to decorate the window. The hint must be set before mapping the window.

These are hints originally defined by the Motif toolkit. The window manager can use them when determining the functions to offer for the window. The hint must be set before mapping the window.

Used to indicate which fields in the #GdkWindowAttr struct should be honored. For example, if you filled in the “cursor” and “x” fields of #GdkWindowAttr, pass “@GDK_WA_X | @GDK_WA_CURSOR” to [gdk.window.Window.new_]. Fields in #GdkWindowAttr not covered by a bit in this enum are required; for example, the @width/@height, @wclass, and @window_type fields are required, they have no corresponding flag in #GdkWindowAttributesType.

Determines a window edge or corner.

Used to indicate which fields of a #GdkGeometry struct should be paid attention to. Also, the presence/absence of @GDK_HINT_POS, @GDK_HINT_USER_POS, and @GDK_HINT_USER_SIZE is significant, though they don't directly refer to #GdkGeometry fields. @GDK_HINT_USER_POS will be set automatically by #GtkWindow if you call [gtk.window.Window.move]. @GDK_HINT_USER_POS and @GDK_HINT_USER_SIZE should be set if the user specified a size/position using a --geometry command-line argument; [gtk.window.Window.parseGeometry] automatically sets these flags.

Specifies the state of a toplevel window.

Describes the kind of window.

These are hints for the window manager that indicate what type of function the window has. The window manager can use this when determining decoration and behaviour of the window. The hint must be set before mapping the window.

See the Extended Window Manager Hints specification for more details about window types.

@GDK_INPUT_OUTPUT windows are the standard kind of window you might expect. Such windows receive events and are also displayed on screen. @GDK_INPUT_ONLY windows are invisible; they are usually placed above other windows in order to trap or filter the events. You can’t draw on @GDK_INPUT_ONLY windows.

GdkAppLaunchContext is an implementation of #GAppLaunchContext that handles launching an application in a graphical context. It 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_screen (screen);
gdk_app_launch_context_set_timestamp (event->time);

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 opaque type representing a string as an index into a table of strings on the X server.

A #GdkColor is used to describe a color, similar to the XColor struct used in the X11 drawing API.

A #GdkCursor represents a cursor. Its contents are private.

The #GdkDevice object represents a single input device, such as a keyboard, a mouse, a touchpad, etc.

See the #GdkDeviceManager documentation for more information about the various kinds of master and slave devices, and their relationships.

In addition to a single pointer and keyboard for user interface input, GDK contains support for a variety of input devices, including graphics tablets, touchscreens and multiple pointers/keyboards interacting simultaneously with the user interface. Such input devices often have additional features, such as sub-pixel positioning information and additional device-dependent information.

In order to query the device hierarchy and be aware of changes in the device hierarchy (such as virtual devices being created or removed, or physical devices being plugged or unplugged), GDK provides #GdkDeviceManager.

By default, and if the platform supports it, GDK is aware of multiple keyboard/pointer pairs and multitouch devices. This behavior can be changed by calling [gdk.global.disableMultidevice] before [gdk.display.Display.open]. There should rarely be a need to do that though, since GDK defaults to a compatibility mode in which it will emit just one enter/leave event pair for all devices on a window. To enable per-device enter/leave events and other multi-pointer interaction features, [gdk.window.Window.setSupportMultidevice] must be called on #GdkWindows (or [gtk.widget.Widget.setSupportMultidevice] on widgets). window. See the [gdk.window.Window.setSupportMultidevice] documentation for more information.

On X11, multi-device support is implemented through XInput 2. Unless [gdk.global.disableMultidevice] is called, the XInput 2 #GdkDeviceManager implementation will be used as the input source. Otherwise either the core or XInput 1 implementations will be used.

For simple applications that don’t have any special interest in input devices, the so-called “client pointer” provides a reasonable approximation to a simple setup with a single pointer and keyboard. The device that has been set as the client pointer can be accessed via [gdk.device_manager.DeviceManager.getClientPointer].

Conceptually, in multidevice mode there are 2 device types. Virtual devices (or master devices) are represented by the pointer cursors and keyboard foci that are seen on the screen. Physical devices (or slave devices) represent the hardware that is controlling the virtual devices, and thus have no visible cursor on the screen.

Virtual devices are always paired, so there is a keyboard device for every pointer device. Associations between devices may be inspected through [gdk.device.Device.getAssociatedDevice].

There may be several virtual devices, and several physical devices could be controlling each of these virtual devices. Physical devices may also be “floating”, which means they are not attached to any virtual device.

Master and slave devices

carlos@sacarino:~$ xinput list
⎡ Virtual core pointer                          id=2    [master pointer  (3)]
⎜   ↳ Virtual core XTEST pointer                id=4    [slave  pointer  (2)]
⎜   ↳ Wacom ISDv4 E6 Pen stylus                 id=10   [slave  pointer  (2)]
⎜   ↳ Wacom ISDv4 E6 Finger touch               id=11   [slave  pointer  (2)]
⎜   ↳ SynPS/2 Synaptics TouchPad                id=13   [slave  pointer  (2)]
⎜   ↳ TPPS/2 IBM TrackPoint                     id=14   [slave  pointer  (2)]
⎜   ↳ Wacom ISDv4 E6 Pen eraser                 id=16   [slave  pointer  (2)]
⎣ Virtual core keyboard                         id=3    [master keyboard (2)]
   ↳ Virtual core XTEST keyboard               id=5    [slave  keyboard (3)]
   ↳ Power Button                              id=6    [slave  keyboard (3)]
   ↳ Video Bus                                 id=7    [slave  keyboard (3)]
   ↳ Sleep Button                              id=8    [slave  keyboard (3)]
   ↳ Integrated Camera                         id=9    [slave  keyboard (3)]
   ↳ AT Translated Set 2 keyboard              id=12   [slave  keyboard (3)]
   ↳ ThinkPad Extra Buttons                    id=15   [slave  keyboard (3)]

By default, GDK will automatically listen for events coming from all master devices, setting the #GdkDevice for all events coming from input devices. Events containing device information are #GDK_MOTION_NOTIFY, #GDK_BUTTON_PRESS, #GDK_2BUTTON_PRESS, #GDK_3BUTTON_PRESS, #GDK_BUTTON_RELEASE, #GDK_SCROLL, #GDK_KEY_PRESS, #GDK_KEY_RELEASE, #GDK_ENTER_NOTIFY, #GDK_LEAVE_NOTIFY, #GDK_FOCUS_CHANGE, #GDK_PROXIMITY_IN, #GDK_PROXIMITY_OUT, #GDK_DRAG_ENTER, #GDK_DRAG_LEAVE, #GDK_DRAG_MOTION, #GDK_DRAG_STATUS, #GDK_DROP_START, #GDK_DROP_FINISHED and #GDK_GRAB_BROKEN. When dealing with an event on a master device, it is possible to get the source (slave) device that the event originated from via [gdk.event.Event.getSourceDevice].

On a standard session, all physical devices are connected by default to the "Virtual Core Pointer/Keyboard" master devices, hence routing all events through these. This behavior is only modified by device grabs, where the slave device is temporarily detached for as long as the grab is held, and more permanently by user modifications to the device hierarchy.

On certain application specific setups, it may make sense to detach a physical device from its master pointer, and mapping it to an specific window. This can be achieved by the combination of [gdk.device.Device.grab] and [gdk.device.Device.setMode].

In order to listen for events coming from devices other than a virtual device, [gdk.window.Window.setDeviceEvents] must be called. Generally, this function can be used to modify the event mask for any given device.

Input devices may also provide additional information besides X/Y. For example, graphics tablets may also provide pressure and X/Y tilt information. This information is device-dependent, and may be queried through [gdk.device.Device.getAxis]. In multidevice mode, virtual devices will change axes in order to always represent the physical device that is routing events through it. Whenever the physical device changes, the #GdkDevice:n-axes property will be notified, and [gdk.device.Device.listAxes] will return the new device axes.

Devices may also have associated “keys” or macro buttons. Such keys can be globally set to map into normal X keyboard events. The mapping is set using [gdk.device.Device.setKey].

In GTK+ 3.20, a new #GdkSeat object has been introduced that supersedes #GdkDeviceManager and should be preferred in newly written code.

#GdkDevicePad 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 the #GdkEventPadGroupMode event.

#GdkDisplay objects purpose are two fold:

• To manage and provide information about input devices (pointers and keyboards)

• To manage and provide information about the available #GdkScreens

GdkDisplay objects are the GDK representation of an X Display, which can be described as a workstation consisting of a keyboard, a pointing device (such as a mouse) and one or more screens. It is used to open and keep track of various GdkScreen objects currently instantiated by the application. It is also used to access the keyboard(s) and mouse pointer(s) of the display.

Most of the input device handling has been factored out into the separate #GdkDeviceManager object. Every display has a device manager, which you can obtain using [gdk.display.Display.getDeviceManager].

The purpose of the #GdkDisplayManager singleton object is to offer notification when displays appear or disappear or the default display changes.

You can use [gdk.display_manager.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.

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:

Backend-specific code ## {#backend-specific}

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

#GdkDrawingContext is an object that represents the current drawing state of a #GdkWindow.

It's possible to use a #GdkDrawingContext to draw on a #GdkWindow via rendering API like Cairo or OpenGL.

A #GdkDrawingContext can only be created by calling [gdk.window.Window.beginDrawFrame] and will be valid until a call to [gdk.window.Window.endDrawFrame].

#GdkDrawingContext is available since GDK 3.22

A #GdkEvent contains a union of all of the event types, and allows access to the data fields in a number of ways.

The event type is always the first field in all of the event types, and can always be accessed with the following code, no matter what type of event it is:

GdkEvent *event;
 GdkEventType type;

 type = event->type;

To access other fields of the event, the pointer to the event can be cast to the appropriate event type, or the union member name can be used. For example if the event type is [gdk.types.EventType.ButtonPress] then the x coordinate of the button press can be accessed with:

GdkEvent *event;
 gdouble x;

 x = ((GdkEventButton*)event)->x;

GdkEvent *event;
 gdouble x;

 x = event->button.x;

Contains the fields which are common to all event structs. Any event pointer can safely be cast to a pointer to a #GdkEventAny to access these fields.

Used for button press and button release events. The @type field will be one of [gdk.types.EventType.ButtonPress], [gdk.types.EventType._2buttonPress], [gdk.types.EventType._3buttonPress] or [gdk.types.EventType.ButtonRelease],

Double and triple-clicks result in a sequence of events being received. For double-clicks the order of events will be:

• [gdk.types.EventType.ButtonPress]
• [gdk.types.EventType.ButtonRelease]
• [gdk.types.EventType.ButtonPress]
• [gdk.types.EventType._2buttonPress]
• [gdk.types.EventType.ButtonRelease]

Note that the first click is received just like a normal button press, while the second click results in a [gdk.types.EventType._2buttonPress] being received just after the [gdk.types.EventType.ButtonPress].

Triple-clicks are very similar to double-clicks, except that [gdk.types.EventType._3buttonPress] is inserted after the third click. The order of the events is:

• [gdk.types.EventType.ButtonPress]
• [gdk.types.EventType.ButtonRelease]
• [gdk.types.EventType.ButtonPress]
• [gdk.types.EventType._2buttonPress]
• [gdk.types.EventType.ButtonRelease]
• [gdk.types.EventType.ButtonPress]
• [gdk.types.EventType._3buttonPress]
• [gdk.types.EventType.ButtonRelease]

For a double click to occur, the second button press must occur within 1/4 of a second of the first. For a triple click to occur, the third button press must also occur within 1/2 second of the first button press.

Generated when a window size or position has changed.

Generated when the pointer enters or leaves a window.

Generated during DND operations.

Generated when all or part of a window becomes visible and needs to be redrawn.

Describes a change of keyboard focus.

Generated when a pointer or keyboard grab is broken. On X11, this happens when the grab window becomes unviewable (i.e. it or one of its ancestors is unmapped), or if the same application grabs the pointer or keyboard again. Note that implicit grabs (which are initiated by button presses) can also cause #GdkEventGrabBroken events.

Describes a key press or key release event.

Generated when the pointer moves.

Generated when the owner of a selection changes. On X11, this information is only available if the X server supports the XFIXES extension.

Generated during [gdk.types.InputSource.TabletPad] interaction with tactile sensors.

Generated during [gdk.types.InputSource.TabletPad] button presses and releases.

Generated during [gdk.types.InputSource.TabletPad] mode switches in a group.

Describes a property change on a window.

Proximity events are generated when using GDK’s wrapper for the XInput extension. The XInput extension is an add-on for standard X that allows you to use nonstandard devices such as graphics tablets. A proximity event indicates that the stylus has moved in or out of contact with the tablet, or perhaps that the user’s finger has moved in or out of contact with a touch screen.

This event type will be used pretty rarely. It only is important for XInput aware programs that are drawing their own cursor.

Generated from button presses for the buttons 4 to 7. Wheel mice are usually configured to generate button press events for buttons 4 and 5 when the wheel is turned.

Some GDK backends can also generate “smooth” scroll events, which can be recognized by the [gdk.types.ScrollDirection.Smooth] scroll direction. For these, the scroll deltas can be obtained with [gdk.event.Event.getScrollDeltas].

Generated when a selection is requested or ownership of a selection is taken over by another client application.

Generated when a setting is modified.

Used for touch events. @type field will be one of [gdk.types.EventType.TouchBegin], [gdk.types.EventType.TouchUpdate], [gdk.types.EventType.TouchEnd] or [gdk.types.EventType.TouchCancel].

Touch events are grouped into sequences by means of the @sequence field, which can also be obtained with [gdk.event.Event.getEventSequence]. Each sequence begins with a [gdk.types.EventType.TouchBegin] event, followed by any number of [gdk.types.EventType.TouchUpdate] events, and ends with a [gdk.types.EventType.TouchEnd] (or [gdk.types.EventType.TouchCancel]) event. With multitouch devices, there may be several active sequences at the same time.

Generated during touchpad swipe gestures.

Generated during touchpad swipe gestures.

Generated when the window visibility status has changed.

Generated when the state of a toplevel window changes.

A #GdkFrameClock tells the application when to update and repaint a window. 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 [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 #GdkFrameClock class for documentation of the phases. [gdk.types.FrameClockPhase.Update] and the #GdkFrameClock::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 #GdkFrameClock::update signal of the clock, they will stay exactly synchronized.

A #GdkFrameTimings object holds timing information for a single frame of the application’s displays. To retrieve #GdkFrameTimings objects, use [gdk.frame_clock.FrameClock.getTimings] or [gdk.frame_clock.FrameClock.getCurrentTimings]. 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.

#GdkGLContext is an object representing the platform-specific OpenGL drawing context.

#GdkGLContexts are created for a #GdkWindow using [gdk.window.Window.createGlContext], and the context will match the #GdkVisual of the window.

A #GdkGLContext is not tied to any particular normal framebuffer. For instance, it cannot draw to the #GdkWindow 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 [gdk.global.cairoDrawFromGl] 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, context creation can fail, returning null 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 #GdkWindow, which you typically get during the realize call of a widget.

A #GdkGLContext is not realized until either [gdk.glcontext.GLContext.makeCurrent], or until it is realized using [gdk.glcontext.GLContext.realize]. 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.window.Window.createGlContext] by calling [gdk.glcontext.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 [gdk.glcontext.GLContext.getCurrent]; you can also unset any #GdkGLContext that is currently set by calling [gdk.glcontext.GLContext.clearCurrent].

The #GdkGeometry struct gives the window manager information about a window’s geometry constraints. Normally you would set these on the GTK+ level using [gtk.window.Window.setGeometryHints]. #GtkWindow then sets the hints on the #GdkWindow it creates.

[gdk.window.Window.setGeometryHints] expects the hints to be fully valid already and simply passes them to the window manager; in contrast, [gtk.window.Window.setGeometryHints] performs some interpretation. For example, #GtkWindow will apply the hints to the geometry widget instead of the toplevel window, if you set a geometry widget. Also, the @min_width/@min_height/@max_width/@max_height fields may be set to -1, and #GtkWindow will substitute the size request of the window or geometry widget. If the minimum size hint is not provided, #GtkWindow will use its requisition as the minimum size. If the minimum size is provided and a geometry widget is set, #GtkWindow will take the minimum size as the minimum size of the geometry widget rather than the entire window. The base size is treated similarly.

The canonical use-case for [gtk.window.Window.setGeometryHints] is to get a terminal widget to resize properly. Here, the terminal text area should be the geometry widget; #GtkWindow will then automatically set the base size to the size of other widgets in the terminal window, such as the menubar and scrollbar. Then, the @width_inc and @height_inc fields should be set to the size of one character in the terminal. Finally, the base size should be set to the size of one character. The net effect is that the minimum size of the terminal will have a 1x1 character terminal area, and only terminal sizes on the “character grid” will be allowed.

Here’s an example of how the terminal example would be implemented, assuming a terminal area widget called “terminal” and a toplevel window “toplevel”:

GdkGeometry hints;

	hints.base_width = terminal->char_width;
       hints.base_height = terminal->char_height;
       hints.min_width = terminal->char_width;
       hints.min_height = terminal->char_height;
       hints.width_inc = terminal->char_width;
       hints.height_inc = terminal->char_height;

gtk_window_set_geometry_hints (GTK_WINDOW (toplevel),
                               GTK_WIDGET (terminal),
                               &hints,
                               GDK_HINT_RESIZE_INC |
                               GDK_HINT_MIN_SIZE |
                               GDK_HINT_BASE_SIZE);

The other useful fields are the @min_aspect and @max_aspect fields; these contain a width/height ratio as a floating point number. If a geometry widget is set, the aspect applies to the geometry widget rather than the entire window. The most common use of these hints is probably to set @min_aspect and @max_aspect to the same value, thus forcing the window to keep a constant aspect ratio.

A #GdkKeymap defines the translation from keyboard state (including a hardware key, a modifier mask, and active keyboard group) to a keyval. This translation has two phases. The first phase is to determine the effective keyboard group and level for the keyboard state; the second phase is to look up the keycode/group/level triplet in the keymap and see what keyval it corresponds to.

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

GdkMonitor objects represent the individual outputs that are associated with a #GdkDisplay. GdkDisplay has APIs to enumerate monitors with [gdk.display.Display.getNMonitors] and [gdk.display.Display.getMonitor], and to find particular monitors with [gdk.display.Display.getPrimaryMonitor] or [gdk.display.Display.getMonitorAtWindow].

GdkMonitor was introduced in GTK+ 3.22 and supersedes earlier APIs in GdkScreen to obtain monitor-related information.

Defines the x and y coordinates of a point.

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

Defines the position and size of a rectangle. It is identical to #cairo_rectangle_int_t.

#GdkScreen objects are the GDK representation of the screen on which windows can be displayed and on which the pointer moves. X originally identified screens with physical screens, but nowadays it is more common to have a single #GdkScreen which combines several physical monitors (see [gdk.screen.Screen.getNMonitors]).

GdkScreen is used throughout GDK and GTK+ to specify which screen the top level windows are to be displayed on. it is also used to query the screen specification and default settings such as the default visual ([gdk.screen.Screen.getSystemVisual]), the dimensions of the physical monitors ([gdk.screen.Screen.getMonitorGeometry]), etc.

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

A #GdkTimeCoord stores a single event in a motion history.

A #GdkVisual contains information about a particular visual.

Attributes to use for a newly-created window.