Functions

  accel_groups_activate (object, accel_key, accel_mods)
  accel_groups_from_object (object)
  accelerator_get_default_mod_mask ()
  accelerator_get_label (accelerator_key, accelerator_mods)
  accelerator_get_label_with_keycode (display, accelerator_key, keycode, accelerator_mods)
  accelerator_name (accelerator_key, accelerator_mods)
  accelerator_name_with_keycode (display, accelerator_key, keycode, accelerator_mods)
  accelerator_parse (accelerator)
  accelerator_parse_with_keycode (accelerator)
  accelerator_set_default_mod_mask (default_mod_mask)
  accelerator_valid (keyval, modifiers)
  alternative_dialog_button_order (screen)
  binding_entry_add_signal_from_string (binding_set, signal_desc)
  binding_entry_add_signall (binding_set, keyval, modifiers, signal_name, binding_args)
  binding_entry_remove (binding_set, keyval, modifiers)
  binding_entry_skip (binding_set, keyval, modifiers)
  binding_set_find (set_name)
  bindings_activate (object, keyval, modifiers)
  bindings_activate_event (object, event)
  builder_error_quark ()
  cairo_should_draw_window (cr, window)
  cairo_transform_to_window (cr, widget, window)
  check_version (required_major, required_minor, required_micro)
  css_provider_error_quark ()
  device_grab_add (widget, device, block_others)
  device_grab_remove (widget, device)
  disable_setlocale ()
  distribute_natural_allocation (extra_space, n_requested_sizes, sizes)
  drag_cancel (context)
  drag_finish (context, success, del_, time_)
  drag_get_source_widget (context)
  drag_set_icon_default (context)
  drag_set_icon_gicon (context, icon, hot_x, hot_y)
  drag_set_icon_name (context, icon_name, hot_x, hot_y)
  drag_set_icon_pixbuf (context, pixbuf, hot_x, hot_y)
  drag_set_icon_stock (context, stock_id, hot_x, hot_y)
  drag_set_icon_surface (context, surface)
  drag_set_icon_widget (context, widget, hot_x, hot_y)
  draw_insertion_cursor (widget, cr, location, is_primary, direction, draw_arrow)
  events_pending ()
  false ()
  file_chooser_error_quark ()
  get_binary_age ()
  get_current_event ()
  get_current_event_device ()
  get_current_event_state ()
  get_current_event_time ()
  get_debug_flags ()
  get_default_language ()
  get_event_widget (event)
  get_interface_age ()
  get_locale_direction ()
  get_major_version ()
  get_micro_version ()
  get_minor_version ()
  get_option_group (open_default_display)
  grab_get_current ()
  icon_size_from_name (name)
  icon_size_get_name (size)
  icon_size_lookup (size)
  icon_size_lookup_for_settings (settings, size)
  icon_size_register (name, width, height)
  icon_size_register_alias (alias, target)
  icon_theme_error_quark ()
  init (argv)
  init_check (argv)
  init_with_args (argv, parameter_string, entries, translation_domain)
  key_snooper_remove (snooper_handler_id)
  main ()
  main_do_event (event)
  main_iteration ()
  main_iteration_do (blocking)
  main_level ()
  main_quit ()
  paint_arrow (style, cr, state_type, shadow_type, widget, detail, arrow_type, fill, x, y, width, height)
  paint_box (style, cr, state_type, shadow_type, widget, detail, x, y, width, height)
  paint_box_gap (style, cr, state_type, shadow_type, widget, detail, x, y, width, height, gap_side, gap_x, gap_width)
  paint_check (style, cr, state_type, shadow_type, widget, detail, x, y, width, height)
  paint_diamond (style, cr, state_type, shadow_type, widget, detail, x, y, width, height)
  paint_expander (style, cr, state_type, widget, detail, x, y, expander_style)
  paint_extension (style, cr, state_type, shadow_type, widget, detail, x, y, width, height, gap_side)
  paint_flat_box (style, cr, state_type, shadow_type, widget, detail, x, y, width, height)
  paint_focus (style, cr, state_type, widget, detail, x, y, width, height)
  paint_handle (style, cr, state_type, shadow_type, widget, detail, x, y, width, height, orientation)
  paint_hline (style, cr, state_type, widget, detail, x1, x2, y)
  paint_layout (style, cr, state_type, use_text, widget, detail, x, y, layout)
  paint_option (style, cr, state_type, shadow_type, widget, detail, x, y, width, height)
  paint_resize_grip (style, cr, state_type, widget, detail, edge, x, y, width, height)
  paint_shadow (style, cr, state_type, shadow_type, widget, detail, x, y, width, height)
  paint_shadow_gap (style, cr, state_type, shadow_type, widget, detail, x, y, width, height, gap_side, gap_x, gap_width)
  paint_slider (style, cr, state_type, shadow_type, widget, detail, x, y, width, height, orientation)
  paint_spinner (style, cr, state_type, widget, detail, step, x, y, width, height)
  paint_tab (style, cr, state_type, shadow_type, widget, detail, x, y, width, height)
  paint_vline (style, cr, state_type, widget, detail, y1_, y2_, x)
  paper_size_get_default ()
  paper_size_get_paper_sizes (include_custom)
  parse_args (argv)
  print_error_quark ()
  print_run_page_setup_dialog (parent, page_setup, settings)
  print_run_page_setup_dialog_async (parent, page_setup, settings, done_cb, *data)
  propagate_event (widget, event)
  rc_add_default_file (filename)
  rc_find_module_in_path (module_file)
  rc_find_pixmap_in_path (settings, scanner, pixmap_file)
  rc_get_default_files ()
  rc_get_im_module_file ()
  rc_get_im_module_path ()
  rc_get_module_dir ()
  rc_get_style (widget)
  rc_get_style_by_paths (settings, widget_path, class_path, type)
  rc_get_theme_dir ()
  rc_parse (filename)
  rc_parse_color (scanner)
  rc_parse_color_full (scanner, style)
  rc_parse_priority (scanner, priority)
  rc_parse_state (scanner)
  rc_parse_string (rc_string)
  rc_property_parse_border (pspec, gstring, property_value)
  rc_property_parse_color (pspec, gstring, property_value)
  rc_property_parse_enum (pspec, gstring, property_value)
  rc_property_parse_flags (pspec, gstring, property_value)
  rc_property_parse_requisition (pspec, gstring, property_value)
  rc_reparse_all ()
  rc_reparse_all_for_settings (settings, force_load)
  rc_reset_styles (settings)
  rc_set_default_files (filenames)
  recent_chooser_error_quark ()
  recent_manager_error_quark ()
  render_activity (context, cr, x, y, width, height)
  render_arrow (context, cr, angle, x, y, size)
  render_background (context, cr, x, y, width, height)
  render_background_get_clip (context, x, y, width, height)
  render_check (context, cr, x, y, width, height)
  render_expander (context, cr, x, y, width, height)
  render_extension (context, cr, x, y, width, height, gap_side)
  render_focus (context, cr, x, y, width, height)
  render_frame (context, cr, x, y, width, height)
  render_frame_gap (context, cr, x, y, width, height, gap_side, xy0_gap, xy1_gap)
  render_handle (context, cr, x, y, width, height)
  render_icon (context, cr, pixbuf, x, y)
  render_icon_pixbuf (context, source, size)
  render_icon_surface (context, cr, surface, x, y)
  render_insertion_cursor (context, cr, x, y, layout, index, direction)
  render_layout (context, cr, x, y, layout)
  render_line (context, cr, x0, y0, x1, y1)
  render_option (context, cr, x, y, width, height)
  render_slider (context, cr, x, y, width, height, orientation)
  rgb_to_hsv (r, g, b)
  selection_add_target (widget, selection, target, info)
  selection_add_targets (widget, selection, targets)
  selection_clear_targets (widget, selection)
  selection_convert (widget, selection, target, time_)
  selection_owner_set (widget, selection, time_)
  selection_owner_set_for_display (display, widget, selection, time_)
  selection_remove_all (widget)
  set_debug_flags (flags)
  show_uri (screen, uri, timestamp)
  show_uri_on_window (parent, uri, timestamp)
  stock_add (items)
  stock_add_static (items)
  stock_list_ids ()
  stock_lookup (stock_id)
  stock_set_translate_func (domain, func, *data)
  target_table_free (targets)
  target_table_new_from_list (list)
  targets_include_image (targets, writable)
  targets_include_rich_text (targets, buffer)
  targets_include_text (targets)
  targets_include_uri (targets)
  test_create_simple_window (window_title, dialog_text)
  test_find_label (widget, label_pattern)
  test_find_sibling (base_widget, widget_type)
  test_find_widget (widget, label_pattern, widget_type)
  test_list_all_types ()
  test_register_all_types ()
  test_slider_get_value (widget)
  test_slider_set_perc (widget, percentage)
  test_spin_button_click (spinner, button, upwards)
  test_text_get (widget)
  test_text_set (widget, string)
  test_widget_click (widget, button, modifiers)
  test_widget_send_key (widget, keyval, modifiers)
  test_widget_wait_for_draw (widget)
  tree_get_row_drag_data (selection_data)
  tree_row_reference_deleted (proxy, path)
  tree_row_reference_inserted (proxy, path)
  tree_set_row_drag_data (selection_data, tree_model, path)
  true ()

Details

Gtk.accel_groups_activate(object, accel_key, accel_mods)[source]
Parameters:
Returns:

True if an accelerator was activated and handled this keypress
Return type:

bool

Finds the first accelerator in any Gtk.AccelGroup attached to object that matches accel_key and accel_mods, and activates that accelerator.

Gtk.accel_groups_from_object(object)[source]
Parameters:object (GObject.Object) – a GObject.Object, usually a Gtk.Window
Returns:a list of all accel groups which are attached to object
Return type:[Gtk.AccelGroup]

Gets a list of all accel groups which are attached to object.

Gtk.accelerator_get_default_mod_mask()[source]
Returns:the default accelerator modifier mask
Return type:Gdk.ModifierType

Gets the modifier mask.

The modifier mask determines which modifiers are considered significant for keyboard accelerators. See Gtk.accelerator_set_default_mod_mask().

Gtk.accelerator_get_label(accelerator_key, accelerator_mods)[source]
Parameters:
  • accelerator_key (int) – accelerator keyval
  • accelerator_mods (Gdk.ModifierType) – accelerator modifier mask
Returns:

a newly-allocated string representing the accelerator.
Return type:

str

Converts an accelerator keyval and modifier mask into a string which can be used to represent the accelerator to the user.

New in version 2.6.

Gtk.accelerator_get_label_with_keycode(display, accelerator_key, keycode, accelerator_mods)[source]
Parameters:
Returns:

a newly-allocated string representing the accelerator.
Return type:

str

Converts an accelerator keyval and modifier mask into a (possibly translated) string that can be displayed to a user, similarly to Gtk.accelerator_get_label(), but handling keycodes.

This is only useful for system-level components, applications should use Gtk.accelerator_parse() instead.

New in version 3.4.

Gtk.accelerator_name(accelerator_key, accelerator_mods)[source]
Parameters:
  • accelerator_key (int) – accelerator keyval
  • accelerator_mods (Gdk.ModifierType) – accelerator modifier mask
Returns:

a newly-allocated accelerator name
Return type:

str

Converts an accelerator keyval and modifier mask into a string parseable by Gtk.accelerator_parse(). For example, if you pass in Gdk.KEY_q and Gdk.ModifierType.CONTROL_MASK, this function returns “<Control>q”.

If you need to display accelerators in the user interface, see Gtk.accelerator_get_label().

Gtk.accelerator_name_with_keycode(display, accelerator_key, keycode, accelerator_mods)[source]
Parameters:
Returns:

a newly allocated accelerator name.
Return type:

str

Converts an accelerator keyval and modifier mask into a string parseable by Gtk.accelerator_parse_with_keycode(), similarly to Gtk.accelerator_name() but handling keycodes. This is only useful for system-level components, applications should use Gtk.accelerator_parse() instead.

New in version 3.4.

Gtk.accelerator_parse(accelerator)[source]
Parameters:accelerator (str) – string representing an accelerator
Returns:
accelerator_key:
 return location for accelerator keyval, or None
accelerator_mods:
 return location for accelerator modifier mask, None
Return type:(accelerator_key: int, accelerator_mods: Gdk.ModifierType)

Parses a string representing an accelerator. The format looks like “<Control>a” or “<Shift><Alt>F1” or “<Release>z” (the last one is for key release).

The parser is fairly liberal and allows lower or upper case, and also abbreviations such as “<Ctl>” and “<Ctrl>”. Key names are parsed using Gdk.keyval_from_name(). For character keys the name is not the symbol, but the lowercase name, e.g. one would use “<Ctrl>minus” instead of “<Ctrl>-”.

If the parse fails, accelerator_key and accelerator_mods will be set to 0 (zero).

Gtk.accelerator_parse_with_keycode(accelerator)[source]
Parameters:accelerator (str) – string representing an accelerator
Returns:
accelerator_key:
 return location for accelerator keyval, or None
accelerator_codes:
 return location for accelerator keycodes, or None
accelerator_mods:
 return location for accelerator modifier mask, None
Return type:(accelerator_key: int, accelerator_codes: [int], accelerator_mods: Gdk.ModifierType)

Parses a string representing an accelerator, similarly to Gtk.accelerator_parse() but handles keycodes as well. This is only useful for system-level components, applications should use Gtk.accelerator_parse() instead.

If accelerator_codes is given and the result stored in it is non-None, the result must be freed with GLib.free().

If a keycode is present in the accelerator and no accelerator_codes is given, the parse will fail.

If the parse fails, accelerator_key, accelerator_mods and accelerator_codes will be set to 0 (zero).

New in version 3.4.

Gtk.accelerator_set_default_mod_mask(default_mod_mask)[source]
Parameters:default_mod_mask (Gdk.ModifierType) – accelerator modifier mask

Sets the modifiers that will be considered significant for keyboard accelerators. The default mod mask depends on the GDK backend in use, but will typically include Gdk.ModifierType.CONTROL_MASK | Gdk.ModifierType.SHIFT_MASK | Gdk.ModifierType.MOD1_MASK | Gdk.ModifierType.SUPER_MASK | Gdk.ModifierType.HYPER_MASK | Gdk.ModifierType.META_MASK. In other words, Control, Shift, Alt, Super, Hyper and Meta. Other modifiers will by default be ignored by Gtk.AccelGroup.

You must include at least the three modifiers Control, Shift and Alt in any value you pass to this function.

The default mod mask should be changed on application startup, before using any accelerator groups.

Gtk.accelerator_valid(keyval, modifiers)[source]
Parameters:
Returns:

True if the accelerator is valid
Return type:

bool

Determines whether a given keyval and modifier mask constitute a valid keyboard accelerator. For example, the Gdk.KEY_a keyval plus Gdk.ModifierType.CONTROL_MASK is valid - this is a “Ctrl+a” accelerator. But, you can’t, for instance, use the Gdk.KEY_Control_L keyval as an accelerator.

Gtk.alternative_dialog_button_order(screen)[source]
Parameters:screen (Gdk.Screen or None) – a Gdk.Screen, or None to use the default screen
Returns:Whether the alternative button order should be used
Return type:bool

Returns True if dialogs are expected to use an alternative button order on the screen screen. See gtk_dialog_set_alternative_button_order() for more details about alternative button order.

If you need to use this function, you should probably connect to the ::notify:gtk-alternative-button-order signal on the Gtk.Settings object associated to screen, in order to be notified if the button order setting changes.

New in version 2.6.

Deprecated since version 3.10: Deprecated

Gtk.binding_entry_add_signal_from_string(binding_set, signal_desc)[source]
Parameters:
Returns:

GLib.TokenType.NONE if the signal was successfully parsed and added, the expected token otherwise
Return type:

GLib.TokenType

Parses a signal description from signal_desc and incorporates it into binding_set.

Signal descriptions may either bind a key combination to one or more signals:

bind "key" {
  "signalname" (param, ...)
  ...
}

Or they may also unbind a key combination:

unbind "key"

Key combinations must be in a format that can be parsed by Gtk.accelerator_parse().

New in version 3.0.

Gtk.binding_entry_add_signall(binding_set, keyval, modifiers, signal_name, binding_args)[source]
Parameters:

Override or install a new key binding for keyval with modifiers on binding_set.

Gtk.binding_entry_remove(binding_set, keyval, modifiers)[source]
Parameters:

Remove a binding previously installed via gtk_binding_entry_add_signal() on binding_set.

Gtk.binding_entry_skip(binding_set, keyval, modifiers)[source]
Parameters:

Install a binding on binding_set which causes key lookups to be aborted, to prevent bindings from lower priority sets to be activated.

New in version 2.12.

Gtk.binding_set_find(set_name)[source]
Parameters:set_name (str) – unique binding set name
Returns:None or the specified binding set
Return type:Gtk.BindingSet or None

Find a binding set by its globally unique name.

The set_name can either be a name used for gtk_binding_set_new() or the type name of a class used in gtk_binding_set_by_class().

Gtk.bindings_activate(object, keyval, modifiers)[source]
Parameters:
  • object (GObject.Object) – object to activate when binding found
  • keyval (int) – key value of the binding
  • modifiers (Gdk.ModifierType) – key modifier of the binding
Returns:

True if a binding was found and activated
Return type:

bool

Find a key binding matching keyval and modifiers and activate the binding on object.

Gtk.bindings_activate_event(object, event)[source]
Parameters:
Returns:

True if a matching key binding was found
Return type:

bool

Looks up key bindings for object to find one matching event, and if one was found, activate it.

New in version 2.4.

Gtk.builder_error_quark()[source]
Return type:int
Gtk.cairo_should_draw_window(cr, window)[source]
Parameters:
  • cr (cairo.Context) – a cairo context
  • window (Gdk.Window) – the window to check. window may not be an input-only window.
Returns:

True if window should be drawn
Return type:

bool

This function is supposed to be called in Gtk.Widget ::draw implementations for widgets that support multiple windows. cr must be untransformed from invoking of the draw function. This function will return True if the contents of the given window are supposed to be drawn and False otherwise. Note that when the drawing was not initiated by the windowing system this function will return True for all windows, so you need to draw the bottommost window first. Also, do not use “else if” statements to check which window should be drawn.

New in version 3.0.

Gtk.cairo_transform_to_window(cr, widget, window)[source]
Parameters:
  • cr (cairo.Context) – the cairo context to transform
  • widget (Gtk.Widget) – the widget the context is currently centered for
  • window (Gdk.Window) – the window to transform the context to

Transforms the given cairo context cr that from widget-relative coordinates to window-relative coordinates. If the widget’s window is not an ancestor of window, no modification will be applied.

This is the inverse to the transformation GTK applies when preparing an expose event to be emitted with the Gtk.Widget ::draw signal. It is intended to help porting multiwindow widgets from GTK+ 2 to the rendering architecture of GTK+ 3.

New in version 3.0.

Gtk.check_version(required_major, required_minor, required_micro)[source]
Parameters:
  • required_major (int) – the required major version
  • required_minor (int) – the required minor version
  • required_micro (int) – the required micro version
Returns:

None if the GTK+ library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by GTK+ and should not be modified or freed.
Return type:

str or None

Checks that the GTK+ library in use is compatible with the given version. Generally you would pass in the constants Gtk.MAJOR_VERSION, Gtk.MINOR_VERSION, Gtk.MICRO_VERSION as the three arguments to this function; that produces a check that the library in use is compatible with the version of GTK+ the application or module was compiled against.

Compatibility is defined by two things: first the version of the running library is newer than the version required_major.required_minor.`required_micro`. Second the running library must be binary compatible with the version required_major.required_minor.`required_micro` (same major version.)

This function is primarily for GTK+ modules; the module can call this function to check that it wasn’t loaded into an incompatible version of GTK+. However, such a check isn’t completely reliable, since the module may be linked against an old version of GTK+ and calling the old version of Gtk.check_version(), but still get loaded into an application using a newer version of GTK+.

Gtk.css_provider_error_quark()[source]
Return type:int
Gtk.device_grab_add(widget, device, block_others)[source]
Parameters:

Adds a GTK+ grab on device, so all the events on device and its associated pointer or keyboard (if any) are delivered to widget. If the block_others parameter is True, any other devices will be unable to interact with widget during the grab.

New in version 3.0.

Gtk.device_grab_remove(widget, device)[source]
Parameters:

Removes a device grab from the given widget.

You have to pair calls to Gtk.device_grab_add() and Gtk.device_grab_remove().

New in version 3.0.

Gtk.disable_setlocale()[source]

Prevents Gtk.init(), Gtk.init_check(), Gtk.init_with_args() and Gtk.parse_args() from automatically calling setlocale (LC_ALL, ""). You would want to use this function if you wanted to set the locale for your program to something other than the user’s locale, or if you wanted to set different values for different locale categories.

Most programs should not need to call this function.

Gtk.distribute_natural_allocation(extra_space, n_requested_sizes, sizes)[source]
Parameters:
  • extra_space (int) – Extra space to redistribute among children after subtracting minimum sizes and any child padding from the overall allocation
  • n_requested_sizes (int) – Number of requests to fit into the allocation
  • sizes (Gtk.RequestedSize) – An array of structs with a client pointer and a minimum/natural size in the orientation of the allocation.
Returns:

The remainder of extra_space after redistributing space to sizes.
Return type:

int

Distributes extra_space to child sizes by bringing smaller children up to natural size first.

The remaining space will be added to the minimum_size member of the Gtk.RequestedSize struct. If all sizes reach their natural size then the remaining space is returned.

Gtk.drag_cancel(context)[source]
Parameters:context (Gdk.DragContext) – a Gdk.DragContext, as e.g. returned by Gtk.Widget.drag_begin_with_coordinates()

Cancels an ongoing drag operation on the source side.

If you want to be able to cancel a drag operation in this way, you need to keep a pointer to the drag context, either from an explicit call to Gtk.Widget.drag_begin_with_coordinates(), or by connecting to Gtk.Widget ::drag-begin.

If context does not refer to an ongoing drag operation, this function does nothing.

If a drag is cancelled in this way, the result argument of Gtk.Widget ::drag-failed is set to Gtk.DragResult.ERROR.

New in version 3.16.

Gtk.drag_finish(context, success, del_, time_)[source]
Parameters:
  • context (Gdk.DragContext) – the drag context
  • success (bool) – a flag indicating whether the drop was successful
  • del (bool) – a flag indicating whether the source should delete the original data. (This should be True for a move)
  • time (int) – the timestamp from the Gtk.Widget ::drag-drop signal

Informs the drag source that the drop is finished, and that the data of the drag will no longer be required.

Gtk.drag_get_source_widget(context)[source]
Parameters:context (Gdk.DragContext) – a (destination side) drag context
Returns:if the drag is occurring within a single application, a pointer to the source widget. Otherwise, None.
Return type:Gtk.Widget or None

Determines the source widget for a drag.

Gtk.drag_set_icon_default(context)[source]
Parameters:context (Gdk.DragContext) – the context for a drag (This must be called with a context for the source side of a drag)

Sets the icon for a particular drag to the default icon.

Gtk.drag_set_icon_gicon(context, icon, hot_x, hot_y)[source]
Parameters:
  • context (Gdk.DragContext) – the context for a drag (This must be called with a context for the source side of a drag)
  • icon (Gio.Icon) – a Gio.Icon
  • hot_x (int) – the X offset of the hotspot within the icon
  • hot_y (int) – the Y offset of the hotspot within the icon

Sets the icon for a given drag from the given icon. See the documentation for Gtk.drag_set_icon_name() for more details about using icons in drag and drop.

New in version 3.2.

Gtk.drag_set_icon_name(context, icon_name, hot_x, hot_y)[source]
Parameters:
  • context (Gdk.DragContext) – the context for a drag (This must be called with a context for the source side of a drag)
  • icon_name (str) – name of icon to use
  • hot_x (int) – the X offset of the hotspot within the icon
  • hot_y (int) – the Y offset of the hotspot within the icon

Sets the icon for a given drag from a named themed icon. See the docs for Gtk.IconTheme for more details. Note that the size of the icon depends on the icon theme (the icon is loaded at the symbolic size Gtk.IconSize.DND), thus hot_x and hot_y have to be used with care.

New in version 2.8.

Gtk.drag_set_icon_pixbuf(context, pixbuf, hot_x, hot_y)[source]
Parameters:
  • context (Gdk.DragContext) – the context for a drag (This must be called with a context for the source side of a drag)
  • pixbuf (GdkPixbuf.Pixbuf) – the GdkPixbuf.Pixbuf to use as the drag icon
  • hot_x (int) – the X offset within widget of the hotspot
  • hot_y (int) – the Y offset within widget of the hotspot

Sets pixbuf as the icon for a given drag.

Gtk.drag_set_icon_stock(context, stock_id, hot_x, hot_y)[source]
Parameters:
  • context (Gdk.DragContext) – the context for a drag (This must be called with a context for the source side of a drag)
  • stock_id (str) – the ID of the stock icon to use for the drag
  • hot_x (int) – the X offset within the icon of the hotspot
  • hot_y (int) – the Y offset within the icon of the hotspot

Sets the icon for a given drag from a stock ID.

Deprecated since version 3.10: Use Gtk.drag_set_icon_name() instead.

Gtk.drag_set_icon_surface(context, surface)[source]
Parameters:
  • context (Gdk.DragContext) – the context for a drag (This must be called with a context for the source side of a drag)
  • surface (cairo.Surface) – the surface to use as icon

Sets surface as the icon for a given drag. GTK+ retains references for the arguments, and will release them when they are no longer needed.

To position the surface relative to the mouse, use cairo.Surface.set_device_offset() on surface. The mouse cursor will be positioned at the (0,0) coordinate of the surface.

Gtk.drag_set_icon_widget(context, widget, hot_x, hot_y)[source]
Parameters:
  • context (Gdk.DragContext) – the context for a drag. (This must be called with a context for the source side of a drag)
  • widget (Gtk.Widget) – a widget to use as an icon
  • hot_x (int) – the X offset within widget of the hotspot
  • hot_y (int) – the Y offset within widget of the hotspot

Changes the icon for drag operation to a given widget. GTK+ will not destroy the widget, so if you don’t want it to persist, you should connect to the “drag-end” signal and destroy it yourself.

Gtk.draw_insertion_cursor(widget, cr, location, is_primary, direction, draw_arrow)[source]
Parameters:

Draws a text caret on cr at location. This is not a style function but merely a convenience function for drawing the standard cursor shape.

New in version 3.0.

Deprecated since version 3.4: Use Gtk.render_insertion_cursor() instead.

Gtk.events_pending()[source]
Returns:True if any events are pending, False otherwise
Return type:bool

Checks if any events are pending.

This can be used to update the UI and invoke timeouts etc. while doing some time intensive computation.

Updating the UI during a long computation
// computation going on...

while (gtk_events_pending ())
  gtk_main_iteration ();

// ...computation continued
Gtk.false()[source]
Returns:False
Return type:bool

Analogical to Gtk.true(), this function does nothing but always returns False.

Gtk.file_chooser_error_quark()[source]
Returns:The error quark used for Gtk.FileChooser errors.
Return type:int

Registers an error quark for Gtk.FileChooser if necessary.

New in version 2.4.

Gtk.get_binary_age()[source]
Returns:the binary age of the GTK+ library
Return type:int

Returns the binary age as passed to libtool when building the GTK+ library the process is running against. If libtool means nothing to you, don’t worry about it.

New in version 3.0.

Gtk.get_current_event()[source]
Returns:a copy of the current event, or None if there is no current event. The returned event must be freed with Gdk.Event.free().
Return type:Gdk.Event or None

Obtains a copy of the event currently being processed by GTK+.

For example, if you are handling a Gtk.Button ::clicked signal, the current event will be the Gdk.EventButton that triggered the ::clicked signal.

Gtk.get_current_event_device()[source]
Returns:a Gdk.Device, or None
Return type:Gdk.Device or None

If there is a current event and it has a device, return that device, otherwise return None.

Gtk.get_current_event_state()[source]
Returns:True if there was a current event and it had a state field
state:a location to store the state of the current event
Return type:(bool, state: Gdk.ModifierType)

If there is a current event and it has a state field, place that state field in state and return True, otherwise return False.

Gtk.get_current_event_time()[source]
Returns:the timestamp from the current event, or Gdk.CURRENT_TIME.
Return type:int

If there is a current event and it has a timestamp, return that timestamp, otherwise return Gdk.CURRENT_TIME.

Gtk.get_debug_flags()[source]
Returns:the GTK+ debug flags.
Return type:int

Returns the GTK+ debug flags.

This function is intended for GTK+ modules that want to adjust their debug output based on GTK+ debug flags.

Gtk.get_default_language()[source]
Returns:the default language as a Pango.Language, must not be freed
Return type:Pango.Language

Returns the Pango.Language for the default language currently in effect. (Note that this can change over the life of an application.) The default language is derived from the current locale. It determines, for example, whether GTK+ uses the right-to-left or left-to-right text direction.

This function is equivalent to Pango.Language.get_default(). See that function for details.

Gtk.get_event_widget(event)[source]
Parameters:event (Gdk.Event) – a Gdk.Event
Returns:the widget that originally received event, or None
Return type:Gtk.Widget or None

If event is None or the event was not associated with any widget, returns None, otherwise returns the widget that received the event originally.

Gtk.get_interface_age()[source]
Returns:the interface age of the GTK+ library
Return type:int

Returns the interface age as passed to libtool when building the GTK+ library the process is running against. If libtool means nothing to you, don’t worry about it.

New in version 3.0.

Gtk.get_locale_direction()[source]
Returns:the Gtk.TextDirection of the current locale
Return type:Gtk.TextDirection

Get the direction of the current locale. This is the expected reading direction for text and UI.

This function depends on the current locale being set with setlocale() and will default to setting the Gtk.TextDirection.LTR direction otherwise. Gtk.TextDirection.NONE will never be returned.

GTK+ sets the default text direction according to the locale during Gtk.init(), and you should normally use Gtk.Widget.get_direction() or Gtk.Widget.get_default_direction() to obtain the current direcion.

This function is only needed rare cases when the locale is changed after GTK+ has already been initialized. In this case, you can use it to update the default text direction as follows:

setlocale (LC_ALL, new_locale);
direction = gtk_get_locale_direction ();
gtk_widget_set_default_direction (direction);

New in version 3.12.

Gtk.get_major_version()[source]
Returns:the major version number of the GTK+ library
Return type:int

Returns the major version number of the GTK+ library. (e.g. in GTK+ version 3.1.5 this is 3.)

This function is in the library, so it represents the GTK+ library your code is running against. Contrast with the Gtk.MAJOR_VERSION macro, which represents the major version of the GTK+ headers you have included when compiling your code.

New in version 3.0.

Gtk.get_micro_version()[source]
Returns:the micro version number of the GTK+ library
Return type:int

Returns the micro version number of the GTK+ library. (e.g. in GTK+ version 3.1.5 this is 5.)

This function is in the library, so it represents the GTK+ library your code is are running against. Contrast with the Gtk.MICRO_VERSION macro, which represents the micro version of the GTK+ headers you have included when compiling your code.

New in version 3.0.

Gtk.get_minor_version()[source]
Returns:the minor version number of the GTK+ library
Return type:int

Returns the minor version number of the GTK+ library. (e.g. in GTK+ version 3.1.5 this is 1.)

This function is in the library, so it represents the GTK+ library your code is are running against. Contrast with the Gtk.MINOR_VERSION macro, which represents the minor version of the GTK+ headers you have included when compiling your code.

New in version 3.0.

Gtk.get_option_group(open_default_display)[source]
Parameters:open_default_display (bool) – whether to open the default display when parsing the commandline arguments
Returns:a GLib.OptionGroup for the commandline arguments recognized by GTK+
Return type:GLib.OptionGroup

Returns a GLib.OptionGroup for the commandline arguments recognized by GTK+ and GDK.

You should add this group to your GLib.OptionContext with GLib.OptionContext.add_group(), if you are using GLib.OptionContext.parse() to parse your commandline arguments.

New in version 2.6.

Gtk.grab_get_current()[source]
Returns:The widget which currently has the grab or None if no grab is active
Return type:Gtk.Widget or None

Queries the current grab of the default window group.

Gtk.icon_size_from_name(name)[source]
Parameters:name (str) – the name to look up.
Returns:the icon size (Gtk.IconSize)
Return type:int

Looks up the icon size associated with name.

Deprecated since version 3.10: Use Gtk.IconTheme instead.

Gtk.icon_size_get_name(size)[source]
Parameters:size (int) – a Gtk.IconSize.
Returns:the name of the given icon size.
Return type:str

Gets the canonical name of the given icon size. The returned string is statically allocated and should not be freed.

Deprecated since version 3.10: Use Gtk.IconTheme instead.

Gtk.icon_size_lookup(size)[source]
Parameters:size (int) – an icon size (Gtk.IconSize)
Returns:True if size was a valid size
width:location to store icon width
height:location to store icon height
Return type:(bool, width: int, height: int)

Obtains the pixel size of a semantic icon size size: Gtk.IconSize.MENU, Gtk.IconSize.BUTTON, etc. This function isn’t normally needed, Gtk.IconTheme.load_icon() is the usual way to get an icon for rendering, then just look at the size of the rendered pixbuf. The rendered pixbuf may not even correspond to the width/height returned by Gtk.IconSize.lookup(), because themes are free to render the pixbuf however they like, including changing the usual size.

Gtk.icon_size_lookup_for_settings(settings, size)[source]
Parameters:
Returns:

True if size was a valid size

width:location to store icon width
height:location to store icon height

Return type:

(bool, width: int, height: int)

Obtains the pixel size of a semantic icon size, possibly modified by user preferences for a particular Gtk.Settings. Normally size would be Gtk.IconSize.MENU, Gtk.IconSize.BUTTON, etc. This function isn’t normally needed, Gtk.Widget.render_icon_pixbuf() is the usual way to get an icon for rendering, then just look at the size of the rendered pixbuf. The rendered pixbuf may not even correspond to the width/height returned by Gtk.IconSize.lookup(), because themes are free to render the pixbuf however they like, including changing the usual size.

New in version 2.2.

Deprecated since version 3.10: Use Gtk.IconSize.lookup() instead.

Gtk.icon_size_register(name, width, height)[source]
Parameters:
  • name (str) – name of the icon size
  • width (int) – the icon width
  • height (int) – the icon height
Returns:

integer value representing the size (Gtk.IconSize)
Return type:

int

Registers a new icon size, along the same lines as Gtk.IconSize.MENU, etc. Returns the integer value for the size.

Deprecated since version 3.10: Use Gtk.IconTheme instead.

Gtk.icon_size_register_alias(alias, target)[source]
Parameters:
  • alias (str) – an alias for target
  • target (int) – an existing icon size (Gtk.IconSize)

Registers alias as another name for target. So calling Gtk.IconSize.from_name() with alias as argument will return target.

Deprecated since version 3.10: Use Gtk.IconTheme instead.

Gtk.icon_theme_error_quark()[source]
Return type:int
Gtk.init(argv)[source]
Parameters:argv ([str] or None) – Address of the argv parameter of main(), or None. Any options understood by GTK+ are stripped before return.
Returns:Address of the argv parameter of main(), or None. Any options understood by GTK+ are stripped before return.
Return type:argv: [str]

Call this function before using any other GTK+ functions in your GUI applications. It will initialize everything needed to operate the toolkit and parses some standard command line options.

Although you are expected to pass the argc, argv parameters from main() to this function, it is possible to pass None if argv is not available or commandline handling is not required.

argc and argv are adjusted accordingly so your own code will never see those standard arguments.

Note that there are some alternative ways to initialize GTK+: if you are calling Gtk.parse_args(), Gtk.init_check(), Gtk.init_with_args() or GLib.OptionContext.parse() with the option group returned by Gtk.get_option_group(), you don’t have to call Gtk.init().

And if you are using Gtk.Application, you don’t have to call any of the initialization functions either; the Gtk.Application ::startup handler does it for you.

This function will terminate your program if it was unable to initialize the windowing system for some reason. If you want your program to fall back to a textual interface you want to call Gtk.init_check() instead.

Since 2.18, GTK+ calls signal (SIGPIPE, SIG_IGN) during initialization, to ignore SIGPIPE signals, since these are almost never wanted in graphical applications. If you do need to handle SIGPIPE for some reason, reset the handler after Gtk.init(), but notice that other libraries (e.g. libdbus or gvfs) might do similar things.

Gtk.init_check(argv)[source]
Parameters:argv ([str] or None) – Address of the argv parameter of main(), or None. Any options understood by GTK+ are stripped before return.
Returns:True if the commandline arguments (if any) were valid and the windowing system has been successfully initialized, False otherwise
argv:Address of the argv parameter of main(), or None. Any options understood by GTK+ are stripped before return.
Return type:(bool, argv: [str])

This function does the same work as Gtk.init() with only a single change: It does not terminate the program if the commandline arguments couldn’t be parsed or the windowing system can’t be initialized. Instead it returns False on failure.

This way the application can fall back to some other means of communication with the user - for example a curses or command line interface.

Note that calling any GTK function or instantiating any GTK type after this function returns False results in undefined behavior.

Gtk.init_with_args(argv, parameter_string, entries, translation_domain)[source]
Parameters:
  • argv ([str] or None) – Address of the argv parameter of main(), or None. Any options understood by GTK+ are stripped before return.
  • parameter_string (str or None) – a string which is displayed in the first line of --help output, after programname [OPTION...]
  • entries ([GLib.OptionEntry]) – a None-terminated array of GLib.OptionEntrys describing the options of your program
  • translation_domain (str or None) – a translation domain to use for translating the --help output for the options in entries and the parameter_string with gettext(), or None
Raises:

GLib.Error
Returns:

True if the commandline arguments (if any) were valid and if the windowing system has been successfully initialized, False otherwise

argv:Address of the argv parameter of main(), or None. Any options understood by GTK+ are stripped before return.

Return type:

(bool, argv: [str])

This function does the same work as Gtk.init_check(). Additionally, it allows you to add your own commandline options, and it automatically generates nicely formatted --help output. Note that your program will be terminated after writing out the help output.

New in version 2.6.

Gtk.key_snooper_remove(snooper_handler_id)[source]
Parameters:snooper_handler_id (int) – Identifies the key snooper to remove

Removes the key snooper function with the given id.

Deprecated since version 3.4: Key snooping should not be done. Events should be handled by widgets.

Gtk.main()[source]

Runs the main loop until Gtk.main_quit() is called.

You can nest calls to Gtk.main(). In that case Gtk.main_quit() will make the innermost invocation of the main loop return.

Gtk.main_do_event(event)[source]
Parameters:event (Gdk.Event) – An event to process (normally passed by GDK)

Processes a single GDK event.

This is public only to allow filtering of events between GDK and GTK+. You will not usually need to call this function directly.

While you should not call this function directly, you might want to know how exactly events are handled. So here is what this function does with the event:

Compress enter/leave notify events. If the event passed build an enter/leave pair together with the next event (peeked from GDK), both events are thrown away. This is to avoid a backlog of (de-)highlighting widgets crossed by the pointer.

Find the widget which got the event. If the widget can’t be determined the event is thrown away unless it belongs to a INCR transaction.

Then the event is pushed onto a stack so you can query the currently handled event with Gtk.get_current_event().

The event is sent to a widget. If a grab is active all events for widgets that are not in the contained in the grab widget are sent to the latter with a few exceptions:

  • Deletion and destruction events are still sent to the event widget for obvious reasons.
  • Events which directly relate to the visual representation of the event widget.
  • Leave events are delivered to the event widget if there was an enter event delivered to it before without the paired leave event.
  • Drag events are not redirected because it is unclear what the semantics of that would be. Another point of interest might be that all key events are first passed through the key snooper functions if there are any. Read the description of gtk_key_snooper_install() if you need this feature.

After finishing the delivery the event is popped from the event stack.

Gtk.main_iteration()[source]
Returns:True if Gtk.main_quit() has been called for the innermost mainloop
Return type:bool

Runs a single iteration of the mainloop.

If no events are waiting to be processed GTK+ will block until the next event is noticed. If you don’t want to block look at Gtk.main_iteration_do() or check if any events are pending with Gtk.events_pending() first.

Gtk.main_iteration_do(blocking)[source]
Parameters:blocking (bool) – True if you want GTK+ to block if no events are pending
Returns:True if Gtk.main_quit() has been called for the innermost mainloop
Return type:bool

Runs a single iteration of the mainloop. If no events are available either return or block depending on the value of blocking.

Gtk.main_level()[source]
Returns:the nesting level of the current invocation of the main loop
Return type:int

Asks for the current nesting level of the main loop.

Gtk.main_quit()[source]

Makes the innermost invocation of the main loop return when it regains control.

Gtk.paint_arrow(style, cr, state_type, shadow_type, widget, detail, arrow_type, fill, x, y, width, height)[source]
Parameters:

Draws an arrow in the given rectangle on cr using the given parameters. arrow_type determines the direction of the arrow.

Deprecated since version 3.0: Use Gtk.render_arrow() instead

Gtk.paint_box(style, cr, state_type, shadow_type, widget, detail, x, y, width, height)[source]
Parameters:

Draws a box on cr with the given parameters.

Deprecated since version 3.0: Use Gtk.render_frame() and Gtk.render_background() instead

Gtk.paint_box_gap(style, cr, state_type, shadow_type, widget, detail, x, y, width, height, gap_side, gap_x, gap_width)[source]
Parameters:

Draws a box in cr using the given style and state and shadow type, leaving a gap in one side.

Deprecated since version 3.0: Use Gtk.render_frame_gap() instead

Gtk.paint_check(style, cr, state_type, shadow_type, widget, detail, x, y, width, height)[source]
Parameters:

Draws a check button indicator in the given rectangle on cr with the given parameters.

Deprecated since version 3.0: Use Gtk.render_check() instead

Gtk.paint_diamond(style, cr, state_type, shadow_type, widget, detail, x, y, width, height)[source]
Parameters:

Draws a diamond in the given rectangle on window using the given parameters.

Deprecated since version 3.0: Use cairo instead

Gtk.paint_expander(style, cr, state_type, widget, detail, x, y, expander_style)[source]
Parameters:

Draws an expander as used in Gtk.TreeView. x and y specify the center the expander. The size of the expander is determined by the “expander-size” style property of widget. (If widget is not specified or doesn’t have an “expander-size” property, an unspecified default size will be used, since the caller doesn’t have sufficient information to position the expander, this is likely not useful.) The expander is expander_size pixels tall in the collapsed position and expander_size pixels wide in the expanded position.

Deprecated since version 3.0: Use Gtk.render_expander() instead

Gtk.paint_extension(style, cr, state_type, shadow_type, widget, detail, x, y, width, height, gap_side)[source]
Parameters:

Draws an extension, i.e. a notebook tab.

Deprecated since version 3.0: Use Gtk.render_extension() instead

Gtk.paint_flat_box(style, cr, state_type, shadow_type, widget, detail, x, y, width, height)[source]
Parameters:

Draws a flat box on cr with the given parameters.

Deprecated since version 3.0: Use Gtk.render_frame() and Gtk.render_background() instead

Gtk.paint_focus(style, cr, state_type, widget, detail, x, y, width, height)[source]
Parameters:
  • style (Gtk.Style) – a Gtk.Style
  • cr (cairo.Context) – a cairo.Context
  • state_type (Gtk.StateType) – a state
  • widget (Gtk.Widget or None) – the widget
  • detail (str or None) – a style detail
  • x (int) – the x origin of the rectangle around which to draw a focus indicator
  • y (int) – the y origin of the rectangle around which to draw a focus indicator
  • width (int) – the width of the rectangle around which to draw a focus indicator
  • height (int) – the height of the rectangle around which to draw a focus indicator

Draws a focus indicator around the given rectangle on cr using the given style.

Deprecated since version 3.0: Use Gtk.render_focus() instead

Gtk.paint_handle(style, cr, state_type, shadow_type, widget, detail, x, y, width, height, orientation)[source]
Parameters:

Draws a handle as used in Gtk.HandleBox and Gtk.Paned.

Deprecated since version 3.0: Use Gtk.render_handle() instead

Gtk.paint_hline(style, cr, state_type, widget, detail, x1, x2, y)[source]
Parameters:

Draws a horizontal line from (x1, y) to (x2, y) in cr using the given style and state.

Deprecated since version 3.0: Use Gtk.render_line() instead

Gtk.paint_layout(style, cr, state_type, use_text, widget, detail, x, y, layout)[source]
Parameters:

Draws a layout on cr using the given parameters.

Deprecated since version 3.0: Use Gtk.render_layout() instead

Gtk.paint_option(style, cr, state_type, shadow_type, widget, detail, x, y, width, height)[source]
Parameters:

Draws a radio button indicator in the given rectangle on cr with the given parameters.

Deprecated since version 3.0: Use Gtk.render_option() instead

Gtk.paint_resize_grip(style, cr, state_type, widget, detail, edge, x, y, width, height)[source]
Parameters:
  • style (Gtk.Style) – a Gtk.Style
  • cr (cairo.Context) – a cairo.Context
  • state_type (Gtk.StateType) – a state
  • widget (Gtk.Widget or None) – the widget
  • detail (str or None) – a style detail
  • edge (Gdk.WindowEdge) – the edge in which to draw the resize grip
  • x (int) – the x origin of the rectangle in which to draw the resize grip
  • y (int) – the y origin of the rectangle in which to draw the resize grip
  • width (int) – the width of the rectangle in which to draw the resize grip
  • height (int) – the height of the rectangle in which to draw the resize grip

Draws a resize grip in the given rectangle on cr using the given parameters.

Deprecated since version 3.0: Use Gtk.render_handle() instead

Gtk.paint_shadow(style, cr, state_type, shadow_type, widget, detail, x, y, width, height)[source]
Parameters:

Draws a shadow around the given rectangle in cr using the given style and state and shadow type.

Deprecated since version 3.0: Use Gtk.render_frame() instead

Gtk.paint_shadow_gap(style, cr, state_type, shadow_type, widget, detail, x, y, width, height, gap_side, gap_x, gap_width)[source]
Parameters:

Draws a shadow around the given rectangle in cr using the given style and state and shadow type, leaving a gap in one side.

Deprecated since version 3.0: Use Gtk.render_frame_gap() instead

Gtk.paint_slider(style, cr, state_type, shadow_type, widget, detail, x, y, width, height, orientation)[source]
Parameters:

Draws a slider in the given rectangle on cr using the given style and orientation.

Deprecated since version 3.0: Use Gtk.render_slider() instead

Gtk.paint_spinner(style, cr, state_type, widget, detail, step, x, y, width, height)[source]
Parameters:
  • style (Gtk.Style) – a Gtk.Style
  • cr (cairo.Context) – a cairo.Context
  • state_type (Gtk.StateType) – a state
  • widget (Gtk.Widget or None) – the widget (may be None)
  • detail (str or None) – a style detail (may be None)
  • step (int) – the nth step
  • x (int) – the x origin of the rectangle in which to draw the spinner
  • y (int) – the y origin of the rectangle in which to draw the spinner
  • width (int) – the width of the rectangle in which to draw the spinner
  • height (int) – the height of the rectangle in which to draw the spinner

Draws a spinner on window using the given parameters.

Deprecated since version 3.0: Use Gtk.render_icon() and the Gtk.StyleContext you are drawing instead

Gtk.paint_tab(style, cr, state_type, shadow_type, widget, detail, x, y, width, height)[source]
Parameters:

Draws an option menu tab (i.e. the up and down pointing arrows) in the given rectangle on cr using the given parameters.

Deprecated since version 3.0: Use cairo instead

Gtk.paint_vline(style, cr, state_type, widget, detail, y1_, y2_, x)[source]
Parameters:

Draws a vertical line from (x, y1_) to (x, y2_) in cr using the given style and state.

Deprecated since version 3.0: Use Gtk.render_line() instead

Gtk.paper_size_get_default()[source]
Returns:the name of the default paper size. The string is owned by GTK+ and should not be modified.
Return type:str

Returns the name of the default paper size, which depends on the current locale.

New in version 2.10.

Gtk.paper_size_get_paper_sizes(include_custom)[source]
Parameters:include_custom (bool) – whether to include custom paper sizes as defined in the page setup dialog
Returns:a newly allocated list of newly allocated Gtk.PaperSize objects
Return type:[Gtk.PaperSize]

Creates a list of known paper sizes.

New in version 2.12.

Gtk.parse_args(argv)[source]
Parameters:argv ([str]) – a pointer to the array of command line arguments
Returns:True if initialization succeeded, otherwise False
argv:a pointer to the array of command line arguments
Return type:(bool, argv: [str])

Parses command line arguments, and initializes global attributes of GTK+, but does not actually open a connection to a display. (See Gdk.Display.open(), Gdk.get_display_arg_name())

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

There is no need to call this function explicitly if you are using Gtk.init(), or Gtk.init_check().

Note that many aspects of GTK+ require a display connection to function, so this way of initializing GTK+ is really only useful for specialized use cases.

Gtk.print_error_quark()[source]
Returns:The error quark used for Gtk.PrintOperation errors.
Return type:int

Registers an error quark for Gtk.PrintOperation if necessary.

New in version 2.10.

Gtk.print_run_page_setup_dialog(parent, page_setup, settings)[source]
Parameters:
Returns:

a new Gtk.PageSetup
Return type:

Gtk.PageSetup

Runs a page setup dialog, letting the user modify the values from page_setup. If the user cancels the dialog, the returned Gtk.PageSetup is identical to the passed in page_setup, otherwise it contains the modifications done in the dialog.

Note that this function may use a recursive mainloop to show the page setup dialog. See Gtk.print_run_page_setup_dialog_async() if this is a problem.

New in version 2.10.

Gtk.print_run_page_setup_dialog_async(parent, page_setup, settings, done_cb, *data)[source]
Parameters:

Runs a page setup dialog, letting the user modify the values from page_setup.

In contrast to Gtk.print_run_page_setup_dialog(), this function returns after showing the page setup dialog on platforms that support this, and calls done_cb from a signal handler for the ::response signal of the dialog.

New in version 2.10.

Gtk.propagate_event(widget, event)[source]
Parameters:

Sends an event to a widget, propagating the event to parent widgets if the event remains unhandled.

Events received by GTK+ from GDK normally begin in Gtk.main_do_event(). Depending on the type of event, existence of modal dialogs, grabs, etc., the event may be propagated; if so, this function is used.

Gtk.propagate_event() calls Gtk.Widget.event() on each widget it decides to send the event to. So Gtk.Widget.event() is the lowest-level function; it simply emits the Gtk.Widget ::event and possibly an event-specific signal on a widget. Gtk.propagate_event() is a bit higher-level, and Gtk.main_do_event() is the highest level.

All that said, you most likely don’t want to use any of these functions; synthesizing events is rarely needed. There are almost certainly better ways to achieve your goals. For example, use Gdk.Window.invalidate_rect() or Gtk.Widget.queue_draw() instead of making up expose events.

Gtk.rc_add_default_file(filename)[source]
Parameters:filename (str) – the pathname to the file. If filename is not absolute, it is searched in the current directory.

Adds a file to the list of files to be parsed at the end of Gtk.init().

Deprecated since version 3.0: Use Gtk.StyleContext with a custom Gtk.StyleProvider instead

Gtk.rc_find_module_in_path(module_file)[source]
Parameters:module_file (str) – name of a theme engine
Returns:The filename, if found (must be freed with GLib.free()), otherwise None.
Return type:str

Searches for a theme engine in the GTK+ search path. This function is not useful for applications and should not be used.

Deprecated since version 3.0: Use Gtk.CssProvider instead.

Gtk.rc_find_pixmap_in_path(settings, scanner, pixmap_file)[source]
Parameters:
Returns:

the filename.
Return type:

str

Looks up a file in pixmap path for the specified Gtk.Settings. If the file is not found, it outputs a warning message using g_warning() and returns None.

Deprecated since version 3.0: Use Gtk.CssProvider instead.

Gtk.rc_get_default_files()[source]
Returns:A None-terminated array of filenames. This memory is owned by GTK+ and must not be freed by the application. If you want to store this information, you should make a copy.
Return type:[str]

Retrieves the current list of RC files that will be parsed at the end of Gtk.init().

Deprecated since version 3.0: Use Gtk.StyleContext instead

Gtk.rc_get_im_module_file()[source]
Returns:a newly-allocated string containing the name of the file listing the IM modules available for loading
Return type:str

Obtains the path to the IM modules file. See the documentation of the GTK_IM_MODULE_FILE environment variable for more details.

Deprecated since version 3.0: Use Gtk.CssProvider instead.

Gtk.rc_get_im_module_path()[source]
Returns:a newly-allocated string containing the path in which to look for IM modules.
Return type:str

Obtains the path in which to look for IM modules. See the documentation of the GTK_PATH environment variable for more details about looking up modules. This function is useful solely for utilities supplied with GTK+ and should not be used by applications under normal circumstances.

Deprecated since version 3.0: Use Gtk.CssProvider instead.

Gtk.rc_get_module_dir()[source]
Returns:the directory. (Must be freed with GLib.free())
Return type:str

Returns a directory in which GTK+ looks for theme engines. For full information about the search for theme engines, see the docs for GTK_PATH in Running GTK+ Applications.

Deprecated since version 3.0: Use Gtk.CssProvider instead.

Gtk.rc_get_style(widget)[source]
Parameters:widget (Gtk.Widget) – a Gtk.Widget
Returns:the resulting style. No refcount is added to the returned style, so if you want to save this style around, you should add a reference yourself.
Return type:Gtk.Style

Finds all matching RC styles for a given widget, composites them together, and then creates a Gtk.Style representing the composite appearance. (GTK+ actually keeps a cache of previously created styles, so a new style may not be created.)

Deprecated since version 3.0: Use Gtk.StyleContext instead

Gtk.rc_get_style_by_paths(settings, widget_path, class_path, type)[source]
Parameters:
  • settings (Gtk.Settings) – a Gtk.Settings object
  • widget_path (str or None) – the widget path to use when looking up the style, or None if no matching against the widget path should be done
  • class_path (str or None) – the class path to use when looking up the style, or None if no matching against the class path should be done.
  • type (GObject.GType) – a type that will be used along with parent types of this type when matching against class styles, or GObject.TYPE_NONE
Returns:

A style created by matching with the supplied paths, or None if nothing matching was specified and the default style should be used. The returned value is owned by GTK+ as part of an internal cache, so you must call GObject.Object.ref() on the returned value if you want to keep a reference to it.
Return type:

Gtk.Style or None

Creates up a Gtk.Style from styles defined in a RC file by providing the raw components used in matching. This function may be useful when creating pseudo-widgets that should be themed like widgets but don’t actually have corresponding GTK+ widgets. An example of this would be items inside a GNOME canvas widget.

The action of Gtk.rc_get_style() is similar to:

gtk_widget_path (widget, NULL, &path, NULL);
gtk_widget_class_path (widget, NULL, &class_path, NULL);
gtk_rc_get_style_by_paths (gtk_widget_get_settings (widget),
                           path, class_path,
                           G_OBJECT_TYPE (widget));

Deprecated since version 3.0: Use Gtk.StyleContext instead

Gtk.rc_get_theme_dir()[source]
Returns:The directory (must be freed with GLib.free()).
Return type:str

Returns the standard directory in which themes should be installed. (GTK+ does not actually use this directory itself.)

Deprecated since version 3.0: Use Gtk.CssProvider instead.

Gtk.rc_parse(filename)[source]
Parameters:filename (str) – the filename of a file to parse. If filename is not absolute, it is searched in the current directory.

Parses a given resource file.

Deprecated since version 3.0: Use Gtk.CssProvider instead.

Gtk.rc_parse_color(scanner)[source]
Parameters:scanner (GLib.Scanner) – a GLib.Scanner
Returns:GLib.TokenType.NONE if parsing succeeded, otherwise the token that was expected but not found
color:a pointer to a Gdk.Color in which to store the result
Return type:(int, color: Gdk.Color)

Parses a color in the format expected in a RC file.

Note that theme engines should use Gtk.rc_parse_color_full() in order to support symbolic colors.

Deprecated since version 3.0: Use Gtk.CssProvider instead

Gtk.rc_parse_color_full(scanner, style)[source]
Parameters:
Returns:

GLib.TokenType.NONE if parsing succeeded, otherwise the token that was expected but not found

color:a pointer to a Gdk.Color in which to store the result

Return type:

(int, color: Gdk.Color)

Parses a color in the format expected in a RC file. If style is not None, it will be consulted to resolve references to symbolic colors.

New in version 2.12.

Deprecated since version 3.0: Use Gtk.CssProvider instead

Gtk.rc_parse_priority(scanner, priority)[source]
Parameters:
Returns:

GLib.TokenType.NONE if parsing succeeded, otherwise the token that was expected but not found.
Return type:

int

Parses a Gtk.PathPriorityType variable from the format expected in a RC file.

Deprecated since version 3.0: Use Gtk.CssProvider instead

Gtk.rc_parse_state(scanner)[source]
Parameters:scanner (GLib.Scanner) – a GLib.Scanner (must be initialized for parsing an RC file)
Returns:GLib.TokenType.NONE if parsing succeeded, otherwise the token that was expected but not found.
state:A pointer to a Gtk.StateType variable in which to store the result.
Return type:(int, state: Gtk.StateType)

Parses a Gtk.StateType variable from the format expected in a RC file.

Deprecated since version 3.0: Use Gtk.CssProvider instead

Gtk.rc_parse_string(rc_string)[source]
Parameters:rc_string (str) – a string to parse.

Parses resource information directly from a string.

Deprecated since version 3.0: Use Gtk.CssProvider instead.

Gtk.rc_property_parse_border(pspec, gstring, property_value)[source]
Parameters:
Returns:

True if gstring could be parsed and property_value has been set to the resulting Gtk.Border.
Return type:

bool

A Gtk.RcPropertyParser for use with Gtk.Settings.install_property_parser() or gtk_widget_class_install_style_property_parser() which parses borders in the form "{ left, right, top, bottom }" for integers left, right, top and bottom.

Gtk.rc_property_parse_color(pspec, gstring, property_value)[source]
Parameters:
Returns:

True if gstring could be parsed and property_value has been set to the resulting Gdk.Color.
Return type:

bool

A Gtk.RcPropertyParser for use with Gtk.Settings.install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a color given either by its name or in the form { red, green, blue } where red, green and blue are integers between 0 and 65535 or floating-point numbers between 0 and 1.

Gtk.rc_property_parse_enum(pspec, gstring, property_value)[source]
Parameters:
Returns:

True if gstring could be parsed and property_value has been set to the resulting GObject.EnumValue.
Return type:

bool

A Gtk.RcPropertyParser for use with Gtk.Settings.install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a single enumeration value.

The enumeration value can be specified by its name, its nickname or its numeric value. For consistency with flags parsing, the value may be surrounded by parentheses.

Gtk.rc_property_parse_flags(pspec, gstring, property_value)[source]
Parameters:
Returns:

True if gstring could be parsed and property_value has been set to the resulting flags value.
Return type:

bool

A Gtk.RcPropertyParser for use with Gtk.Settings.install_property_parser() or gtk_widget_class_install_style_property_parser() which parses flags.

Flags can be specified by their name, their nickname or numerically. Multiple flags can be specified in the form "( flag1 | flag2 | ... )".

Gtk.rc_property_parse_requisition(pspec, gstring, property_value)[source]
Parameters:
Returns:

True if gstring could be parsed and property_value has been set to the resulting Gtk.Requisition.
Return type:

bool

A Gtk.RcPropertyParser for use with Gtk.Settings.install_property_parser() or gtk_widget_class_install_style_property_parser() which parses a requisition in the form "{ width, height }" for integers %width and %height.

Gtk.rc_reparse_all()[source]
Returns:True if the files were reread.
Return type:bool

If the modification time on any previously read file for the default Gtk.Settings has changed, discard all style information and then reread all previously read RC files.

Deprecated since version 3.0: Use Gtk.CssProvider instead.

Gtk.rc_reparse_all_for_settings(settings, force_load)[source]
Parameters:
Returns:

True if the files were reread.
Return type:

bool

If the modification time on any previously read file for the given Gtk.Settings has changed, discard all style information and then reread all previously read RC files.

Deprecated since version 3.0: Use Gtk.CssProvider instead.

Gtk.rc_reset_styles(settings)[source]
Parameters:settings (Gtk.Settings) – a Gtk.Settings

This function recomputes the styles for all widgets that use a particular Gtk.Settings object. (There is one Gtk.Settings object per Gdk.Screen, see Gtk.Settings.get_for_screen()); It is useful when some global parameter has changed that affects the appearance of all widgets, because when a widget gets a new style, it will both redraw and recompute any cached information about its appearance. As an example, it is used when the default font size set by the operating system changes. Note that this function doesn’t affect widgets that have a style set explicitly on them with Gtk.Widget.set_style().

New in version 2.4.

Deprecated since version 3.0: Use Gtk.CssProvider instead.

Gtk.rc_set_default_files(filenames)[source]
Parameters:filenames ([str]) – A None-terminated list of filenames.

Sets the list of files that GTK+ will read at the end of Gtk.init().

Deprecated since version 3.0: Use Gtk.StyleContext with a custom Gtk.StyleProvider instead

Gtk.recent_chooser_error_quark()[source]
Return type:int
Gtk.recent_manager_error_quark()[source]
Return type:int
Gtk.render_activity(context, cr, x, y, width, height)[source]
Parameters:

Renders an activity indicator (such as in Gtk.Spinner). The state Gtk.StateFlags.CHECKED determines whether there is activity going on.

New in version 3.0.

Gtk.render_arrow(context, cr, angle, x, y, size)[source]
Parameters:

Renders an arrow pointing to angle.

Typical arrow rendering at 0, 1⁄2 π;, π; and 3⁄2 π:

New in version 3.0.

Gtk.render_background(context, cr, x, y, width, height)[source]
Parameters:

Renders the background of an element.

Typical background rendering, showing the effect of background-image, border-width and border-radius :

New in version 3.0..

Gtk.render_background_get_clip(context, x, y, width, height)[source]
Parameters:
Returns:

return location for the clip
Return type:

out_clip: Gdk.Rectangle

Returns the area that will be affected (i.e. drawn to) when calling Gtk.render_background() for the given context and rectangle.

New in version 3.20.

Gtk.render_check(context, cr, x, y, width, height)[source]
Parameters:

Renders a checkmark (as in a Gtk.CheckButton).

The Gtk.StateFlags.CHECKED state determines whether the check is on or off, and Gtk.StateFlags.INCONSISTENT determines whether it should be marked as undefined.

Typical checkmark rendering:

New in version 3.0.

Gtk.render_expander(context, cr, x, y, width, height)[source]
Parameters:

Renders an expander (as used in Gtk.TreeView and Gtk.Expander) in the area defined by x, y, width, height. The state Gtk.StateFlags.CHECKED determines whether the expander is collapsed or expanded.

Typical expander rendering:

New in version 3.0.

Gtk.render_extension(context, cr, x, y, width, height, gap_side)[source]
Parameters:

Renders a extension (as in a Gtk.Notebook tab) in the rectangle defined by x, y, width, height. The side where the extension connects to is defined by gap_side.

Typical extension rendering:

New in version 3.0.

Gtk.render_focus(context, cr, x, y, width, height)[source]
Parameters:

Renders a focus indicator on the rectangle determined by x, y, width, height.

Typical focus rendering:

New in version 3.0.

Gtk.render_frame(context, cr, x, y, width, height)[source]
Parameters:

Renders a frame around the rectangle defined by x, y, width, height.

Examples of frame rendering, showing the effect of border-image, border-color, border-width, border-radius and junctions:

New in version 3.0.

Gtk.render_frame_gap(context, cr, x, y, width, height, gap_side, xy0_gap, xy1_gap)[source]
Parameters:

Renders a frame around the rectangle defined by (x, y, width, height), leaving a gap on one side. xy0_gap and xy1_gap will mean X coordinates for Gtk.PositionType.TOP and Gtk.PositionType.BOTTOM gap sides, and Y coordinates for Gtk.PositionType.LEFT and Gtk.PositionType.RIGHT.

Typical rendering of a frame with a gap:

New in version 3.0.

Deprecated since version 3.24: Use Gtk.render_frame() instead. Themes can create gaps by omitting borders via CSS.

Gtk.render_handle(context, cr, x, y, width, height)[source]
Parameters:

Renders a handle (as in Gtk.HandleBox, Gtk.Paned and Gtk.Window’s resize grip), in the rectangle determined by x, y, width, height.

Handles rendered for the paned and grip classes:

New in version 3.0.

Gtk.render_icon(context, cr, pixbuf, x, y)[source]
Parameters:

Renders the icon in pixbuf at the specified x and y coordinates.

This function will render the icon in pixbuf at exactly its size, regardless of scaling factors, which may not be appropriate when drawing on displays with high pixel densities.

You probably want to use Gtk.render_icon_surface() instead, if you already have a Cairo surface.

New in version 3.2.

Gtk.render_icon_pixbuf(context, source, size)[source]
Parameters:
Returns:

a newly-created GdkPixbuf.Pixbuf containing the rendered icon
Return type:

GdkPixbuf.Pixbuf

Renders the icon specified by source at the given size, returning the result in a pixbuf.

New in version 3.0.

Deprecated since version 3.10: Use Gtk.IconTheme.load_icon() instead.

Gtk.render_icon_surface(context, cr, surface, x, y)[source]
Parameters:

Renders the icon in surface at the specified x and y coordinates.

New in version 3.10.

Gtk.render_insertion_cursor(context, cr, x, y, layout, index, direction)[source]
Parameters:

Draws a text caret on cr at the specified index of layout.

New in version 3.4.

Gtk.render_layout(context, cr, x, y, layout)[source]
Parameters:

Renders layout on the coordinates x, y

New in version 3.0.

Gtk.render_line(context, cr, x0, y0, x1, y1)[source]
Parameters:

Renders a line from (x0, y0) to (x1, y1).

New in version 3.0.

Gtk.render_option(context, cr, x, y, width, height)[source]
Parameters:

Renders an option mark (as in a Gtk.RadioButton), the Gtk.StateFlags.CHECKED state will determine whether the option is on or off, and Gtk.StateFlags.INCONSISTENT whether it should be marked as undefined.

Typical option mark rendering:

New in version 3.0.

Gtk.render_slider(context, cr, x, y, width, height, orientation)[source]
Parameters:

Renders a slider (as in Gtk.Scale) in the rectangle defined by x, y, width, height. orientation defines whether the slider is vertical or horizontal.

Typical slider rendering:

New in version 3.0.

Gtk.rgb_to_hsv(r, g, b)[source]
Parameters:
Returns:

h:Return value for the hue component
s:Return value for the saturation component
v:Return value for the value component

Return type:

(h: float, s: float, v: float)

Converts a color from RGB space to HSV.

Input values must be in the [0.0, 1.0] range; output values will be in the same range.

New in version 2.14.

Gtk.selection_add_target(widget, selection, target, info)[source]
Parameters:

Appends a specified target to the list of supported targets for a given widget and selection.

Gtk.selection_add_targets(widget, selection, targets)[source]
Parameters:

Prepends a table of targets to the list of supported targets for a given widget and selection.

Gtk.selection_clear_targets(widget, selection)[source]
Parameters:

Remove all targets registered for the given selection for the widget.

Gtk.selection_convert(widget, selection, target, time_)[source]
Parameters:
  • widget (Gtk.Widget) – The widget which acts as requestor
  • selection (Gdk.Atom) – Which selection to get
  • target (Gdk.Atom) – Form of information desired (e.g., STRING)
  • time (int) – Time of request (usually of triggering event) In emergency, you could use Gdk.CURRENT_TIME
Returns:

True if requested succeeded. False if we could not process request. (e.g., there was already a request in process for this widget).
Return type:

bool

Requests the contents of a selection. When received, a “selection-received” signal will be generated.

Gtk.selection_owner_set(widget, selection, time_)[source]
Parameters:
Returns:

True if the operation succeeded
Return type:

bool

Claims ownership of a given selection for a particular widget, or, if widget is None, release ownership of the selection.

Gtk.selection_owner_set_for_display(display, widget, selection, time_)[source]
Parameters:
Returns:

True if the operation succeeded
Return type:

bool

Claim ownership of a given selection for a particular widget, or, if widget is None, release ownership of the selection.

New in version 2.2.

Gtk.selection_remove_all(widget)[source]
Parameters:widget (Gtk.Widget) – a Gtk.Widget

Removes all handlers and unsets ownership of all selections for a widget. Called when widget is being destroyed. This function will not generally be called by applications.

Gtk.set_debug_flags(flags)[source]
Parameters:flags (int) –

Sets the GTK+ debug flags.

Gtk.show_uri(screen, uri, timestamp)[source]
Parameters:
  • screen (Gdk.Screen or None) – screen to show the uri on or None for the default screen
  • uri (str) – the uri to show
  • timestamp (int) – a timestamp to prevent focus stealing
Raises:

GLib.Error
Returns:

True on success, False on error
Return type:

bool

A convenience function for launching the default application to show the uri. Like Gtk.show_uri_on_window(), but takes a screen as transient parent instead of a window.

Note that this function is deprecated as it does not pass the necessary information for helpers to parent their dialog properly, when run from sandboxed applications for example.

New in version 2.14.

Deprecated since version 3.22: Use Gtk.show_uri_on_window() instead.

Gtk.show_uri_on_window(parent, uri, timestamp)[source]
Parameters:
  • parent (Gtk.Window or None) – parent window
  • uri (str) – the uri to show
  • timestamp (int) – a timestamp to prevent focus stealing
Raises:

GLib.Error
Returns:

True on success, False on error
Return type:

bool

This is a convenience function for launching the default application to show the uri. The uri must be of a form understood by GIO (i.e. you need to install gvfs to get support for uri schemes such as http:// or ftp://, as only local files are handled by GIO itself). Typical examples are

  • file:///home/gnome/pict.jpg
  • http://www.gnome.org
  • mailto:me@gnome.org

Ideally the timestamp is taken from the event triggering the Gtk.show_uri() call. If timestamp is not known you can take Gdk.CURRENT_TIME.

This is the recommended call to be used as it passes information necessary for sandbox helpers to parent their dialogs properly.

New in version 3.22.

Gtk.stock_add(items)[source]
Parameters:items ([Gtk.StockItem]) – a Gtk.StockItem or array of items

Registers each of the stock items in items. If an item already exists with the same stock ID as one of the items, the old item gets replaced. The stock items are copied, so GTK+ does not hold any pointer into items and items can be freed. Use Gtk.stock_add_static() if items is persistent and GTK+ need not copy the array.

Deprecated since version 3.10.

Gtk.stock_add_static(items)[source]
Parameters:items ([Gtk.StockItem]) – a Gtk.StockItem or array of Gtk.StockItem

Same as Gtk.stock_add(), but doesn’t copy items, so items must persist until application exit.

Deprecated since version 3.10.

Gtk.stock_list_ids()[source]
Returns:a list of known stock IDs
Return type:[str]

Retrieves a list of all known stock IDs added to a Gtk.IconFactory or registered with Gtk.stock_add(). The list must be freed with g_slist_free(), and each string in the list must be freed with GLib.free().

Deprecated since version 3.10.

Gtk.stock_lookup(stock_id)[source]
Parameters:stock_id (str) – a stock item name
Returns:a stock item or None if the stock icon isn’t known.
Return type:Gtk.StockItem or None

Deprecated since version 3.10.

Gtk.stock_set_translate_func(domain, func, *data)[source]
Parameters:

Sets a function to be used for translating the label of a stock item.

If no function is registered for a translation domain, GLib.dgettext() is used.

The function is used for all stock items whose translation_domain matches domain. Note that it is possible to use strings different from the actual gettext translation domain of your application for this, as long as your Gtk.TranslateFunc uses the correct domain when calling dgettext(). This can be useful, e.g. when dealing with message contexts:

GtkStockItem items[] = {
 { MY_ITEM1, NC_("odd items", "Item 1"), 0, 0, "odd-item-domain" },
 { MY_ITEM2, NC_("even items", "Item 2"), 0, 0, "even-item-domain" },
};

gchar *
my_translate_func (const gchar *msgid,
                   gpointer     data)
{
  gchar *msgctxt = data;

  return (gchar*)g_dpgettext2 (GETTEXT_PACKAGE, msgctxt, msgid);
}

...

gtk_stock_add (items, G_N_ELEMENTS (items));
gtk_stock_set_translate_func ("odd-item-domain", my_translate_func, "odd items");
gtk_stock_set_translate_func ("even-item-domain", my_translate_func, "even items");

New in version 2.8.

Deprecated since version 3.10.

Gtk.target_table_free(targets)[source]
Parameters:targets ([Gtk.TargetEntry]) – a Gtk.TargetEntry array

This function frees a target table as returned by Gtk.target_table_new_from_list()

New in version 2.10.

Gtk.target_table_new_from_list(list)[source]
Parameters:list (Gtk.TargetList) – a Gtk.TargetList
Returns:the new table.
Return type:[Gtk.TargetEntry]

This function creates an Gtk.TargetEntry array that contains the same targets as the passed %list. The returned table is newly allocated and should be freed using Gtk.target_table_free() when no longer needed.

New in version 2.10.

Gtk.targets_include_image(targets, writable)[source]
Parameters:
  • targets ([Gdk.Atom]) – an array of Gdk.Atoms
  • writable (bool) – whether to accept only targets for which GTK+ knows how to convert a pixbuf into the format
Returns:

True if targets include a suitable target for images, otherwise False.
Return type:

bool

Determines if any of the targets in targets can be used to provide a GdkPixbuf.Pixbuf.

New in version 2.10.

Gtk.targets_include_rich_text(targets, buffer)[source]
Parameters:
Returns:

True if targets include a suitable target for rich text, otherwise False.
Return type:

bool

Determines if any of the targets in targets can be used to provide rich text.

New in version 2.10.

Gtk.targets_include_text(targets)[source]
Parameters:targets ([Gdk.Atom]) – an array of Gdk.Atoms
Returns:True if targets include a suitable target for text, otherwise False.
Return type:bool

Determines if any of the targets in targets can be used to provide text.

New in version 2.10.

Gtk.targets_include_uri(targets)[source]
Parameters:targets ([Gdk.Atom]) – an array of Gdk.Atoms
Returns:True if targets include a suitable target for uri lists, otherwise False.
Return type:bool

Determines if any of the targets in targets can be used to provide an uri list.

New in version 2.10.

Gtk.test_create_simple_window(window_title, dialog_text)[source]
Parameters:
  • window_title (str) – Title of the window to be displayed.
  • dialog_text (str) – Text inside the window to be displayed.
Returns:

a widget pointer to the newly created Gtk.Window.
Return type:

Gtk.Widget

Create a simple window with window title window_title and text contents dialog_text. The window will quit any running Gtk.main()-loop when destroyed, and it will automatically be destroyed upon test function teardown.

New in version 2.14.

Deprecated since version 3.20: This testing infrastructure is phased out in favor of reftests.

Gtk.test_find_label(widget, label_pattern)[source]
Parameters:
  • widget (Gtk.Widget) – Valid label or container widget.
  • label_pattern (str) – Shell-glob pattern to match a label string.
Returns:

a Gtk.Label widget if any is found.
Return type:

Gtk.Widget

This function will search widget and all its descendants for a Gtk.Label widget with a text string matching label_pattern. The label_pattern may contain asterisks “*” and question marks “?” as placeholders, GLib.pattern_match() is used for the matching. Note that locales other than “C“ tend to alter (translate” label strings, so this function is genrally only useful in test programs with predetermined locales, see gtk_test_init() for more details.

New in version 2.14.

Gtk.test_find_sibling(base_widget, widget_type)[source]
Parameters:
  • base_widget (Gtk.Widget) – Valid widget, part of a widget hierarchy
  • widget_type (GObject.GType) – Type of a aearched for sibling widget
Returns:

a widget of type widget_type if any is found.
Return type:

Gtk.Widget

This function will search siblings of base_widget and siblings of its ancestors for all widgets matching widget_type. Of the matching widgets, the one that is geometrically closest to base_widget will be returned. The general purpose of this function is to find the most likely “action” widget, relative to another labeling widget. Such as finding a button or text entry widget, given its corresponding label widget.

New in version 2.14.

Gtk.test_find_widget(widget, label_pattern, widget_type)[source]
Parameters:
  • widget (Gtk.Widget) – Container widget, usually a Gtk.Window.
  • label_pattern (str) – Shell-glob pattern to match a label string.
  • widget_type (GObject.GType) – Type of a aearched for label sibling widget.
Returns:

a valid widget if any is found or None.
Return type:

Gtk.Widget or None

This function will search the descendants of widget for a widget of type widget_type that has a label matching label_pattern next to it. This is most useful for automated GUI testing, e.g. to find the “OK” button in a dialog and synthesize clicks on it. However see Gtk.test_find_label(), Gtk.test_find_sibling() and Gtk.test_widget_click() for possible caveats involving the search of such widgets and synthesizing widget events.

New in version 2.14.

Gtk.test_list_all_types()[source]
Returns:0-terminated array of type ids
Return type:[GObject.GType]

Return the type ids that have been registered after calling Gtk.test_register_all_types().

New in version 2.14.

Gtk.test_register_all_types()[source]

Force registration of all core Gtk+ and Gdk object types. This allowes to refer to any of those object types via GObject.type_from_name() after calling this function.

New in version 2.14.

Gtk.test_slider_get_value(widget)[source]
Parameters:widget (Gtk.Widget) – valid widget pointer.
Returns:Gtk.Adjustment.get_value (adjustment) for an adjustment belonging to widget.
Return type:float

Retrive the literal adjustment value for Gtk.Range based widgets and spin buttons. Note that the value returned by this function is anything between the lower and upper bounds of the adjustment belonging to widget, and is not a percentage as passed in to Gtk.test_slider_set_perc().

New in version 2.14.

Deprecated since version 3.20: This testing infrastructure is phased out in favor of reftests.

Gtk.test_slider_set_perc(widget, percentage)[source]
Parameters:
  • widget (Gtk.Widget) – valid widget pointer.
  • percentage (float) – value between 0 and 100.

This function will adjust the slider position of all Gtk.Range based widgets, such as scrollbars or scales, it’ll also adjust spin buttons. The adjustment value of these widgets is set to a value between the lower and upper limits, according to the percentage argument.

New in version 2.14.

Deprecated since version 3.20: This testing infrastructure is phased out in favor of reftests.

Gtk.test_spin_button_click(spinner, button, upwards)[source]
Parameters:
  • spinner (Gtk.SpinButton) – valid Gtk.SpinButton widget.
  • button (int) – Number of the pointer button for the event, usually 1, 2 or 3.
  • upwards (bool) – True for upwards arrow click, False for downwards arrow click.
Returns:

whether all actions neccessary for the button click simulation were carried out successfully.
Return type:

bool

This function will generate a button click in the upwards or downwards spin button arrow areas, usually leading to an increase or decrease of spin button’s value.

New in version 2.14.

Deprecated since version 3.20: This testing infrastructure is phased out in favor of reftests.

Gtk.test_text_get(widget)[source]
Parameters:widget (Gtk.Widget) – valid widget pointer.
Returns:new 0-terminated C string, needs to be released with GLib.free().
Return type:str

Retrive the text string of widget if it is a Gtk.Label, Gtk.Editable (entry and text widgets) or Gtk.TextView.

New in version 2.14.

Deprecated since version 3.20: This testing infrastructure is phased out in favor of reftests.

Gtk.test_text_set(widget, string)[source]
Parameters:
  • widget (Gtk.Widget) – valid widget pointer.
  • string (str) – a 0-terminated C string

Set the text string of widget to string if it is a Gtk.Label, Gtk.Editable (entry and text widgets) or Gtk.TextView.

New in version 2.14.

Deprecated since version 3.20: This testing infrastructure is phased out in favor of reftests.

Gtk.test_widget_click(widget, button, modifiers)[source]
Parameters:
  • widget (Gtk.Widget) – Widget to generate a button click on.
  • button (int) – Number of the pointer button for the event, usually 1, 2 or 3.
  • modifiers (Gdk.ModifierType) – Keyboard modifiers the event is setup with.
Returns:

whether all actions neccessary for the button click simulation were carried out successfully.
Return type:

bool

This function will generate a button click (button press and button release event) in the middle of the first Gdk.Window found that belongs to widget. For windowless widgets like Gtk.Button (which returns False from Gtk.Widget.get_has_window()), this will often be an input-only event window. For other widgets, this is usually widget->window. Certain caveats should be considered when using this function, in particular because the mouse pointer is warped to the button click location, see Gdk.test_simulate_button() for details.

New in version 2.14.

Deprecated since version 3.20: This testing infrastructure is phased out in favor of reftests.

Gtk.test_widget_send_key(widget, keyval, modifiers)[source]
Parameters:
  • widget (Gtk.Widget) – Widget to generate a key press and release on.
  • keyval (int) – A Gdk keyboard value.
  • modifiers (Gdk.ModifierType) – Keyboard modifiers the event is setup with.
Returns:

whether all actions neccessary for the key event simulation were carried out successfully.
Return type:

bool

This function will generate keyboard press and release events in the middle of the first Gdk.Window found that belongs to widget. For windowless widgets like Gtk.Button (which returns False from Gtk.Widget.get_has_window()), this will often be an input-only event window. For other widgets, this is usually widget->window. Certain caveats should be considered when using this function, in particular because the mouse pointer is warped to the key press location, see Gdk.test_simulate_key() for details.

New in version 2.14.

Gtk.test_widget_wait_for_draw(widget)[source]
Parameters:widget (Gtk.Widget) – the widget to wait for

Enters the main loop and waits for widget to be “drawn”. In this context that means it waits for the frame clock of widget to have run a full styling, layout and drawing cycle.

This function is intended to be used for syncing with actions that depend on widget relayouting or on interaction with the display server.

New in version 3.10.

Gtk.tree_get_row_drag_data(selection_data)[source]
Parameters:selection_data (Gtk.SelectionData) – a Gtk.SelectionData
Returns:True if selection_data had target type %GTK_TREE_MODEL_ROW and is otherwise valid
tree_model:a Gtk.TreeModel
path:row in tree_model
Return type:(bool, tree_model: Gtk.TreeModel or None, path: Gtk.TreePath or None)

Obtains a tree_model and path from selection data of target type %GTK_TREE_MODEL_ROW. Normally called from a drag_data_received handler. This function can only be used if selection_data originates from the same process that’s calling this function, because a pointer to the tree model is being passed around. If you aren’t in the same process, then you’ll get memory corruption. In the Gtk.TreeDragDest drag_data_received handler, you can assume that selection data of type %GTK_TREE_MODEL_ROW is in from the current process. The returned path must be freed with Gtk.TreePath.free().

Gtk.tree_row_reference_deleted(proxy, path)[source]
Parameters:

Lets a set of row reference created by Gtk.TreeRowReference.new_proxy() know that the model emitted the Gtk.TreeModel ::row-deleted signal.

Gtk.tree_row_reference_inserted(proxy, path)[source]
Parameters:

Lets a set of row reference created by Gtk.TreeRowReference.new_proxy() know that the model emitted the Gtk.TreeModel ::row-inserted signal.

Gtk.tree_set_row_drag_data(selection_data, tree_model, path)[source]
Parameters:
Returns:

True if the Gtk.SelectionData had the proper target type to allow us to set a tree row
Return type:

bool

Sets selection data of target type %GTK_TREE_MODEL_ROW. Normally used in a drag_data_get handler.

Gtk.true()[source]
Returns:True
Return type:bool

All this function does it to return True.

This can be useful for example if you want to inhibit the deletion of a window. Of course you should not do this as the user expects a reaction from clicking the close icon of the window…

A persistent window
#include <gtk/gtk.h>

int
main (int argc, char **argv)
{
  GtkWidget *win, *but;
  const char *text = "Close yourself. I mean it!";

  gtk_init (&argc, &argv);

  win = gtk_window_new (GTK_WINDOW_TOPLEVEL);
  g_signal_connect (win,
                    "delete-event",
                    G_CALLBACK (gtk_true),
                    NULL);
  g_signal_connect (win, "destroy",
                    G_CALLBACK (gtk_main_quit),
                    NULL);

  but = gtk_button_new_with_label (text);
  g_signal_connect_swapped (but, "clicked",
                            G_CALLBACK (gtk_object_destroy),
                            win);
  gtk_container_add (GTK_CONTAINER (win), but);

  gtk_widget_show_all (win);

  gtk_main ();

  return 0;
}