Functions

accelerator_get_default_mod_mask() → ModifierType

Gets the modifier mask.

The modifier mask determines which modifiers are considered significant for keyboard accelerators. This includes all keyboard modifiers except for %GDK_LOCK_MASK.

Returns:

the modifier mask for accelerators

accelerator_get_label(accelerator_key: int, accelerator_mods: ModifierType) → str

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

Parameters:

• accelerator_key – accelerator keyval

• accelerator_mods – accelerator modifier mask

Returns:

a newly-allocated string representing the accelerator

accelerator_get_label_with_keycode(display: Display | None, accelerator_key: int, keycode: int, accelerator_mods: ModifierType) → str

Converts an accelerator keyval and modifier mask into a string that can be displayed to the user.

The string may be translated.

This function is similar to accelerator_get_label, but handling keycodes. This is only useful for system-level components, applications should use accelerator_get_label instead.

Parameters:

• display – a GdkDisplay or None to use the default display

• accelerator_key – accelerator keyval

• keycode – accelerator keycode

• accelerator_mods – accelerator modifier mask

Returns:

a newly-allocated string representing the accelerator

accelerator_name(accelerator_key: int, accelerator_mods: ModifierType) → str

Converts an accelerator keyval and modifier mask into a string parseable by accelerator_parse().

For example, if you pass in %GDK_KEY_q and %GDK_CONTROL_MASK, this function returns <Control>q.

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

Parameters:

• accelerator_key – accelerator keyval

• accelerator_mods – accelerator modifier mask

Returns:

a newly-allocated accelerator name

accelerator_name_with_keycode(display: Display | None, accelerator_key: int, keycode: int, accelerator_mods: ModifierType) → str

Converts an accelerator keyval and modifier mask into a string parseable by accelerator_parse_with_keycode().

This is similar to accelerator_name but handling keycodes. This is only useful for system-level components, applications should use accelerator_name instead.

Parameters:

• display – a GdkDisplay or None to use the default display

• accelerator_key – accelerator keyval

• keycode – accelerator keycode

• accelerator_mods – accelerator modifier mask

Returns:

a newly allocated accelerator name.

accelerator_parse(accelerator: str) → tuple[bool, int, ModifierType]

Parses a string representing an accelerator.

The format looks like “<Control>a” or “<Shift><Alt>F1”.

The parser is fairly liberal and allows lower or upper case, and also abbreviations such as “<Ctl>” and “<Ctrl>”.

Key names are parsed using 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>-”.

Modifiers are enclosed in angular brackets <>, and match the ModifierType mask:

• <Shift> for GDK_SHIFT_MASK

• <Ctrl> for GDK_CONTROL_MASK

• <Alt> for GDK_ALT_MASK

• <Meta> for GDK_META_MASK

• <Super> for GDK_SUPER_MASK

• <Hyper> for GDK_HYPER_MASK

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

Parameters:

accelerator – string representing an accelerator

accelerator_parse_with_keycode(accelerator: str, display: Display | None = None) → tuple[bool, int, list[int], ModifierType]

Parses a string representing an accelerator.

This is similar to accelerator_parse but handles keycodes as well. This is only useful for system-level components, applications should use accelerator_parse instead.

If accelerator_codes is given and the result stored in it is non-None, the result must be freed with 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).

Parameters:

• accelerator – string representing an accelerator

• display – the GdkDisplay to look up accelerator_codes in

Returns:

True if parsing succeeded

accelerator_valid(keyval: int, modifiers: ModifierType) → bool

Determines whether a given keyval and modifier mask constitute a valid keyboard accelerator.

For example, the %GDK_KEY_a keyval plus %GDK_CONTROL_MASK mark is valid, and matches the “Ctrl+a” accelerator. But, you can’t, for instance, use the %GDK_KEY_Control_L keyval as an accelerator.

Parameters:

• keyval – a GDK keyval

• modifiers – modifier mask

Returns:

True if the accelerator is valid

accessible_property_init_value(property: AccessibleProperty, value: Any) → None

Parameters:

• property

• value

accessible_relation_init_value(relation: AccessibleRelation, value: Any) → None

Parameters:

• relation

• value

accessible_state_init_value(state: AccessibleState, value: Any) → None

Parameters:

• state

• value

bitset_iter_init_at(set: Bitset, target: int) → tuple[bool, BitsetIter, int]

Parameters:

• set

• target

bitset_iter_init_first(set: Bitset) → tuple[bool, BitsetIter, int]

Parameters:

set

bitset_iter_init_last(set: Bitset) → tuple[bool, BitsetIter, int]

Parameters:

set

builder_error_quark() → int

check_version(required_major: int, required_minor: int, required_micro: int) → str | None

Checks that the GTK library in use is compatible with the given version.

Generally you would pass in the constants MAJOR_VERSION, MINOR_VERSION, 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 check_version(), but still get loaded into an application using a newer version of GTK.

Parameters:

• required_major – the required major version

• required_minor – the required minor version

• required_micro – 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.

constraint_vfl_parser_error_quark() → int

css_parser_error_quark() → int

css_parser_warning_quark() → int

dialog_error_quark() → int

disable_setlocale() → None

Prevents init and init_check 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.

distribute_natural_allocation(extra_space: int, sizes: Sequence[RequestedSize]) → 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 GtkRequestedSize struct. If all sizes reach their natural size then the remaining space is returned.

Parameters:

• extra_space – Extra space to redistribute among children after subtracting minimum sizes and any child padding from the overall allocation

• sizes – 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.

editable_delegate_get_property(object: Object, prop_id: int, value: Any, pspec: ParamSpec) → bool

Parameters:

• object

• prop_id

• value

• pspec

editable_delegate_set_property(object: Object, prop_id: int, value: Any, pspec: ParamSpec) → bool

Parameters:

• object

• prop_id

• value

• pspec

editable_install_properties(object_class: ObjectClass, first_prop: int) → int

Parameters:

• object_class

• first_prop

enumerate_printers(func: Callable[[...], bool], wait: bool, *data: Any) → None

Calls a function for all GtkPrinter’s.

If func returns True, the enumeration is stopped.

Parameters:

• func – a function to call for each printer

• wait – if True, wait in a recursive mainloop until all printers are enumerated; otherwise return early

• data – user data to pass to func

file_chooser_error_quark() → int

get_binary_age() → int

Returns the binary age as passed to libtool.

If libtool means nothing to you, don’t worry about it.

Returns:

the binary age of the GTK library

get_debug_flags() → DebugFlags

Returns the GTK debug flags that are currently active.

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

Returns:

the GTK debug flags.

get_default_language() → Language

Returns the PangoLanguage 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 get_default. See that function for details.

Returns:

the default language

get_interface_age() → int

Returns the interface age as passed to libtool.

If libtool means nothing to you, don’t worry about it.

Returns:

the interface age of the GTK library

get_locale_direction() → 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 LTR direction otherwise. NONE will never be returned.

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

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:

``include`` <locale.h>

static void
update_locale (const char *new_locale)
{
  setlocale (LC_ALL, new_locale);
  gtk_widget_set_default_direction (gtk_get_locale_direction ());
}

Returns:

the direction of the current locale

get_major_version() → int

Returns the major version number of the GTK library.

For example, 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 MAJOR_VERSION macro, which represents the major version of the GTK headers you have included when compiling your code.

Returns:

the major version number of the GTK library

get_micro_version() → int

Returns the micro version number of the GTK library.

For example, 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 MICRO_VERSION macro, which represents the micro version of the GTK headers you have included when compiling your code.

Returns:

the micro version number of the GTK library

get_minor_version() → int

Returns the minor version number of the GTK library.

For example, 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 MINOR_VERSION macro, which represents the minor version of the GTK headers you have included when compiling your code.

Returns:

the minor version number of the GTK library

hsv_to_rgb(h: float, s: float, v: float) → tuple[float, float, float]

Converts a color from HSV space to RGB.

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

Parameters:

• h – Hue

• s – Saturation

• v – Value

icon_theme_error_quark() → int

init() → None

Call this function before using any other GTK functions in your GUI applications. It will initialize everything needed to operate the toolkit.

If you are using GtkApplication, you usually don’t have to call this function; the GApplication::startup handler does it for you. Though, if you are using GApplication methods that will be invoked before startup, such as local_command_line, you may need to initialize stuff explicitly.

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, call init_check instead.

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 init(), but notice that other libraries (e.g. libdbus or gvfs) might do similar things.

init_check() → bool

This function does the same work as init() with only a single change: It does not terminate the program if 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.

Returns:

True if the windowing system has been successfully initialized, False otherwise

is_initialized() → bool

Use this function to check if GTK has been initialized.

See init.

Returns:

the initialization status

native_get_for_surface(surface: Surface) → Native | None

Parameters:

surface

paper_size_get_default() → str

paper_size_get_paper_sizes(include_custom: bool) → list[PaperSize]

Parameters:

include_custom

param_spec_expression(name: str, nick: str, blurb: str, flags: ParamFlags) → ParamSpec

Creates a new GParamSpec instance for a property holding a GtkExpression.

See :func:`~gi.repository.GObject.GObject.ParamSpec.internal` for details on the property strings.

Parameters:

• name – canonical name of the property

• nick – a user-readable name for the property

• blurb – a user-readable description of the property

• flags – flags for the property

Returns:

a newly created property specification

print_error_quark() → int

print_run_page_setup_dialog(parent: Window | None, page_setup: PageSetup | None, settings: PrintSettings) → PageSetup

Runs a page setup dialog, letting the user modify the values from page_setup. If the user cancels the dialog, the returned GtkPageSetup 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 print_run_page_setup_dialog_async() if this is a problem.

Parameters:

• parent – transient parent

• page_setup – an existing GtkPageSetup

• settings – a GtkPrintSettings

Returns:

a new GtkPageSetup

print_run_page_setup_dialog_async(parent: Window | None, page_setup: PageSetup | None, settings: PrintSettings, done_cb: Callable[[...], None], *data: Any) → None

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

In contrast to 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.

Parameters:

• parent – transient parent

• page_setup – an existing GtkPageSetup

• settings – a GtkPrintSettings

• done_cb – a function to call when the user saves the modified page setup

• data – user data to pass to done_cb

recent_manager_error_quark() → int

render_activity(context: StyleContext, cr: Context, x: float, y: float, width: float, height: float) → None

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

• context – a GtkStyleContext

• cr – a cairo_t

• x – X origin of the rectangle

• y – Y origin of the rectangle

• width – rectangle width

• height – rectangle height

render_arrow(context: StyleContext, cr: Context, angle: float, x: float, y: float, size: float) → None

Renders an arrow pointing to angle.

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

• context – a GtkStyleContext

• cr – a cairo_t

• angle – arrow angle from 0 to 2 * ``%G_PI``, being 0 the arrow pointing to the north

• x – X origin of the render area

• y – Y origin of the render area

• size – square side for render area

render_background(context: StyleContext, cr: Context, x: float, y: float, width: float, height: float) → None

Renders the background of an element.

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

• context – a GtkStyleContext

• cr – a cairo_t

• x – X origin of the rectangle

• y – Y origin of the rectangle

• width – rectangle width

• height – rectangle height

render_check(context: StyleContext, cr: Context, x: float, y: float, width: float, height: float) → None

Renders a checkmark (as in a GtkCheckButton).

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

Typical checkmark rendering:

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

• context – a GtkStyleContext

• cr – a cairo_t

• x – X origin of the rectangle

• y – Y origin of the rectangle

• width – rectangle width

• height – rectangle height

render_expander(context: StyleContext, cr: Context, x: float, y: float, width: float, height: float) → None

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

Typical expander rendering:

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

• context – a GtkStyleContext

• cr – a cairo_t

• x – X origin of the rectangle

• y – Y origin of the rectangle

• width – rectangle width

• height – rectangle height

render_focus(context: StyleContext, cr: Context, x: float, y: float, width: float, height: float) → None

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

Typical focus rendering:

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

• context – a GtkStyleContext

• cr – a cairo_t

• x – X origin of the rectangle

• y – Y origin of the rectangle

• width – rectangle width

• height – rectangle height

render_frame(context: StyleContext, cr: Context, x: float, y: float, width: float, height: float) → None

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:

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

• context – a GtkStyleContext

• cr – a cairo_t

• x – X origin of the rectangle

• y – Y origin of the rectangle

• width – rectangle width

• height – rectangle height

render_handle(context: StyleContext, cr: Context, x: float, y: float, width: float, height: float) → None

Renders a handle (as in GtkPaned and GtkWindow’s resize grip), in the rectangle determined by x, y, width, height.

Handles rendered for the paned and grip classes:

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

• context – a GtkStyleContext

• cr – a cairo_t

• x – X origin of the rectangle

• y – Y origin of the rectangle

• width – rectangle width

• height – rectangle height

render_icon(context: StyleContext, cr: Context, texture: Texture, x: float, y: float) → None

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

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

• context – a GtkStyleContext

• cr – a cairo_t

• texture – a GdkTexture containing the icon to draw

• x – X position for the texture

• y – Y position for the texture

render_layout(context: StyleContext, cr: Context, x: float, y: float, layout: Layout) → None

Renders layout on the coordinates x, y

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

• context – a GtkStyleContext

• cr – a cairo_t

• x – X origin

• y – Y origin

• layout – the PangoLayout to render

render_line(context: StyleContext, cr: Context, x0: float, y0: float, x1: float, y1: float) → None

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

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

• context – a GtkStyleContext

• cr – a cairo_t

• x0 – X coordinate for the origin of the line

• y0 – Y coordinate for the origin of the line

• x1 – X coordinate for the end of the line

• y1 – Y coordinate for the end of the line

render_option(context: StyleContext, cr: Context, x: float, y: float, width: float, height: float) → None

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

Typical option mark rendering:

Deprecated since version 4.10: Please do not use it in newly written code

Parameters:

• context – a GtkStyleContext

• cr – a cairo_t

• x – X origin of the rectangle

• y – Y origin of the rectangle

• width – rectangle width

• height – rectangle height

rgb_to_hsv(r: float, g: float, b: float) → tuple[float, float, 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.

Parameters:

• r – Red

• g – Green

• b – Blue

set_debug_flags(flags: DebugFlags) → None

Sets the GTK debug flags.

Parameters:

flags – the debug flags to set

show_uri(parent: Window | None, uri: str, timestamp: int) → None

This function launches the default application for showing a given uri, or shows an error dialog if that fails.

Deprecated since version 4.10: Use launch or launch instead

Parameters:

• parent – parent window

• uri – the uri to show

• timestamp – timestamp from the event that triggered this call, or ``%GDK_CURRENT_TIME``

show_uri_full(parent: Window | None, uri: str, timestamp: int, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

This function launches the default application for showing a given uri.

The callback will be called when the launch is completed. It should call show_uri_full_finish() to obtain the result.

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

Deprecated since version 4.10: Use launch or launch instead

Parameters:

• parent – parent window

• uri – the uri to show

• timestamp – timestamp from the event that triggered this call, or ``%GDK_CURRENT_TIME``

• cancellable – a GCancellable to cancel the launch

• callback – a callback to call when the action is complete

• user_data – data to pass to callback

show_uri_full_finish(parent: Window, result: AsyncResult) → bool

Finishes the show_uri() call and returns the result of the operation.

Deprecated since version 4.10: Use launch_finish or launch_finish instead

Parameters:

• parent – the GtkWindow passed to show_uri()

• result – GAsyncResult that was passed to callback

Returns:

True if the URI was shown successfully. Otherwise, False is returned and error is set

test_accessible_assertion_message_role(domain: str, file: str, line: int, func: str, expr: str, accessible: Accessible, expected_role: AccessibleRole, actual_role: AccessibleRole) → None

Parameters:

• domain

• file

• line

• func

• expr

• accessible

• expected_role

• actual_role

test_accessible_has_property(accessible: Accessible, property: AccessibleProperty) → bool

Checks whether the GtkAccessible has property set.

Parameters:

• accessible – a GtkAccessible

• property – a GtkAccessibleProperty

Returns:

True if the property is set in the accessible

test_accessible_has_relation(accessible: Accessible, relation: AccessibleRelation) → bool

Checks whether the GtkAccessible has relation set.

Parameters:

• accessible – a GtkAccessible

• relation – a GtkAccessibleRelation

Returns:

True if the relation is set in the accessible

test_accessible_has_role(accessible: Accessible, role: AccessibleRole) → bool

Checks whether the GtkAccessible:accessible-role of the accessible is role.

Parameters:

• accessible – a GtkAccessible

• role – a GtkAccessibleRole

Returns:

True if the role matches

test_accessible_has_state(accessible: Accessible, state: AccessibleState) → bool

Checks whether the GtkAccessible has state set.

Parameters:

• accessible – a GtkAccessible

• state – a GtkAccessibleState

Returns:

True if the state is set in the accessible

test_list_all_types() → list[type]

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

Returns:

0-terminated array of type ids

test_register_all_types() → None

Force registration of all core GTK object types.

This allows to refer to any of those object types via type_from_name() after calling this function.

test_widget_wait_for_draw(widget: Widget) → None

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.

Parameters:

widget – the widget to wait for

tree_create_row_drag_content(tree_model: TreeModel, path: TreePath) → ContentProvider

Creates a content provider for dragging path from tree_model.

Deprecated since version 4.10: Use list models instead

Parameters:

• tree_model – a GtkTreeModel

• path – a row in tree_model

Returns:

a new GdkContentProvider

tree_get_row_drag_data(value: Any) → tuple[bool, TreeModel, TreePath]

Obtains a tree_model and path from value of target type %GTK_TYPE_TREE_ROW_DATA.

The returned path must be freed with free().

Deprecated since version 4.10: Use list models instead

Parameters:

value – a GValue

Returns:

True if selection_data had target type %GTK_TYPE_TREE_ROW_DATA is otherwise valid

tree_row_reference_deleted(proxy: Object, path: TreePath) → None

Parameters:

• proxy

• path

tree_row_reference_inserted(proxy: Object, path: TreePath) → None

Parameters:

• proxy

• path

value_dup_expression(value: Any) → Expression | None

Retrieves the GtkExpression stored inside the given value, and acquires a reference to it.

Parameters:

value – a GValue initialized with type GTK_TYPE_EXPRESSION

Returns:

a GtkExpression

value_get_expression(value: Any) → Expression | None

Retrieves the GtkExpression stored inside the given value.

Parameters:

value – a GValue initialized with type GTK_TYPE_EXPRESSION

Returns:

a GtkExpression

value_set_expression(value: Any, expression: Expression) → None

Stores the given GtkExpression inside value.

The GValue will acquire a reference to the expression.

Parameters:

• value – a GValue initialized with type GTK_TYPE_EXPRESSION

• expression – a GtkExpression

value_take_expression(value: Any, expression: Expression | None = None) → None

Stores the given GtkExpression inside value.

This function transfers the ownership of the expression to the GValue.

Parameters:

• value – a GValue initialized with type GTK_TYPE_EXPRESSION

• expression – a GtkExpression