Functions -

Gdk 3.0 ([original](https://lazka.github.io/pgi-docs/Gdk-3.0/functions.html)) ([raw](?raw))
add_option_entries_libgtk_only (group)
atom_intern (atom_name, only_if_exists)
atom_intern_static_string (atom_name)
beep ()
cairo_create (window)
cairo_draw_from_gl (cr, window, source, source_type, buffer_scale, x, y, width, height)
cairo_get_clip_rectangle (cr)
cairo_get_drawing_context (cr)
cairo_rectangle (cr, rectangle)
cairo_region (cr, region)
cairo_region_create_from_surface (surface)
cairo_set_source_color (cr, color)
cairo_set_source_pixbuf (cr, pixbuf, pixbuf_x, pixbuf_y)
cairo_set_source_rgba (cr, rgba)
cairo_set_source_window (cr, window, x, y)
cairo_surface_create_from_pixbuf (pixbuf, scale, for_window)
color_parse (spec)
disable_multidevice ()
drag_abort (context, time_)
drag_begin (window, targets)
drag_begin_for_device (window, device, targets)
drag_begin_from_point (window, device, targets, x_root, y_root)
drag_drop (context, time_)
drag_drop_done (context, success)
drag_drop_succeeded (context)
drag_find_window_for_screen (context, drag_window, screen, x_root, y_root)
drag_get_selection (context)
drag_motion (context, dest_window, protocol, x_root, y_root, suggested_action, possible_actions, time_)
drag_status (context, action, time_)
drop_finish (context, success, time_)
drop_reply (context, accepted, time_)
error_trap_pop ()
error_trap_pop_ignored ()
error_trap_push ()
event_get ()
event_handler_set (func, *data)
event_peek ()
event_request_motions (event)
events_get_angle (event1, event2)
events_get_center (event1, event2)
events_get_distance (event1, event2)
events_pending ()
flush ()
get_default_root_window ()
get_display ()
get_display_arg_name ()
get_program_class ()
get_show_events ()
gl_error_quark ()
init (argv)
init_check (argv)
keyboard_grab (window, owner_events, time_)
keyboard_ungrab (time_)
keyval_convert_case (symbol)
keyval_from_name (keyval_name)
keyval_is_lower (keyval)
keyval_is_upper (keyval)
keyval_name (keyval)
keyval_to_lower (keyval)
keyval_to_unicode (keyval)
keyval_to_upper (keyval)
list_visuals ()
notify_startup_complete ()
notify_startup_complete_with_id (startup_id)
offscreen_window_get_embedder (window)
offscreen_window_get_surface (window)
offscreen_window_set_embedder (window, embedder)
pango_context_get ()
pango_context_get_for_display (display)
pango_context_get_for_screen (screen)
parse_args (argv)
pixbuf_get_from_surface (surface, src_x, src_y, width, height)
pixbuf_get_from_window (window, src_x, src_y, width, height)
pointer_grab (window, owner_events, event_mask, confine_to, cursor, time_)
pointer_is_grabbed ()
pointer_ungrab (time_)
pre_parse_libgtk_only ()
property_delete (window, property)
property_get (window, property, type, offset, length, pdelete)
query_depths ()
query_visual_types ()
rectangle_intersect (src2)
rectangle_union (src2)
selection_convert (requestor, selection, target, time_)
selection_owner_get (selection)
selection_owner_get_for_display (display, selection)
selection_owner_set (owner, selection, time_, send_event)
selection_owner_set_for_display (display, owner, selection, time_, send_event)
selection_send_notify (requestor, selection, target, property, time_)
selection_send_notify_for_display (display, requestor, selection, target, property, time_)
set_allowed_backends (backends)
set_double_click_time (msec)
set_program_class (program_class)
set_show_events (show_events)
setting_get (name, value)
synthesize_window_state (window, unset_flags, set_flags)
test_render_sync (window)
test_simulate_button (window, x, y, button, modifiers, button_pressrelease)
test_simulate_key (window, x, y, keyval, modifiers, key_pressrelease)
text_property_to_utf8_list_for_display (display, encoding, format, text)
threads_add_idle (priority, function, *data)
threads_add_timeout (priority, interval, function, *data)
threads_add_timeout_seconds (priority, interval, function, *data)
threads_enter ()
threads_init ()
threads_leave ()
unicode_to_keyval (wc)
utf8_to_string_target (str)

Details

Gdk.add_option_entries_libgtk_only(group)[source]

Parameters:

group (GLib.OptionGroup) – An option group.

Appends gdk option entries to the passed in option group. This is not public API and must not be used by applications.

Deprecated since version 3.16: This symbol was never meant to be used outside of GTK+

Gdk.atom_intern(atom_name, only_if_exists)[source]

Parameters:

Returns:

the atom corresponding to atom_name.

Return type:

Gdk.Atom

Finds or creates an atom corresponding to a given string.

Gdk.atom_intern_static_string(atom_name)[source]

Parameters:

atom_name (str) – a static string

Returns:

the atom corresponding to atom_name

Return type:

Gdk.Atom

Finds or creates an atom corresponding to a given string.

Note that this function is identical to Gdk.Atom.intern() except that if a new Gdk.Atom is created the string itself is used rather than a copy. This saves memory, but can only be used if the string will always exist. It can be used with statically allocated strings in the main program, but not with statically allocated memory in dynamically loaded modules, if you expect to ever unload the module again (e.g. do not use this function in GTK+ theme engines).

New in version 2.10.

Gdk.beep()[source]

Emits a short beep on the default display.

Gdk.cairo_create(window)[source]

Parameters:

window (Gdk.Window) – a Gdk.Window

Returns:

A newly created Cairo context. Free with cairo_destroy() when you are done drawing.

Return type:

cairo.Context

Creates a Cairo context for drawing to window.

Note that calling cairo.Context.reset_clip() on the resulting cairo.Context will produce undefined results, so avoid it at all costs.

Typically, this function is used to draw on a Gdk.Window out of the paint cycle of the toolkit; this should be avoided, as it breaks various assumptions and optimizations.

If you are drawing on a native Gdk.Window in response to a Gdk.EventType.EXPOSE event you should use Gdk.Window.begin_draw_frame() and Gdk.DrawingContext.get_cairo_context() instead. GTK will automatically do this for you when drawing a widget.

New in version 2.8.

Gdk.cairo_draw_from_gl(cr, window, source, source_type, buffer_scale, x, y, width, height)[source]

Parameters:

This is the main way to draw GL content in GTK+. It takes a render buffer ID (source_type == #GL_RENDERBUFFER) or a texture id (source_type == #GL_TEXTURE) and draws it onto cr with an OVER operation, respecting the current clip. The top left corner of the rectangle specified by x, y, width and heightwill be drawn at the current (0,0) position of the cairo.Context.

This will work for *all* cairo.Context, as long as window is realized, but the fallback implementation that reads back the pixels from the buffer may be used in the general case. In the case of direct drawing to a window with no special effects applied to cr it will however use a more efficient approach.

For #GL_RENDERBUFFER the code will always fall back to software for buffers with alpha components, so make sure you use #GL_TEXTURE if using alpha.

Calling this may change the current GL context.

New in version 3.16.

Gdk.cairo_get_clip_rectangle(cr)[source]

Parameters:

cr (cairo.Context) – a cairo context

Returns:

True if a clip rectangle exists, False if all of cr is clipped and all drawing can be skipped

rect:

return location for the clip, or None

Return type:

(bool, rect: Gdk.Rectangle)

This is a convenience function around cairo.Context.clip_extents(). It rounds the clip extents to integer coordinates and returns a boolean indicating if a clip area exists.

Gdk.cairo_get_drawing_context(cr)[source]

Parameters:

cr (cairo.Context) – a Cairo context

Returns:

a Gdk.DrawingContext, if any is set

Return type:

Gdk.DrawingContext or None

Retrieves the Gdk.DrawingContext that created the Cairo context cr.

New in version 3.22.

Gdk.cairo_rectangle(cr, rectangle)[source]

Parameters:

Adds the given rectangle to the current path of cr.

New in version 2.8.

Gdk.cairo_region(cr, region)[source]

Parameters:

Adds the given region to the current path of cr.

New in version 2.8.

Gdk.cairo_region_create_from_surface(surface)[source]

Parameters:

surface (cairo.Surface) – a cairo surface

Returns:

A cairo.Region; must be freed with cairo_region_destroy()

Return type:

cairo.Region

Creates region that describes covers the area where the givensurface is more than 50% opaque.

This function takes into account device offsets that might be set with cairo.Surface.set_device_offset().

Gdk.cairo_set_source_color(cr, color)[source]

Parameters:

Sets the specified Gdk.Color as the source color of cr.

New in version 2.8.

Deprecated since version 3.4: Use Gdk.cairo_set_source_rgba() instead

Gdk.cairo_set_source_pixbuf(cr, pixbuf, pixbuf_x, pixbuf_y)[source]

Parameters:

Sets the given pixbuf as the source pattern for cr.

The pattern has an extend mode of cairo.Extend.NONE and is aligned so that the origin of pixbuf is pixbuf_x, pixbuf_y.

New in version 2.8.

Gdk.cairo_set_source_rgba(cr, rgba)[source]

Parameters:

Sets the specified Gdk.RGBA as the source color of cr.

New in version 3.0.

Gdk.cairo_set_source_window(cr, window, x, y)[source]

Parameters:

Sets the given window as the source pattern for cr.

The pattern has an extend mode of cairo.Extend.NONE and is aligned so that the origin of window is x, y. The window contains all its subwindows when rendering.

Note that the contents of window are undefined outside of the visible part of window, so use this function with care.

New in version 2.24.

Gdk.cairo_surface_create_from_pixbuf(pixbuf, scale, for_window)[source]

Parameters:

Returns:

a new cairo surface, must be freed with cairo_surface_destroy()

Return type:

cairo.Surface

Creates an image surface with the same contents as the pixbuf.

New in version 3.10.

Gdk.color_parse(spec)[source]

Parameters:

spec (str) – the string specifying the color

Returns:

Gdk.Color or None if the parsing didn’t succeed

Return type:

Gdk.Color or None

Deprecated since version 3.14: Use Gdk.RGBA

Gdk.disable_multidevice()[source]

Disables multidevice support in GDK. This call must happen prior to Gdk.Display.open(), gtk_init(), gtk_init_with_args() or gtk_init_check() in order to take effect.

Most common GTK+ applications won’t ever need to call this. Only applications that do mixed GDK/Xlib calls could want to disable multidevice support if such Xlib code deals with input devices in any way and doesn’t observe the presence of XInput 2.

New in version 3.0.

Gdk.drag_abort(context, time_)[source]

Parameters:

Aborts a drag without dropping.

This function is called by the drag source.

This function does not need to be called in managed drag and drop operations. See Gdk.DragContext.manage_dnd() for more information.

Gdk.drag_begin(window, targets)[source]

Parameters:

Returns:

a newly created Gdk.DragContext

Return type:

Gdk.DragContext

Starts a drag and creates a new drag context for it. This function assumes that the drag is controlled by the client pointer device, use Gdk.drag_begin_for_device() to begin a drag with a different device.

This function is called by the drag source.

Gdk.drag_begin_for_device(window, device, targets)[source]

Parameters:

Returns:

a newly created Gdk.DragContext

Return type:

Gdk.DragContext

Starts a drag and creates a new drag context for it.

This function is called by the drag source.

Gdk.drag_begin_from_point(window, device, targets, x_root, y_root)[source]

Parameters:

Returns:

a newly created Gdk.DragContext

Return type:

Gdk.DragContext

Starts a drag and creates a new drag context for it.

This function is called by the drag source.

New in version 3.20.

Gdk.drag_drop(context, time_)[source]

Parameters:

Drops on the current destination.

This function is called by the drag source.

This function does not need to be called in managed drag and drop operations. See Gdk.DragContext.manage_dnd() for more information.

Gdk.drag_drop_done(context, success)[source]

Parameters:

Inform GDK if the drop ended successfully. Passing Falsefor success may trigger a drag cancellation animation.

This function is called by the drag source, and should be the last call before dropping the reference to thecontext.

The Gdk.DragContext will only take the first Gdk.drag_drop_done() call as effective, if this function is called multiple times, all subsequent calls will be ignored.

New in version 3.20.

Gdk.drag_drop_succeeded(context)[source]

Parameters:

context (Gdk.DragContext) – a Gdk.DragContext

Returns:

True if the drop was successful.

Return type:

bool

Returns whether the dropped data has been successfully transferred. This function is intended to be used while handling a Gdk.EventType.DROP_FINISHED event, its return value is meaningless at other times.

New in version 2.6.

Gdk.drag_find_window_for_screen(context, drag_window, screen, x_root, y_root)[source]

Parameters:

Returns:

dest_window:

location to store the destination window in

protocol:

location to store the DND protocol in

Return type:

(dest_window: Gdk.Window, protocol: Gdk.DragProtocol)

Finds the destination window and DND protocol to use at the given pointer position.

This function is called by the drag source to obtain thedest_window and protocol parameters for Gdk.drag_motion().

New in version 2.2.

Gdk.drag_get_selection(context)[source]

Parameters:

context (Gdk.DragContext) – a Gdk.DragContext.

Returns:

the selection atom, or %GDK_NONE

Return type:

Gdk.Atom

Returns the selection atom for the current source window.

Gdk.drag_motion(context, dest_window, protocol, x_root, y_root, suggested_action, possible_actions, time_)[source]

Parameters:

Return type:

bool

Updates the drag context when the pointer moves or the set of actions changes.

This function is called by the drag source.

This function does not need to be called in managed drag and drop operations. See Gdk.DragContext.manage_dnd() for more information.

Gdk.drag_status(context, action, time_)[source]

Parameters:

Selects one of the actions offered by the drag source.

This function is called by the drag destination in response toGdk.drag_motion() called by the drag source.

Gdk.drop_finish(context, success, time_)[source]

Parameters:

Ends the drag operation after a drop.

This function is called by the drag destination.

Gdk.drop_reply(context, accepted, time_)[source]

Parameters:

Accepts or rejects a drop.

This function is called by the drag destination in response to a drop initiated by the drag source.

Gdk.error_trap_pop()[source]

Returns:

X error code or 0 on success

Return type:

int

Removes an error trap pushed with Gdk.error_trap_push(). May block until an error has been definitively received or not received from the X server. Gdk.error_trap_pop_ignored() is preferred if you don’t need to know whether an error occurred, because it never has to block. If you don’t need the return value of Gdk.error_trap_pop(), useGdk.error_trap_pop_ignored().

Prior to GDK 3.0, this function would not automatically sync for you, so you had to Gdk.flush() if your last call to Xlib was not a blocking round trip.

Gdk.error_trap_pop_ignored()[source]

Removes an error trap pushed with Gdk.error_trap_push(), but without bothering to wait and see whether an error occurred. If an error arrives later asynchronously that was triggered while the trap was pushed, that error will be ignored.

New in version 3.0.

Gdk.error_trap_push()[source]

This function allows X errors to be trapped instead of the normal behavior of exiting the application. It should only be used if it is not possible to avoid the X error in any other way. Errors are ignored on all Gdk.Display currently known to theGdk.DisplayManager. If you don’t care which error happens and just want to ignore everything, pop with Gdk.error_trap_pop_ignored(). If you need the error code, use Gdk.error_trap_pop() which may have to block and wait for the error to arrive from the X server.

This API exists on all platforms but only does anything on X.

You can use gdk_x11_display_error_trap_push() to ignore errors on only a single display.

Trapping an X error

gdk_error_trap_push ();

// ... Call the X function which may cause an error here ...

if (gdk_error_trap_pop ()) { // ... Handle the error here ... }

Gdk.event_get()[source]

Returns:

the next Gdk.Event to be processed, or Noneif no events are pending. The returned Gdk.Event should be freed with Gdk.Event.free().

Return type:

Gdk.Event or None

Checks all open displays for a Gdk.Event to process,to be processed on, fetching events from the windowing system if necessary. See Gdk.Display.get_event().

Gdk.event_handler_set(func, *data)[source]

Parameters:

Sets the function to call to handle all events from GDK.

Note that GTK+ uses this to install its own event handler, so it is usually not useful for GTK+ applications. (Although an application can call this function then call gtk_main_do_event() to pass events to GTK+.)

Gdk.event_peek()[source]

Returns:

a copy of the first Gdk.Event on some event queue, or None if no events are in any queues. The returnedGdk.Event should be freed with Gdk.Event.free().

Return type:

Gdk.Event or None

If there is an event waiting in the event queue of some open display, returns a copy of it. See Gdk.Display.peek_event().

Gdk.event_request_motions(event)[source]

Parameters:

event (Gdk.EventMotion) – a valid Gdk.Event

Request more motion notifies if event is a motion notify hint event.

This function should be used instead of Gdk.Window.get_pointer() to request further motion notifies, because it also works for extension events where motion notifies are provided for devices other than the core pointer. Coordinate extraction, processing and requesting more motion events from a Gdk.EventType.MOTION_NOTIFY event usually works like this:

{ // motion_event handler x = motion_event->x; y = motion_event->y; // handle (x,y) motion gdk_event_request_motions (motion_event); // handles is_hint events }

New in version 2.12.

Gdk.events_get_angle(event1, event2)[source]

Parameters:

Returns:

True if the angle could be calculated.

angle:

return location for the relative angle between both events

Return type:

(bool, angle: float)

If both events contain X/Y information, this function will return Trueand return in angle the relative angle from event1 to event2. The rotation direction for positive angles is from the positive X axis towards the positive Y axis.

New in version 3.0.

Gdk.events_get_center(event1, event2)[source]

Parameters:

Returns:

True if the center could be calculated.

x:

return location for the X coordinate of the center

y:

return location for the Y coordinate of the center

Return type:

(bool, x: float, y: float)

If both events contain X/Y information, the center of both coordinates will be returned in x and y.

New in version 3.0.

Gdk.events_get_distance(event1, event2)[source]

Parameters:

Returns:

True if the distance could be calculated.

distance:

return location for the distance

Return type:

(bool, distance: float)

If both events have X/Y information, the distance between both coordinates (as in a straight line going from event1 to event2) will be returned.

New in version 3.0.

Gdk.events_pending()[source]

Returns:

True if any events are pending.

Return type:

bool

Checks if any events are ready to be processed for any display.

Gdk.flush()[source]

Flushes the output buffers of all display connections and waits until all requests have been processed. This is rarely needed by applications.

Gdk.get_default_root_window()[source]

Returns:

the default root window

Return type:

Gdk.Window

Obtains the root window (parent all other windows are inside) for the default display and screen.

Gdk.get_display()[source]

Returns:

the name of the display.

Return type:

str

Gets the name of the display, which usually comes from theDISPLAY environment variable or the--display command line option.

Gdk.get_display_arg_name()[source]

Returns:

the display name, if specified explicitly, otherwise None this string is owned by GTK+ and must not be modified or freed.

Return type:

str or None

Gets the display name specified in the command line arguments passed to Gdk.init() or Gdk.parse_args(), if any.

New in version 2.2.

Gdk.get_program_class()[source]

Returns:

the program class.

Return type:

str

Gets the program class. Unless the program class has explicitly been set with Gdk.set_program_class() or with the --classcommandline option, the default value is the program name (determined with GLib.get_prgname()) with the first character converted to uppercase.

Gdk.get_show_events()[source]

Returns:

True if event debugging output is enabled.

Return type:

bool

Gets whether event debugging output is enabled.

Gdk.gl_error_quark()[source]

Return type:

int

Gdk.init(argv)[source]

Parameters:

argv ([str]) – the array of command line arguments.

Returns:

the array of command line arguments.

Return type:

argv: [str]

Initializes the GDK library and connects to the windowing system. If initialization fails, a warning message is output and the application terminates with a call to exit(1).

Any arguments used by GDK are removed from the array and argc and argvare updated accordingly.

GTK+ initializes GDK in gtk_init() and so this function is not usually needed by GTK+ applications.

Gdk.init_check(argv)[source]

Parameters:

argv ([str]) – the array of command line arguments.

Returns:

True if initialization succeeded.

argv:

the array of command line arguments.

Return type:

(bool, argv: [str])

Initializes the GDK library and connects to the windowing system, returning True on success.

Any arguments used by GDK are removed from the array and argc and argvare updated accordingly.

GTK+ initializes GDK in gtk_init() and so this function is not usually needed by GTK+ applications.

Gdk.keyboard_grab(window, owner_events, time_)[source]

Parameters:

Returns:

Gdk.GrabStatus.SUCCESS if the grab was successful.

Return type:

Gdk.GrabStatus

Grabs the keyboard so that all events are passed to this application until the keyboard is ungrabbed with Gdk.keyboard_ungrab(). This overrides any previous keyboard grab by this client.

If you set up anything at the time you take the grab that needs to be cleaned up when the grab ends, you should handle the Gdk.EventGrabBroken events that are emitted when the grab ends unvoluntarily.

Gdk.keyboard_ungrab(time_)[source]

Parameters:

time (int) – a timestamp from a Gdk.Event, or Gdk.CURRENT_TIME if no timestamp is available.

Ungrabs the keyboard on the default display, if it is grabbed by this application.

Gdk.keyval_convert_case(symbol)[source]

Parameters:

symbol (int) – a keyval

Returns:

lower:

return location for lowercase version of symbol

upper:

return location for uppercase version of symbol

Return type:

(lower: int, upper: int)

Obtains the upper- and lower-case versions of the keyval symbol. Examples of keyvals are Gdk.KEY_a, #GDK_KEY_Enter, Gdk.KEY_F1, etc.

Gdk.keyval_from_name(keyval_name)[source]

Parameters:

keyval_name (str) – a key name

Returns:

the corresponding key value, or Gdk.KEY_VoidSymbolif the key name is not a valid key

Return type:

int

Converts a key name to a key value.

The names are the same as those in thegdk/gdkkeysyms.h header file but without the leading “GDK_KEY_”.

Gdk.keyval_is_lower(keyval)[source]

Parameters:

keyval (int) – a key value.

Returns:

True if keyval is in lower case, or if keyval is not subject to case conversion.

Return type:

bool

Returns True if the given key value is in lower case.

Gdk.keyval_is_upper(keyval)[source]

Parameters:

keyval (int) – a key value.

Returns:

True if keyval is in upper case, or if keyval is not subject to case conversion.

Return type:

bool

Returns True if the given key value is in upper case.

Gdk.keyval_name(keyval)[source]

Parameters:

keyval (int) – a key value

Returns:

a string containing the name of the key, or None if keyval is not a valid key. The string should not be modified.

Return type:

str or None

Converts a key value into a symbolic name.

The names are the same as those in thegdk/gdkkeysyms.h header file but without the leading “GDK_KEY_”.

Gdk.keyval_to_lower(keyval)[source]

Parameters:

keyval (int) – a key value.

Returns:

the lower case form of keyval, or keyval itself if it is already in lower case or it is not subject to case conversion.

Return type:

int

Converts a key value to lower case, if applicable.

Gdk.keyval_to_unicode(keyval)[source]

Parameters:

keyval (int) – a GDK key symbol

Returns:

the corresponding unicode character, or 0 if there is no corresponding character.

Return type:

int

Convert from a GDK key symbol to the corresponding ISO10646 (Unicode) character.

Gdk.keyval_to_upper(keyval)[source]

Parameters:

keyval (int) – a key value.

Returns:

the upper case form of keyval, or keyval itself if it is already in upper case or it is not subject to case conversion.

Return type:

int

Converts a key value to upper case, if applicable.

Gdk.list_visuals()[source]

Returns:

a list of visuals; the list must be freed, but not its contents

Return type:

[Gdk.Visual]

Lists the available visuals for the default screen. (See Gdk.Screen.list_visuals()) A visual describes a hardware image data format. For example, a visual might support 24-bit color, or 8-bit color, and might expect pixels to be in a certain format.

Call g_list_free() on the return value when you’re finished with it.

Gdk.notify_startup_complete()[source]

Indicates to the GUI environment that the application has finished loading. If the applications opens windows, this function is normally called after opening the application’s initial set of windows.

GTK+ will call this function automatically after opening the first #GtkWindow unless gtk_window_set_auto_startup_notification() is called to disable that feature.

New in version 2.2.

Gdk.notify_startup_complete_with_id(startup_id)[source]

Parameters:

startup_id (str) – a startup-notification identifier, for which notification process should be completed

Indicates to the GUI environment that the application has finished loading, using a given identifier.

GTK+ will call this function automatically for #GtkWindow with custom startup-notification identifier unless gtk_window_set_auto_startup_notification() is called to disable that feature.

New in version 2.12.

Gdk.offscreen_window_get_embedder(window)[source]

Parameters:

window (Gdk.Window) – a Gdk.Window

Returns:

the embedding Gdk.Window, orNone if window is not an mbedded offscreen window

Return type:

Gdk.Window or None

Gets the window that window is embedded in.

New in version 2.18.

Gdk.offscreen_window_get_surface(window)[source]

Parameters:

window (Gdk.Window) – a Gdk.Window

Returns:

The offscreen surface, orNone if not offscreen

Return type:

cairo.Surface or None

Gets the offscreen surface that an offscreen window renders into. If you need to keep this around over window resizes, you need to add a reference to it.

Gdk.offscreen_window_set_embedder(window, embedder)[source]

Parameters:

Sets window to be embedded in embedder.

To fully embed an offscreen window, in addition to calling this function, it is also necessary to handle the Gdk.Window ::pick-embedded-childsignal on the embedder and the Gdk.Window ::to-embedder andGdk.Window ::from-embedder signals on window.

New in version 2.18.

Gdk.pango_context_get()[source]

Returns:

a new Pango.Context for the default display

Return type:

Pango.Context

Creates a Pango.Context for the default GDK screen.

The context must be freed when you’re finished with it.

When using GTK+, normally you should use gtk_widget_get_pango_context() instead of this function, to get the appropriate context for the widget you intend to render text onto.

The newly created context will have the default font options (seecairo.FontOptions) for the default screen; if these options change it will not be updated. Using gtk_widget_get_pango_context() is more convenient if you want to keep a context around and track changes to the screen’s font rendering settings.

Gdk.pango_context_get_for_display(display)[source]

Parameters:

display (Gdk.Display) – the Gdk.Display for which the context is to be created

Returns:

a new Pango.Context for display

Return type:

Pango.Context

Creates a Pango.Context for display.

The context must be freed when you’re finished with it.

When using GTK+, normally you should use gtk_widget_get_pango_context() instead of this function, to get the appropriate context for the widget you intend to render text onto.

The newly created context will have the default font options (see cairo.FontOptions) for the display; if these options change it will not be updated. Using gtk_widget_get_pango_context() is more convenient if you want to keep a context around and track changes to the font rendering settings.

New in version 3.22.

Gdk.pango_context_get_for_screen(screen)[source]

Parameters:

screen (Gdk.Screen) – the Gdk.Screen for which the context is to be created.

Returns:

a new Pango.Context for screen

Return type:

Pango.Context

Creates a Pango.Context for screen.

The context must be freed when you’re finished with it.

When using GTK+, normally you should use gtk_widget_get_pango_context() instead of this function, to get the appropriate context for the widget you intend to render text onto.

The newly created context will have the default font options (see cairo.FontOptions) for the screen; if these options change it will not be updated. Using gtk_widget_get_pango_context() is more convenient if you want to keep a context around and track changes to the screen’s font rendering settings.

New in version 2.2.

Gdk.parse_args(argv)[source]

Parameters:

argv ([str]) – the array of command line arguments.

Returns:

the array of command line arguments.

Return type:

argv: [str]

Parse command line arguments, and store for future use by calls to Gdk.Display.open().

Any arguments used by GDK are removed from the array and argc and argv are updated accordingly.

You shouldn’t call this function explicitly if you are using gtk_init(), gtk_init_check(), Gdk.init(), or Gdk.init_check().

New in version 2.2.

Gdk.pixbuf_get_from_surface(surface, src_x, src_y, width, height)[source]

Parameters:

Returns:

A newly-created pixbuf with a reference count of 1, or None on error

Return type:

GdkPixbuf.Pixbuf or None

Transfers image data from a cairo.Surface and converts it to an RGB(A) representation inside a GdkPixbuf.Pixbuf. This allows you to efficiently read individual pixels from cairo surfaces. For Gdk.Windows, useGdk.pixbuf_get_from_window() instead.

This function will create an RGB pixbuf with 8 bits per channel. The pixbuf will contain an alpha channel if the surface contains one.

Gdk.pixbuf_get_from_window(window, src_x, src_y, width, height)[source]

Parameters:

Returns:

A newly-created pixbuf with a reference count of 1, or None on error

Return type:

GdkPixbuf.Pixbuf or None

Transfers image data from a Gdk.Window and converts it to an RGB(A) representation inside a GdkPixbuf.Pixbuf.

In other words, copies image data from a server-side drawable to a client-side RGB(A) buffer. This allows you to efficiently read individual pixels on the client side.

This function will create an RGB pixbuf with 8 bits per channel with the size specified by the width and height arguments scaled by the scale factor of window. The pixbuf will contain an alpha channel if the window contains one.

If the window is off the screen, then there is no image data in the obscured/offscreen regions to be placed in the pixbuf. The contents of portions of the pixbuf corresponding to the offscreen region are undefined.

If the window you’re obtaining data from is partially obscured by other windows, then the contents of the pixbuf areas corresponding to the obscured regions are undefined.

If the window is not mapped (typically because it’s iconified/minimized or not on the current workspace), then None will be returned.

If memory can’t be allocated for the return value, None will be returned instead.

In short, there are several ways this function can fail, and if it fails it returns None; so check the return value.

You should rarely, if ever, need to call this function.

Gdk.pointer_grab(window, owner_events, event_mask, confine_to, cursor, time_)[source]

Parameters:

Returns:

Gdk.GrabStatus.SUCCESS if the grab was successful.

Return type:

Gdk.GrabStatus

Grabs the pointer (usually a mouse) so that all events are passed to this application until the pointer is ungrabbed with Gdk.pointer_ungrab(), or the grab window becomes unviewable. This overrides any previous pointer grab by this client.

Pointer grabs are used for operations which need complete control over mouse events, even if the mouse leaves the application. For example in GTK+ it is used for Drag and Drop, for dragging the handle in the #GtkHPaned and #GtkVPaned widgets.

Note that if the event mask of an X window has selected both button press and button release events, then a button press event will cause an automatic pointer grab until the button is released. X does this automatically since most applications expect to receive button press and release events in pairs. It is equivalent to a pointer grab on the window with owner_events set toTrue.

If you set up anything at the time you take the grab that needs to be cleaned up when the grab ends, you should handle the Gdk.EventGrabBroken events that are emitted when the grab ends unvoluntarily.

Gdk.pointer_is_grabbed()[source]

Returns:

True if the pointer is currently grabbed by this application.

Return type:

bool

Returns True if the pointer on the default display is currently grabbed by this application.

Note that this does not take the inmplicit pointer grab on button presses into account.

Gdk.pointer_ungrab(time_)[source]

Parameters:

time (int) – a timestamp from a Gdk.Event, or Gdk.CURRENT_TIME if no timestamp is available.

Ungrabs the pointer on the default display, if it is grabbed by this application.

Gdk.pre_parse_libgtk_only()[source]

Prepare for parsing command line arguments for GDK. This is not public API and should not be used in application code.

Deprecated since version 3.16: This symbol was never meant to be used outside of GTK+

Gdk.property_delete(window, property)[source]

Parameters:

Deletes a property from a window.

Gdk.property_get(window, property, type, offset, length, pdelete)[source]

Parameters:

Returns:

True if data was successfully received and stored in data, otherwise False.

actual_property_type:

location to store the actual type of the property.

actual_format:

location to store the actual return format of the data; either 8, 16 or 32 bits.

data:

location to store a pointer to the data. The retrieved data should be freed with GLib.free() when you are finished using it.

Return type:

(bool, actual_property_type: Gdk.Atom, actual_format: int, data: bytes)

Retrieves a portion of the contents of a property. If the property does not exist, then the function returns False, and %GDK_NONE will be stored in actual_property_type.

The XGetWindowProperty() function that Gdk.property_get() uses has a very confusing and complicated set of semantics. Unfortunately, Gdk.property_get() makes the situation worse instead of better (the semantics should be considered undefined), and also prints warnings to stderr in cases where it should return a useful error to the program. You are advised to use XGetWindowProperty() directly until a replacement function forGdk.property_get() is provided.

Gdk.query_depths()[source]

Returns:

return location for available depths

Return type:

depths: [int]

This function returns the available bit depths for the default screen. It’s equivalent to listing the visuals (Gdk.list_visuals()) and then looking at the depth field in each visual, removing duplicates.

The array returned by this function should not be freed.

Gdk.query_visual_types()[source]

Returns:

return location for the available visual types

Return type:

visual_types: [Gdk.VisualType]

This function returns the available visual types for the default screen. It’s equivalent to listing the visuals (Gdk.list_visuals()) and then looking at the type field in each visual, removing duplicates.

The array returned by this function should not be freed.

Gdk.rectangle_intersect(src2)

intersect(src2: Gdk.Rectangle) -> (bool, dest: Gdk.Rectangle)

Gdk.rectangle_union(src2)

union(src2: Gdk.Rectangle) -> dest: Gdk.Rectangle

Gdk.selection_convert(requestor, selection, target, time_)[source]

Parameters:

Retrieves the contents of a selection in a given form.

Gdk.selection_owner_get(selection)[source]

Parameters:

selection (Gdk.Atom) – an atom indentifying a selection.

Returns:

if there is a selection owner for this window, and it is a window known to the current process, the Gdk.Window that owns the selection, otherwise None. Note that the return value may be owned by a different process if a foreign window was previously created for that window, but a new foreign window will never be created by this call.

Return type:

Gdk.Window or None

Determines the owner of the given selection.

Gdk.selection_owner_get_for_display(display, selection)[source]

Parameters:

Returns:

if there is a selection owner for this window, and it is a window known to the current process, the Gdk.Window that owns the selection, otherwiseNone.

Return type:

Gdk.Window or None

Determine the owner of the given selection.

Note that the return value may be owned by a different process if a foreign window was previously created for that window, but a new foreign window will never be created by this call.

New in version 2.2.

Gdk.selection_owner_set(owner, selection, time_, send_event)[source]

Parameters:

Returns:

True if the selection owner was successfully changed to owner, otherwise False.

Return type:

bool

Sets the owner of the given selection.

Gdk.selection_owner_set_for_display(display, owner, selection, time_, send_event)[source]

Parameters:

Returns:

True if the selection owner was successfully changed to owner, otherwise False.

Return type:

bool

Sets the Gdk.Window owner as the current owner of the selection selection.

New in version 2.2.

Gdk.selection_send_notify(requestor, selection, target, property, time_)[source]

Parameters:

Sends a response to SelectionRequest event.

Gdk.selection_send_notify_for_display(display, requestor, selection, target, property, time_)[source]

Parameters:

Send a response to SelectionRequest event.

New in version 2.2.

Gdk.set_allowed_backends(backends)[source]

Parameters:

backends (str) – a comma-separated list of backends

Sets a list of backends that GDK should try to use.

This can be be useful if your application does not work with certain GDK backends.

By default, GDK tries all included backends.

For example,

gdk_set_allowed_backends ("wayland,quartz,*");

instructs GDK to try the Wayland backend first, followed by the Quartz backend, and then all others.

If the GDK_BACKEND environment variable is set, it determines what backends are tried in what order, while still respecting the set of allowed backends that are specified by this function.

The possible backend names are x11, win32, quartz, broadway, wayland. You can also include a * in the list to try all remaining backends.

This call must happen prior to Gdk.Display.open(), gtk_init(), gtk_init_with_args() or gtk_init_check() in order to take effect.

New in version 3.10.

Gdk.set_double_click_time(msec)[source]

Parameters:

msec (int) – double click time in milliseconds (thousandths of a second)

Set the double click time for the default display. SeeGdk.Display.set_double_click_time(). See also Gdk.Display.set_double_click_distance(). Applications should not set this, it is a global user-configured setting.

Gdk.set_program_class(program_class)[source]

Parameters:

program_class (str) – a string.

Sets the program class. The X11 backend uses the program class to set the class name part of the WM_CLASS property on toplevel windows; see the ICCCM.

The program class can still be overridden with the –class command line option.

Gdk.set_show_events(show_events)[source]

Parameters:

show_events (bool) – True to output event debugging information.

Sets whether a trace of received events is output. Note that GTK+ must be compiled with debugging (that is, configured using the --enable-debug option) to use this option.

Gdk.setting_get(name, value)[source]

Parameters:

Returns:

True if the setting existed and a value was stored in value, False otherwise.

Return type:

bool

Obtains a desktop-wide setting, such as the double-click time, for the default screen. See Gdk.Screen.get_setting().

Gdk.synthesize_window_state(window, unset_flags, set_flags)[source]

Parameters:

Gdk.test_render_sync(window)[source]

Parameters:

window (Gdk.Window) – a mapped Gdk.Window

Retrieves a pixel from window to force the windowing system to carry out any pending rendering commands.

This function is intended to be used to synchronize with rendering pipelines, to benchmark windowing system rendering operations.

New in version 2.14.

Gdk.test_simulate_button(window, x, y, button, modifiers, button_pressrelease)[source]

Parameters:

Returns:

whether all actions necessary for a button event simulation were carried out successfully

Return type:

bool

This function is intended to be used in GTK+ test programs. It will warp the mouse pointer to the given (x,`y`) coordinates within window and simulate a button press or release event. Because the mouse pointer needs to be warped to the target location, use of this function outside of test programs that run in their own virtual windowing system (e.g. Xvfb) is not recommended.

Also, Gdk.test_simulate_button() is a fairly low level function, for most testing purposes, gtk_test_widget_click() is the right function to call which will generate a button press event followed by its accompanying button release event.

New in version 2.14.

Gdk.test_simulate_key(window, x, y, keyval, modifiers, key_pressrelease)[source]

Parameters:

Returns:

whether all actions necessary for a key event simulation were carried out successfully

Return type:

bool

This function is intended to be used in GTK+ test programs. If (x,`y`) are > (-1,-1), it will warp the mouse pointer to the given (x,`y`) coordinates within window and simulate a key press or release event.

When the mouse pointer is warped to the target location, use of this function outside of test programs that run in their own virtual windowing system (e.g. Xvfb) is not recommended. If (x,`y`) are passed as (-1,-1), the mouse pointer will not be warped and window origin will be used as mouse pointer location for the event.

Also, Gdk.test_simulate_key() is a fairly low level function, for most testing purposes, gtk_test_widget_send_key() is the right function to call which will generate a key press event followed by its accompanying key release event.

New in version 2.14.

Gdk.text_property_to_utf8_list_for_display(display, encoding, format, text)[source]

Parameters:

Returns:

the number of strings in the resulting list

list:

location to store the list of strings or None. The list should be freed withGLib.strfreev().

Return type:

(int, list: [str])

Converts a text property in the given encoding to a list of UTF-8 strings.

New in version 2.2.

Gdk.threads_add_idle(priority, function, *data)[source]

Parameters:

Returns:

the ID (greater than 0) of the event source.

Return type:

int

Adds a function to be called whenever there are no higher priority events pending. If the function returns False it is automatically removed from the list of event sources and will not be called again.

This variant of GLib.idle_add() calls function with the GDK lock held. It can be thought of a MT-safe version for GTK+ widgets for the following use case, where you have to worry about idle_callback() running in thread A and accessing self after it has been finalized in thread B:

static gboolean idle_callback (gpointer data) { // gdk_threads_enter(); would be needed for g_idle_add()

SomeWidget *self = data; // do stuff with self

self->idle_id = 0;

// gdk_threads_leave(); would be needed for g_idle_add() return FALSE; }

static void some_widget_do_stuff_later (SomeWidget *self) { self->idle_id = gdk_threads_add_idle (idle_callback, self) // using g_idle_add() here would require thread protection in the callback }

static void some_widget_finalize (GObject *object) { SomeWidget *self = SOME_WIDGET (object); if (self->idle_id) g_source_remove (self->idle_id); G_OBJECT_CLASS (parent_class)->finalize (object); }

New in version 2.12.

Gdk.threads_add_timeout(priority, interval, function, *data)[source]

Parameters:

Returns:

the ID (greater than 0) of the event source.

Return type:

int

Sets a function to be called at regular intervals holding the GDK lock, with the given priority. The function is called repeatedly until it returns False, at which point the timeout is automatically destroyed and the function will not be called again. The notify function is called when the timeout is destroyed. The first call to the function will be at the end of the first interval.

Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to “catch up” time lost in delays).

This variant of GLib.timeout_add() can be thought of a MT-safe version for GTK+ widgets for the following use case:

static gboolean timeout_callback (gpointer data) { SomeWidget *self = data;

// do stuff with self

self->timeout_id = 0;

return G_SOURCE_REMOVE; }

static void some_widget_do_stuff_later (SomeWidget *self) { self->timeout_id = g_timeout_add (timeout_callback, self) }

static void some_widget_finalize (GObject *object) { SomeWidget *self = SOME_WIDGET (object);

if (self->timeout_id) g_source_remove (self->timeout_id);

G_OBJECT_CLASS (parent_class)->finalize (object); }

New in version 2.12.

Gdk.threads_add_timeout_seconds(priority, interval, function, *data)[source]

Parameters:

Returns:

the ID (greater than 0) of the event source.

Return type:

int

A variant of Gdk.threads_add_timeout() with second-granularity. See GLib.timeout_add_seconds() for a discussion of why it is a good idea to use this function if you don’t need finer granularity.

New in version 2.14.

Gdk.threads_enter()[source]

This function marks the beginning of a critical section in which GDK and GTK+ functions can be called safely and without causing race conditions. Only one thread at a time can be in such a critial section.

Deprecated since version 3.6: All GDK and GTK+ calls should be made from the main thread

Gdk.threads_init()[source]

Initializes GDK so that it can be used from multiple threads in conjunction with Gdk.threads_enter() and Gdk.threads_leave().

This call must be made before any use of the main loop from GTK+; to be safe, call it before gtk_init().

Deprecated since version 3.6: All GDK and GTK+ calls should be made from the main thread

Gdk.threads_leave()[source]

Leaves a critical region begun with Gdk.threads_enter().

Deprecated since version 3.6: All GDK and GTK+ calls should be made from the main thread

Gdk.unicode_to_keyval(wc)[source]

Parameters:

wc (int) – a ISO10646 encoded character

Returns:

the corresponding GDK key symbol, if one exists. or, if there is no corresponding symbol, wc | 0x01000000

Return type:

int

Convert from a ISO10646 character to a key symbol.

Gdk.utf8_to_string_target(str)[source]

Parameters:

str (str) – a UTF-8 string

Returns:

the newly-allocated string, or None if the conversion failed. (It should not fail for any properly formed UTF-8 string unless system limits like memory or file descriptors are exceeded.)

Return type:

str or None

Converts an UTF-8 string into the best possible representation as a STRING. The representation of characters not in STRING is not specified; it may be as pseudo-escape sequences \x{ABCD}, or it may be in some other form of approximation.