The rectangle representing the area allocated for a widget by its parent.

The priority of an accessibility announcement.

The possible values for the [gtk.types.AccessibleProperty.Autocomplete] accessible property.

The possible values for the [gtk.types.AccessibleState.Invalid] accessible state.

Note that the [gtk.types.AccessibleInvalidState.False] and [gtk.types.AccessibleInvalidState.True] have the same values as false and true.

The various platform states which can be queried using [gtk.accessible.Accessible.getPlatformState].

The possible accessible properties of a iface@Accessible.

The possible accessible relations of a iface@Accessible.

Accessible relations can be references to other widgets, integers or strings.

The accessible role for a iface@Accessible implementation.

Abstract roles are only used as part of the ontology; application developers must not use abstract roles in their code.

The possible values for the [gtk.types.AccessibleProperty.Sort] accessible property.

The possible accessible states of a iface@Accessible.

The type of contents change operation.

The granularity for queries about the text contents of a [gtk.accessible_text.AccessibleText] implementation.

The possible values for the [gtk.types.AccessibleState.Pressed] accessible state.

Note that the [gtk.types.AccessibleTristate.False] and [gtk.types.AccessibleTristate.True] have the same values as false and true.

Controls how a widget deals with extra space in a single dimension.

Alignment only matters if the widget receives a “too large” allocation, for example if you packed the widget with the [gtk.widget.Widget.hexpand] property inside a class@Box, then the widget might get extra space. If you have for example a 16x16 icon inside a 32x32 space, the icon could be scaled and stretched, it could be centered, or it could be positioned to one side of the space.

Note that in horizontal context [gtk.types.Align.Start] and [gtk.types.Align.End] are interpreted relative to text direction.

Baseline support is optional for containers and widgets, and is only available for vertical alignment. `GTK_ALIGN_BASELINE_CENTER and [gtk.types.Align.BaselineFill] are treated similar to [gtk.types.Align.Center] and [gtk.types.Align.Fill], except that it positions the widget to line up the baselines, where that is supported.

Types of user actions that may be blocked by [gtk.application.Application].

See [gtk.application.Application.inhibit].

Used to indicate the direction in which an arrow should point.

Determines the page role inside a [gtk.assistant.Assistant].

The role is used to handle buttons sensitivity and visibility.

Note that an assistant needs to end its page flow with a page of type [gtk.types.AssistantPageType.Confirm], [gtk.types.AssistantPageType.Summary] or [gtk.types.AssistantPageType.Progress] to be correct.

The Cancel button will only be shown if the page isn’t “committed”. See [gtk.assistant.Assistant.commit] for details.

Baseline position in a row of widgets.

Whenever a container has some form of natural row it may align children in that row along a common typographical baseline. If the amount of vertical space in the row is taller than the total requested height of the baseline-aligned children then it can use a [gtk.types.BaselinePosition] to select where to put the baseline inside the extra available space.

Describes how the border of a UI element should be rendered.

The list of flags that can be passed to [gtk.builder.Builder.createClosure].

New values may be added in the future for new features, so external implementations of [gtk.builder_scope.BuilderScope] should test the flags for unknown values and raise a [gtk.types.BuilderError.InvalidAttribute] error when they encounter one.

Error codes that identify various errors that can occur while using [gtk.builder.Builder].

Prebuilt sets of buttons for [gtk.dialog.Dialog].

If none of these choices are appropriate, simply use [gtk.types.ButtonsType.None] and call [gtk.dialog.Dialog.addButtons].

Please note that [gtk.types.ButtonsType.Ok], [gtk.types.ButtonsType.YesNo]

and [gtk.types.ButtonsType.OkCancel] are discouraged by the

GNOME Human Interface Guidelines.

The available modes for property@Gtk.CellRendererAccel:accel-mode.

Identifies how the user can interact with a particular cell.

Tells how a cell is to be rendered.

Describes how a [gtk.string_sorter.StringSorter] turns strings into sort keys to compare them.

Note that the result of sorting will in general depend on the current locale unless the mode is @GTK_COLLATION_NONE.

The widget attributes that can be used when creating a class@Constraint.

The relation between two terms of a constraint.

The strength of a constraint, expressed as a symbolic constant.

The strength of a class@Constraint can be expressed with any positive integer; the values of this enumeration can be used for readability.

Domain for VFL parsing errors.

Controls how a content should be made to fit inside an allocation.

Specifies which corner a child widget should be placed in when packed into a GtkScrolledWindow.

This is effectively the opposite of where the scroll bars are placed.

Errors that can occur while parsing CSS.

These errors are unexpected and will cause parts of the given CSS to be ignored.

Warnings that can occur while parsing CSS.

Unlike [gtk.types.CssParserError]s, warnings do not cause the parser to skip any input, but they indicate issues that should be fixed.

Flags to use with [gtk.global.setDebugFlags].

Settings these flags causes GTK to print out different types of debugging information. Some of these flags are only available when GTK has been configured with -Ddebug=true.

Passed to various keybinding signals for deleting text.

Error codes in the GTK_DIALOG_ERROR domain that can be returned by async dialog functions.

Flags used to influence dialog construction.

Focus movement types.

The identifiers for [gtk.editable.Editable] properties.

See [gtk.editable.Editable.installProperties] for details on how to implement the [gtk.editable.Editable] interface.

Specifies the side of the entry at which an icon is placed.

Describes the behavior of a [gtk.event_controller_scroll.EventControllerScroll].

Describes the state of a [gdk.event_sequence.EventSequence] in a class@Gesture.

Describes whether a [gtk.file_chooser.FileChooser] is being used to open existing files or to save to a possibly new file.

These identify the various errors that can occur while calling [gtk.file_chooser.FileChooser] functions.

Describes changes in a filter in more detail and allows objects using the filter to optimize refiltering items.

If you are writing an implementation and are not sure which value to pass, [gtk.types.FilterChange.Different] is always a correct choice.

Describes the known strictness of a filter.

Note that for filters where the strictness is not known, [gtk.types.FilterMatch.Some] is always an acceptable value, even if a filter does match all or no items.

Specifies the granularity of font selection that is desired in a [gtk.font_chooser.FontChooser].

This enumeration may be extended in the future; applications should ignore unknown values.

The level of granularity for the font selection.

Depending on this value, the [pango.font_description.FontDescription] that is returned by [gtk.font_dialog_button.FontDialogButton.getFontDesc] will have more or less fields set.

Represents the state of graphics offlodading.

Used to specify options for [gtk.icon_theme.IconTheme.lookupIcon].

Built-in icon sizes.

Icon sizes default to being inherited. Where they cannot be inherited, text size is the default.

All widgets which use [gtk.types.IconSize] set the normal-icons or large-icons style classes correspondingly, and let themes determine the actual size to be used with the -gtk-icon-size CSS property.

Error codes for [gtk.icon_theme.IconTheme] operations.

An enum for determining where a dropped item goes.

Describes the image data representation used by a [gtk.image.Image].

If you want to get the image from the widget, you can only get the currently-stored representation; for instance, if the [gtk.image.Image.getStorageType] returns [gtk.types.ImageType.Paintable], then you can call [gtk.image.Image.getPaintable].

For empty images, you can request any storage type (call any of the "get" functions), but they will all return null values.

Describes hints that might be taken into account by input methods or applications.

Note that input methods may already tailor their behaviour according to the enum@InputPurpose of the entry.

Some common sense is expected when using these flags - mixing [gtk.types.InputHints.Lowercase] with any of the uppercase hints makes no sense.

This enumeration may be extended in the future; input methods should ignore unknown values.

Describes primary purpose of the input widget.

This information is useful for on-screen keyboards and similar input methods to decide which keys should be presented to the user.

Note that the purpose is not meant to impose a totally strict rule about allowed characters, and does not replace input validation. It is fine for an on-screen keyboard to let the user override the character set restriction that is expressed by the purpose. The application is expected to validate the entry contents, even if it specified a purpose.

The difference between [gtk.types.InputPurpose.Digits] and [gtk.types.InputPurpose.Number] is that the former accepts only digits while the latter also some punctuation (like commas or points, plus, minus) and “e” or “E” as in 3.14E+000.

This enumeration may be extended in the future; input methods should interpret unknown values as “free form”.

The different methods to handle text in #GtkInscription when it doesn't fit the available space.

Used for justifying the text inside a class@Label widget.

Describes how class@LevelBar contents should be rendered.

Note that this enumeration could be extended with additional modes in the future.

The type of license for an application.

This enumeration can be expanded at later date.

List of actions to perform when scrolling to items in a list widget.

Used to configure the focus behavior in the [gtk.types.DirectionType.TabForward] and [gtk.types.DirectionType.TabBackward] direction, like the <kbd>Tab</kbd> key in a [gtk.list_view.ListView].

The type of message being displayed in a class@MessageDialog.

Passed as argument to various keybinding signals for moving the cursor position.

Options for selecting a different wrap mode for natural size requests.

See for example the property@Gtk.Label:natural-wrap-mode property.

The parameter used in the action signals of [gtk.notebook.Notebook].

Used to determine the layout of pages on a sheet when printing multiple pages per sheet.

Describes the way two values can be compared.

These values can be used with a [glib.types.CompareFunc]. However, a [glib.types.CompareFunc] is allowed to return any integer values. For converting such a value to a [gtk.types.Ordering] value, use func@Gtk.Ordering.from_cmpfunc.

Represents the orientation of widgets and other objects.

Typical examples are class@Box or class@GesturePan.

Defines how content overflowing a given area should be handled.

This is used in [gtk.widget.Widget.setOverflow]. The [gtk.widget.Widget.overflow] property is modeled after the CSS overflow property, but implements it only partially.

Represents the packing location of a children in its parent.

See class@WindowControls for example.

The type of a pad action.

See also [gtk.print_settings.PrintSettings.setOrientation].

See also [gtk.print_job.PrintJob.setPageSet].

Describes the panning direction of a class@GesturePan.

Flags that influence the behavior of [gtk.widget.Widget.pick].

Determines how the size should be computed to achieve the one of the visibility mode for the scrollbars.

Flags that affect how [gtk.popover_menu.PopoverMenu] widgets built from a [gio.menu_model.MenuModel] are created and displayed.

Describes which edge of a widget a certain feature is positioned at.

For examples, see the tabs of a class@Notebook, or the label of a class@Scale.

Specifies which features the print dialog should offer.

If neither [gtk.types.PrintCapabilities.GeneratePdf] nor [gtk.types.PrintCapabilities.GeneratePs] is specified, GTK assumes that all formats are supported.

See also [gtk.print_settings.PrintSettings.setDuplex].

Error codes that identify various errors that can occur while using the GTK printing support.

Determines what action the print operation should perform.

A parameter of this typs is passed to [gtk.print_operation.PrintOperation.run].

The result of a print operation.

A value of this type is returned by [gtk.print_operation.PrintOperation.run].

See also [gtk.print_job.PrintJob.setPages]

See also [gtk.print_settings.PrintSettings.setQuality].

The status gives a rough indication of the completion of a running print operation.

Describes limits of a class@EventController for handling events targeting other widgets.

Describes the stage at which events are fed into a class@EventController.

Error codes for [gtk.recent_manager.RecentManager] operations

Predefined values for use as response ids in [gtk.dialog.Dialog.addButton].

All predefined values are negative; GTK leaves values of 0 or greater for application-defined response ids.

These enumeration values describe the possible transitions when the child of a [gtk.revealer.Revealer] widget is shown or hidden.

Passed as argument to various keybinding signals.

Scrolling types.

Defines the policy to be used in a scrollable widget when updating the scrolled window adjustments in a given orientation.

Used to control what selections users are allowed to make.

Determines how GTK handles the sensitivity of various controls, such as combo box buttons.

List of flags that can be passed to action activation.

More flags may be added in the future.

Describes where class@Shortcuts added to a class@ShortcutController get handled.

GtkShortcutType specifies the kind of shortcut that is being described.

More values may be added to this enumeration over time.

The mode of the size group determines the directions in which the size group affects the requested sizes of its component widgets.

Specifies a preference for height-for-width or width-for-height geometry management.

Determines the direction of a sort.

Describes changes in a sorter in more detail and allows users to optimize resorting.

Describes the type of order that a [gtk.sorter.Sorter] may produce.

Determines whether the spin button displays values outside the adjustment bounds.

See [gtk.spin_button.SpinButton.setUpdatePolicy].

The values of the GtkSpinType enumeration are used to specify the change to make in [gtk.spin_button.SpinButton.spin].

Possible transitions between pages in a [gtk.stack.Stack] widget.

New values may be added to this enumeration over time.

Describes a widget state.

Widget states are used to match the widget against CSS pseudo-classes. Note that GTK extends the regular CSS classes and sometimes uses different names.

Specifies how search strings are matched inside text.

Flags that modify the behavior of [gtk.style_context.StyleContext.toString_].

New values may be added to this enumeration.

The indexes of colors passed to symbolic color rendering, such as vfunc@Gtk.SymbolicPaintable.snapshot_symbolic.

More values may be added over time.

Values that can be passed to the vfunc@Gtk.Widget.system_setting_changed vfunc.

The values indicate which system setting has changed. Widgets may need to drop caches, or react otherwise.

Most of the values correspond to class@Settings properties.

More values may be added over time.

Reading directions for text.

Granularity types that extend the text selection. Use the GtkTextView::extend-selection signal to customize the selection.

Flags affecting how a search is done.

If neither [gtk.types.TextSearchFlags.VisibleOnly] nor [gtk.types.TextSearchFlags.TextOnly] are enabled, the match must be exact; the special 0xFFFC character will match embedded paintables or child widgets.

Used to reference the layers of [gtk.text_view.TextView] for the purpose of customized drawing with the ::snapshot_layer vfunc.

Used to reference the parts of [gtk.text_view.TextView].

These flags indicate various properties of a [gtk.tree_model.TreeModel].

They are returned by [gtk.tree_model.TreeModel.getFlags], and must be static for the lifetime of the object. A more complete description of [gtk.types.TreeModelFlags.ItersPersist] can be found in the overview of this section.

The sizing method the column uses to determine its width. Please note that [gtk.types.TreeViewColumnSizing.Autosize] are inefficient for large views, and can make columns appear choppy.

An enum for determining where a dropped row goes.

Used to indicate which grid lines to draw in a tree view.

See also [gtk.print_settings.PrintSettings.setPaperWidth].

Describes a type of line wrapping.

[gtk.atcontext.ATContext] is an abstract class provided by GTK to communicate to platform-specific assistive technologies API.

Each platform supported by GTK implements a [gtk.atcontext.ATContext] subclass, and is responsible for updating the accessible state in response to state changes in [gtk.accessible.Accessible].

The [gtk.about_dialog.AboutDialog] offers a simple way to display information about a program.

The shown information includes the programs' logo, name, copyright, website and license. It is also possible to give credits to the authors, documenters, translators and artists who have worked on the program.

An about dialog is typically opened when the user selects the About option from the Help menu. All parts of the dialog are optional.

!An example GtkAboutDialog

About dialogs often contain links and email addresses. [gtk.about_dialog.AboutDialog] displays these as clickable links. By default, it calls [gtk.file_launcher.FileLauncher.launch] when a user clicks one. The behaviour can be overridden with the signal@Gtk.AboutDialog::activate-link signal.

To specify a person with an email address, use a string like Edgar Allan Poe <edgar@poe.com>. To specify a website with a title, use a string like GTK team https://www.gtk.org.

To make constructing a [gtk.about_dialog.AboutDialog] as convenient as possible, you can use the function func@Gtk.show_about_dialog which constructs and shows a dialog and keeps it around so that it can be shown again.

Note that GTK sets a default title of _("About s`")` on the dialog window (where `s is replaced by the name of the application, but in order to ensure proper translation of the title, applications should set the title property explicitly when constructing a [gtk.about_dialog.AboutDialog], as shown in the following example:
CODEBLOCK0
## CSS nodes [gtk.about_dialog.AboutDialog] has a single CSS node with the name window and style class .aboutdialog`.

[gtk.accessible.Accessible] is an interface for describing UI elements for Assistive Technologies.

Every accessible implementation has:

• a “role”, represented by a value of the [gtk.types.AccessibleRole] enumeration
• an “attribute”, represented by a set of [gtk.types.AccessibleState],

[gtk.types.AccessibleProperty] and [gtk.types.AccessibleRelation] values

The role cannot be changed after instantiating a [gtk.accessible.Accessible] implementation.

The attributes are updated every time a UI element's state changes in a way that should be reflected by assistive technologies. For instance, if a [gtk.widget.Widget] visibility changes, the [gtk.types.AccessibleState.Hidden] state will also change to reflect the [gtk.widget.Widget.visible] property.

Every accessible implementation is part of a tree of accessible objects. Normally, this tree corresponds to the widget tree, but can be customized by reimplementing the vfunc@Gtk.Accessible.get_accessible_parent, vfunc@Gtk.Accessible.get_first_accessible_child and vfunc@Gtk.Accessible.get_next_accessible_sibling virtual functions. Note that you can not create a top-level accessible object as of now, which means that you must always have a parent accessible object. Also note that when an accessible object does not correspond to a widget, and it has children, whose implementation you don't control, it is necessary to ensure the correct shape of the a11y tree by calling [gtk.accessible.Accessible.setAccessibleParent] and updating the sibling by [gtk.accessible.Accessible.updateNextAccessibleSibling].

The common interface for accessible objects.

A boxed type which wraps a list of references to GtkAccessible objects.

This interface describes ranged controls, e.g. controls which have a single value within an allowed range and that can optionally be changed by the user.

This interface is expected to be implemented by controls using the following roles:

• [gtk.types.AccessibleRole.Meter]
• [gtk.types.AccessibleRole.ProgressBar]
• [gtk.types.AccessibleRole.Scrollbar]
• [gtk.types.AccessibleRole.Slider]
• [gtk.types.AccessibleRole.SpinButton]

If that is not the case, a warning will be issued at run time.

In addition to this interface, its implementers are expected to provide the correct values for the following properties:

• [gtk.types.AccessibleProperty.ValueMax]
• [gtk.types.AccessibleProperty.ValueMin]
• [gtk.types.AccessibleProperty.ValueNow]
• [gtk.types.AccessibleProperty.ValueText]

An interface for accessible objects containing formatted text.

The [gtk.accessible_text.AccessibleText] interfaces is meant to be implemented by accessible objects that have text formatted with attributes, or non-trivial text contents.

You should use the enum@Gtk.AccessibleProperty.LABEL or the enum@Gtk.AccessibleProperty.DESCRIPTION properties for accessible objects containing simple, unformatted text.

The interface vtable for accessible objects containing text.

A range inside the text of an accessible object.

[gtk.action_bar.ActionBar] is designed to present contextual actions.

!An example GtkActionBar

It is expected to be displayed below the content and expand horizontally to fill the area.

It allows placing children at the start or the end. In addition, it contains an internal centered box which is centered with respect to the full width of the box, even if the children at either side take up different amounts of space.

GtkActionBar as GtkBuildable

The [gtk.action_bar.ActionBar] implementation of the [gtk.buildable.Buildable] interface supports adding children at the start or end sides by specifying “start” or “end” as the “type” attribute of a <child> element, or setting the center widget by specifying “center” value.

CSS nodes

actionbar
╰── revealer
   ╰── box
       ├── box.start
       │   ╰── [start children]
       ├── [center widget]
       ╰── box.end
           ╰── [end children]

A [gtk.action_bar.ActionBar]'s CSS node is called actionbar. It contains a revealer subnode, which contains a box subnode, which contains two box subnodes at the start and end of the action bar, with start and `end style classes respectively, as well as a center node that represents the center child.

Each of the boxes contains children packed for that side.

The [gtk.actionable.Actionable] interface provides a convenient way of associating widgets with actions.

It primarily consists of two properties: property@Gtk.Actionable:action-name and property@Gtk.Actionable:action-target. There are also some convenience APIs for setting these properties.

The action will be looked up in action groups that are found among the widgets ancestors. Most commonly, these will be the actions with the “win.” or “app.” prefix that are associated with the [gtk.application_window.ApplicationWindow] or [gtk.application.Application], but other action groups that are added with [gtk.widget.Widget.insertActionGroup] will be consulted as well.

The interface vtable for [gtk.actionable.Actionable].

A [gtk.shortcut_action.ShortcutAction] that calls [gtk.widget.Widget.activate].

[gtk.adjustment.Adjustment] is a model for a numeric value.

The [gtk.adjustment.Adjustment] has an associated lower and upper bound. It also contains step and page increments, and a page size.

Adjustments are used within several GTK widgets, including [gtk.spin_button.SpinButton], [gtk.viewport.Viewport], [gtk.scrollbar.Scrollbar] and [gtk.scale.Scale].

The [gtk.adjustment.Adjustment] object does not update the value itself. Instead it is left up to the owner of the [gtk.adjustment.Adjustment] to control the value.

A [gtk.alert_dialog.AlertDialog] object collects the arguments that are needed to present a message to the user.

The message is shown with the [gtk.alert_dialog.AlertDialog.choose] function. This API follows the GIO async pattern, and the result can be obtained by calling [gtk.alert_dialog.AlertDialog.chooseFinish].

If you don't need to wait for a button to be clicked, you can use [gtk.alert_dialog.AlertDialog.show].

A [gtk.shortcut_trigger.ShortcutTrigger] that combines two triggers.

The [gtk.alternative_trigger.AlternativeTrigger] triggers when either of two trigger.

This can be cascaded to combine more than two triggers.

[gtk.any_filter.AnyFilter] matches an item when at least one of its filters matches.

To add filters to a [gtk.any_filter.AnyFilter], use [gtk.multi_filter.MultiFilter.append].

[gtk.app_chooser.AppChooser] is an interface for widgets which allow the user to choose an application.

The main objects that implement this interface are [gtk.app_chooser_widget.AppChooserWidget], [gtk.app_chooser_dialog.AppChooserDialog] and [gtk.app_chooser_button.AppChooserButton].

Applications are represented by GIO [gio.app_info.AppInfo] objects here. GIO has a concept of recommended and fallback applications for a given content type. Recommended applications are those that claim to handle the content type itself, while fallback also includes applications that handle a more generic content type. GIO also knows the default and last-used application for a given content type. The [gtk.app_chooser_widget.AppChooserWidget] provides detailed control over whether the shown list of applications should include default, recommended or fallback applications.

To obtain the application that has been selected in a [gtk.app_chooser.AppChooser], use [gtk.app_chooser.AppChooser.getAppInfo].

The [gtk.app_chooser_button.AppChooserButton] lets the user select an application.

!An example GtkAppChooserButton

Initially, a [gtk.app_chooser_button.AppChooserButton] selects the first application in its list, which will either be the most-recently used application or, if property@Gtk.AppChooserButton:show-default-item is true, the default application.

The list of applications shown in a [gtk.app_chooser_button.AppChooserButton] includes the recommended applications for the given content type. When property@Gtk.AppChooserButton:show-default-item is set, the default application is also included. To let the user chooser other applications, you can set the property@Gtk.AppChooserButton:show-dialog-item property, which allows to open a full [gtk.app_chooser_dialog.AppChooserDialog].

It is possible to add custom items to the list, using [gtk.app_chooser_button.AppChooserButton.appendCustomItem]. These items cause the signal@Gtk.AppChooserButton::custom-item-activated signal to be emitted when they are selected.

To track changes in the selected application, use the [gtk.app_chooser_button.AppChooserButton.changed] signal.

CSS nodes

[gtk.app_chooser_button.AppChooserButton] has a single CSS node with the name “appchooserbutton”.

[gtk.app_chooser_dialog.AppChooserDialog] shows a [gtk.app_chooser_widget.AppChooserWidget] inside a [gtk.dialog.Dialog].

!An example GtkAppChooserDialog

Note that [gtk.app_chooser_dialog.AppChooserDialog] does not have any interesting methods of its own. Instead, you should get the embedded [gtk.app_chooser_widget.AppChooserWidget] using [gtk.app_chooser_dialog.AppChooserDialog.getWidget] and call its methods if the generic [gtk.app_chooser.AppChooser] interface is not sufficient for your needs.

To set the heading that is shown above the [gtk.app_chooser_widget.AppChooserWidget], use [gtk.app_chooser_dialog.AppChooserDialog.setHeading].

CSS nodes

[gtk.app_chooser_dialog.AppChooserDialog] has a single CSS node with the name window and style class .appchooser.

[gtk.app_chooser_widget.AppChooserWidget] is a widget for selecting applications.

It is the main building block for [gtk.app_chooser_dialog.AppChooserDialog]. Most applications only need to use the latter; but you can use this widget as part of a larger widget if you have special needs.

[gtk.app_chooser_widget.AppChooserWidget] offers detailed control over what applications are shown, using the property@Gtk.AppChooserWidget:show-default, property@Gtk.AppChooserWidget:show-recommended, property@Gtk.AppChooserWidget:show-fallback, property@Gtk.AppChooserWidget:show-other and property@Gtk.AppChooserWidget:show-all properties. See the [gtk.app_chooser.AppChooser] documentation for more information about these groups of applications.

To keep track of the selected application, use the signal@Gtk.AppChooserWidget::application-selected and signal@Gtk.AppChooserWidget::application-activated signals.

CSS nodes

[gtk.app_chooser_widget.AppChooserWidget] has a single CSS node with name appchooser.

[gtk.application.Application] is a high-level API for writing applications.

It supports many aspects of writing a GTK application in a convenient fashion, without enforcing a one-size-fits-all model.

Currently, [gtk.application.Application] handles GTK initialization, application uniqueness, session management, provides some basic scriptability and desktop shell integration by exporting actions and menus and manages a list of toplevel windows whose life-cycle is automatically tied to the life-cycle of your application.

While [gtk.application.Application] works fine with plain [gtk.window.Window]s, it is recommended to use it together with [gtk.application_window.ApplicationWindow].

Automatic resources

[gtk.application.Application] will automatically load menus from the [gtk.builder.Builder] resource located at "gtk/menus.ui", relative to the application's resource base path (see [gio.application.Application.setResourceBasePath]). The menu with the ID "menubar" is taken as the application's menubar. Additional menus (most interesting submenus) can be named and accessed via [gtk.application.Application.getMenuById] which allows for dynamic population of a part of the menu structure.

Note that automatic resource loading uses the resource base path that is set at construction time and will not work if the resource base path is changed at a later time.

It is also possible to provide the menubar manually using [gtk.application.Application.setMenubar].

[gtk.application.Application] will also automatically setup an icon search path for the default icon theme by appending "icons" to the resource base path. This allows your application to easily store its icons as resources. See [gtk.icon_theme.IconTheme.addResourcePath] for more information.

If there is a resource located at gtk/help-overlay.ui which defines a [gtk.shortcuts_window.ShortcutsWindow] with ID help_overlay then [gtk.application.Application] associates an instance of this shortcuts window with each [gtk.application_window.ApplicationWindow] and sets up the keyboard accelerator

displays the shortcuts window, associate the item with the action win.show-help-overlay.

A simple application

is available in the GTK source code repository

[gtk.application.Application] optionally registers with a session manager of the users session (if you set the property@Gtk.Application:register-session property) and offers various functionality related to the session life-cycle.

An application can block various ways to end the session with the [gtk.application.Application.inhibit] function. Typical use cases for this kind of inhibiting are long-running, uninterruptible operations, such as burning a CD or performing a disk backup. The session manager may not honor the inhibitor, but it can be expected to inform the user about the negative consequences of ending the session while inhibitors are present.

See Also

[gtk.application_window.ApplicationWindow] is a [gtk.window.Window] subclass that integrates with [gtk.application.Application].

Notably, [gtk.application_window.ApplicationWindow] can handle an application menubar.

This class implements the [gio.action_group.ActionGroup] and [gio.action_map.ActionMap] interfaces, to let you add window-specific actions that will be exported by the associated [gtk.application.Application], together with its application-wide actions. Window-specific actions are prefixed with the “win.” prefix and application-wide actions are prefixed with the “app.” prefix. Actions must be addressed with the prefixed name when referring to them from a [gio.menu_model.MenuModel].

Note that widgets that are placed inside a [gtk.application_window.ApplicationWindow] can also activate these actions, if they implement the [gtk.actionable.Actionable] interface.

The settings property@Gtk.Settings:gtk-shell-shows-app-menu and property@Gtk.Settings:gtk-shell-shows-menubar tell GTK whether the desktop environment is showing the application menu and menubar models outside the application as part of the desktop shell. For instance, on OS X, both menus will be displayed remotely; on Windows neither will be.

If the desktop environment does not display the menubar, then [gtk.application_window.ApplicationWindow] will automatically show a menubar for it. This behaviour can be overridden with the property@Gtk.ApplicationWindow:show-menubar property. If the desktop environment does not display the application menu, then it will automatically be included in the menubar or in the windows client-side decorations.

See [gtk.popover_menu.PopoverMenu] for information about the XML language used by [gtk.builder.Builder] for menu models.

See also: [gtk.application.Application.setMenubar].

A GtkApplicationWindow with a menubar

The code sample below shows how to set up a [gtk.application_window.ApplicationWindow] with a menu bar defined on the [gtk.application.Application]:

GtkApplication *app = gtk_application_new ("org.gtk.test", 0);

GtkBuilder *builder = gtk_builder_new_from_string (
   "<interface>"
   "  <menu id='menubar'>"
   "    <submenu>"
   "      <attribute name='label' translatable='yes'>_Edit</attribute>"
   "      <item>"
   "        <attribute name='label' translatable='yes'>_Copy</attribute>"
   "        <attribute name='action'>win.copy</attribute>"
   "      </item>"
   "      <item>"
   "        <attribute name='label' translatable='yes'>_Paste</attribute>"
   "        <attribute name='action'>win.paste</attribute>"
   "      </item>"
   "    </submenu>"
   "  </menu>"
   "</interface>",
   -1);

GMenuModel *menubar = G_MENU_MODEL (gtk_builder_get_object (builder, "menubar"));
gtk_application_set_menubar (GTK_APPLICATION (app), menubar);
g_object_unref (builder);

// ...

GtkWidget *window = gtk_application_window_new (app);

[gtk.aspect_frame.AspectFrame] preserves the aspect ratio of its child.

The frame can respect the aspect ratio of the child widget, or use its own aspect ratio.

CSS nodes

[gtk.aspect_frame.AspectFrame] uses a CSS node with name frame.

Accessibility

Until GTK 4.10, [gtk.aspect_frame.AspectFrame] used the [gtk.types.AccessibleRole.Group] role.

Starting from GTK 4.12, [gtk.aspect_frame.AspectFrame] uses the [gtk.types.AccessibleRole.Generic] role.

[gtk.assistant.Assistant] is used to represent a complex as a series of steps.

!An example GtkAssistant

Each step consists of one or more pages. [gtk.assistant.Assistant] guides the user through the pages, and controls the page flow to collect the data needed for the operation.

[gtk.assistant.Assistant] handles which buttons to show and to make sensitive based on page sequence knowledge and the [gtk.types.AssistantPageType] of each page in addition to state information like the completed and committed page statuses.

If you have a case that doesn’t quite fit in [gtk.assistant.Assistant]s way of handling buttons, you can use the [gtk.types.AssistantPageType.Custom] page type and handle buttons yourself.

[gtk.assistant.Assistant] maintains a [gtk.assistant_page.AssistantPage] object for each added child, which holds additional per-child properties. You obtain the [gtk.assistant_page.AssistantPage] for a child with [gtk.assistant.Assistant.getPage].

GtkAssistant as GtkBuildable

The [gtk.assistant.Assistant] implementation of the [gtk.buildable.Buildable] interface exposes the @action_area as internal children with the name “action_area”.

To add pages to an assistant in [gtk.builder.Builder], simply add it as a child to the [gtk.assistant.Assistant] object. If you need to set per-object properties, create a [gtk.assistant_page.AssistantPage] object explicitly, and set the child widget as a property on it.

CSS nodes

[gtk.assistant.Assistant] has a single CSS node with the name window and style class .assistant.

[gtk.assistant_page.AssistantPage] is an auxiliary object used by `GtkAssistant.

[gtk.bin_layout.BinLayout] is a [gtk.layout_manager.LayoutManager] subclass useful for create "bins" of widgets.

[gtk.bin_layout.BinLayout] will stack each child of a widget on top of each other, using the [gtk.widget.Widget.hexpand], [gtk.widget.Widget.vexpand], [gtk.widget.Widget.halign], and [gtk.widget.Widget.valign] properties of each child to determine where they should be positioned.

A [gtk.bitset.Bitset] represents a set of unsigned integers.

Another name for this data structure is "bitmap".

The current implementation is based on roaring bitmaps.

A bitset allows adding a set of integers and provides support for set operations like unions, intersections and checks for equality or if a value is contained in the set. [gtk.bitset.Bitset] also contains various functions to query metadata about the bitset, such as the minimum or maximum values or its size.

The fastest way to iterate values in a bitset is [gtk.bitset_iter.BitsetIter].

The main use case for [gtk.bitset.Bitset] is implementing complex selections for [gtk.selection_model.SelectionModel].

An opaque, stack-allocated struct for iterating over the elements of a [gtk.bitset.Bitset].

Before a [gtk.bitset_iter.BitsetIter] can be used, it needs to be initialized with [gtk.bitset_iter.BitsetIter.initFirst], [gtk.bitset_iter.BitsetIter.initLast] or [gtk.bitset_iter.BitsetIter.initAt].

[gtk.bookmark_list.BookmarkList] is a list model that wraps [glib.bookmark_file.BookmarkFile].

It presents a [gio.list_model.ListModel] and fills it asynchronously with the [gio.file_info.FileInfo]s returned from that function.

The [gio.file_info.FileInfo]s in the list have some attributes in the recent namespace added: recent::private (boolean) and recent:applications (stringv).

[gtk.bool_filter.BoolFilter] evaluates a boolean [gtk.expression.Expression] to determine whether to include items.

A struct that specifies a border around a rectangular area.

Each side can have different width.

The [gtk.box.Box] widget arranges child widgets into a single row or column.

!An example GtkBox

Whether it is a row or column depends on the value of its [gtk.orientable.Orientable.orientation] property. Within the other dimension, all children are allocated the same size. Of course, the [gtk.widget.Widget.halign] and [gtk.widget.Widget.valign] properties can be used on the children to influence their allocation.

Use repeated calls to [gtk.box.Box.append] to pack widgets into a [gtk.box.Box] from start to end. Use [gtk.box.Box.remove] to remove widgets from the [gtk.box.Box]. [gtk.box.Box.insertChildAfter] can be used to add a child at a particular position.

Use [gtk.box.Box.setHomogeneous] to specify whether or not all children of the [gtk.box.Box] are forced to get the same amount of space.

Use [gtk.box.Box.setSpacing] to determine how much space will be minimally placed between all children in the [gtk.box.Box]. Note that spacing is added

Use [gtk.box.Box.reorderChildAfter] to move a child to a different place in the box.

CSS nodes

[gtk.box.Box] uses a single CSS node with name box.

Accessibility

Until GTK 4.10, [gtk.box.Box] used the [gtk.types.AccessibleRole.Group] role.

Starting from GTK 4.12, [gtk.box.Box] uses the [gtk.types.AccessibleRole.Generic] role.

[gtk.box_layout.BoxLayout] is a layout manager that arranges children in a single row or column.

Whether it is a row or column depends on the value of its [gtk.orientable.Orientable.orientation] property. Within the other dimension all children all allocated the same size. The [gtk.box_layout.BoxLayout] will respect the [gtk.widget.Widget.halign] and [gtk.widget.Widget.valign] properties of each child widget.

If you want all children to be assigned the same size, you can use the [gtk.box_layout.BoxLayout.homogeneous] property.

If you want to specify the amount of space placed between each child, you can use the [gtk.box_layout.BoxLayout.spacing] property.

[gtk.buildable.Buildable] allows objects to extend and customize their deserialization from ui files.

The interface includes methods for setting names and properties of objects, parsing custom tags and constructing child objects.

The [gtk.buildable.Buildable] interface is implemented by all widgets and many of the non-widget objects that are provided by GTK. The main user of this interface is [gtk.builder.Builder]. There should be very little need for applications to call any of these functions directly.

An object only needs to implement this interface if it needs to extend the [gtk.builder.Builder] XML format or run any extra routines at deserialization time.

The [gtk.buildable_iface.BuildableIface] interface contains methods that are necessary to allow [gtk.builder.Builder] to construct an object from a [gtk.builder.Builder] UI definition.

An opaque context struct for [gtk.types.BuildableParser].

A sub-parser for [gtk.buildable.Buildable] implementations.

A [gtk.builder.Builder] reads XML descriptions of a user interface and instantiates the described objects.

To create a [gtk.builder.Builder] from a user interface description, call [gtk.builder.Builder.newFromFile], [gtk.builder.Builder.newFromResource] or [gtk.builder.Builder.newFromString].

In the (unusual) case that you want to add user interface descriptions from multiple sources to the same [gtk.builder.Builder] you can call [gtk.builder.Builder.new_] to get an empty builder and populate it by (multiple) calls to [gtk.builder.Builder.addFromFile], [gtk.builder.Builder.addFromResource] or [gtk.builder.Builder.addFromString].

A [gtk.builder.Builder] holds a reference to all objects that it has constructed and drops these references when it is finalized. This finalization can cause the destruction of non-widget objects or widgets which are not contained in a toplevel window. For toplevel windows constructed by a builder, it is the responsibility of the user to call [gtk.window.Window.destroy] to get rid of them and all the widgets they contain.

The functions [gtk.builder.Builder.getObject] and [gtk.builder.Builder.getObjects] can be used to access the widgets in the interface by the names assigned to them inside the UI description. Toplevel windows returned by these functions will stay around until the user explicitly destroys them with [gtk.window.Window.destroy]. Other widgets will either be part of a larger hierarchy constructed by the builder (in which case you should not have to worry about their lifecycle), or without a parent, in which case they have to be added to some container to make use of them. Non-widget objects need to be reffed with [gobject.object.ObjectWrap.ref_] to keep them beyond the lifespan of the builder.

GtkBuilder UI Definitions

[gtk.builder.Builder] parses textual descriptions of user interfaces which are specified in XML format. We refer to these descriptions as “GtkBuilder UI definitions” or just “UI definitions” if the context is clear.

Structure of UI definitions

UI definition files are always encoded in UTF-8.

The toplevel element is <interface>. It optionally takes a “domain” attribute, which will make the builder look for translated strings using dgettext() in the domain specified. This can also be done by calling [gtk.builder.Builder.setTranslationDomain] on the builder. For example:

<?xml version="1.0" encoding="UTF-8">
<interface domain="your-app">
 ...
</interface>

Requirements

The target toolkit version(s) are described by <requires> elements, the “lib” attribute specifies the widget library in question (currently the only supported value is “gtk”) and the “version” attribute specifies the target version in the form “<major>.<minor>”. [gtk.builder.Builder] will error out if the version requirements are not met. For example:

<?xml version="1.0" encoding="UTF-8">
<interface domain="your-app">
 <requires lib="gtk" version="4.0" />
</interface>

Objects

Objects are defined as children of the <interface> element.

Objects are described by <object> elements, which can contain <property> elements to set properties, <signal> elements which connect signals to handlers, and <child> elements, which describe child objects.

Typically, the specific kind of object represented by an <object> element is specified by the “class” attribute. If the type has not been loaded yet, GTK tries to find the get_type() function from the class name by applying heuristics. This works in most cases, but if necessary, it is possible to specify the name of the get_type() function explicitly with the "type-func" attribute. If your UI definition is referencing internal types, you should make sure to call [gobject.global.typeEnsure] for each object type before parsing the UI definition.

Objects may be given a name with the “id” attribute, which allows the application to retrieve them from the builder with [gtk.builder.Builder.getObject]. An id is also necessary to use the object as property value in other parts of the UI definition. GTK reserves ids starting and ending with ___ (three consecutive underscores) for its own purposes.

Properties

Setting properties of objects is pretty straightforward with the <property> element: the “name” attribute specifies the name of the property, and the content of the element specifies the value:

<object class="GtkButton">
 <property name="label">Hello, world</property>
</object>

If the “translatable” attribute is set to a true value, GTK uses gettext() (or dgettext() if the builder has a translation domain set) to find a translation for the value. This happens before the value is parsed, so it can be used for properties of any type, but it is probably most useful for string properties. It is also possible to specify a context to disambiguate short strings, and comments which may help the translators:

<object class="GtkButton">
 <property name="label" translatable="yes" context="button">Hello, world</property>
</object>

[gtk.builder.Builder] can parse textual representations for the most common property types:

• characters
• strings
• integers
• floating-point numbers
• booleans (strings like “TRUE”, “t”, “yes”, “y”, “1” are interpreted

as true values, strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted as false values)

• enumeration types (can be specified by their full C identifier their short

name used when registering the enumeration type, or their integer value)

• flag types (can be specified by their C identifier, short name, integer

value, and optionally combined with “|” for bitwise OR, e.g. “GTK_INPUT_HINT_EMOJI|GTK_INPUT_HINT_LOWERCASE”, or “emoji|lowercase”)

• colors (in a format understood by [gdk.rgba.RGBA.parse])
• [glib.variant.Variant] (can be specified in the format understood by

[glib.variant.Variant.parse])

• pixbufs (can be specified as a filename of an image file to load)

Objects can be referred to by their name and by default refer to objects declared in the local XML fragment and objects exposed via [gtk.builder.Builder.exposeObject]. In general, [gtk.builder.Builder] allows forward references to objects declared in the local XML; an object doesn’t have to be constructed before it can be referred to. The exception to this rule is that an object has to be constructed before it can be used as the value of a construct-only property.

Child objects

Many widgets have properties for child widgets, such as [gtk.expander.Expander.child]. In this case, the preferred way to specify the child widget in a ui file is to simply set the property:

<object class="GtkExpander">
 <property name="child">
   <object class="GtkLabel">
   ...
   </object>
 </property>
</object>

Generic containers that can contain an arbitrary number of children, such as [gtk.box.Box] instead use the <child> element. A <child> element contains an <object> element which describes the child object. Most often, child objects are widgets inside a container, but they can also be, e.g., actions in an action group, or columns in a tree model.

Any object type that implements the [gtk.buildable.Buildable] interface can specify how children may be added to it. Since many objects and widgets that are included with GTK already implement the [gtk.buildable.Buildable] interface, typically child objects can be added using the <child> element without having to be concerned about the underlying implementation.

See the [[gtk.widget.Widget] documentation](class.Widget.html#gtkwidget-as-gtkbuildable) for many examples of using [gtk.builder.Builder] with widgets, including setting child objects using the <child> element.

A noteworthy special case to the general rule that only objects implementing [gtk.buildable.Buildable] may specify how to handle the <child> element is that [gtk.builder.Builder] provides special support for adding objects to a [gio.list_store.ListStore] by using the <child> element. For instance:

<object class="GListStore">
 <property name="item-type">MyObject</property>
 <child>
   <object class="MyObject" />
 </child>
 ...
</object>

Property bindings

It is also possible to bind a property value to another object's property value using the attributes "bind-source" to specify the source object of the binding, and optionally, "bind-property" and "bind-flags" to specify the source property and source binding flags respectively. Internally, [gtk.builder.Builder] implements this using [gobject.binding.Binding] objects.

For instance, in the example below the “label” property of the bottom_label widget is bound to the “label” property of the top_button widget:

<object class="GtkBox">
 <property name="orientation">vertical</property>
 <child>
   <object class="GtkButton" id="top_button">
     <property name="label">Hello, world</property>
   </object>
 </child>
 <child>
   <object class="GtkLabel" id="bottom_label">
     <property name="label"
               bind-source="top_button"
               bind-property="label"
               bind-flags="sync-create" />
   </object>
 </child>
</object>

For more information, see the documentation of the [gobject.object.ObjectWrap.bindProperty] method.

Please note that another way to set up bindings between objects in .ui files is to use the [gtk.expression.Expression] methodology. See the [[gtk.expression.Expression] documentation](class.Expression.html#gtkexpression-in-ui-files) for more information.

Internal children

Sometimes it is necessary to refer to widgets which have implicitly been constructed by GTK as part of a composite widget, to set properties on them or to add further children (e.g. the content area of a [gtk.dialog.Dialog]). This can be achieved by setting the “internal-child” property of the <child> element to a true value. Note that [gtk.builder.Builder] still requires an <object> element for the internal child, even if it has already been constructed.

Specialized children

A number of widgets have different places where a child can be added (e.g. tabs vs. page content in notebooks). This can be reflected in a UI definition by specifying the “type” attribute on a <child> The possible values for the “type” attribute are described in the sections describing the widget-specific portions of UI definitions.

Signal handlers and function pointers

Signal handlers are set up with the <signal> element. The “name” attribute specifies the name of the signal, and the “handler” attribute specifies the function to connect to the signal.

<object class="GtkButton" id="hello_button">
 <signal name="clicked" handler="hello_button__clicked" />
</object>

The remaining attributes, “after”, “swapped” and “object”, have the same meaning as the corresponding parameters of the func@GObject.signal_connect_object or func@GObject.signal_connect_data functions:

• “after” matches the G_CONNECT_AFTER flag, and will ensure that the

handler is called after the default class closure for the signal

• “swapped” matches the G_CONNECT_SWAPPED flag, and will swap the

instance and closure arguments when invoking the signal handler

• “object” will bind the signal handler to the lifetime of the object

referenced by the attribute

By default "swapped" will be set to "yes" if not specified otherwise, in the case where "object" is set, for convenience. A “last_modification_time” attribute is also allowed, but it does not have a meaning to the builder.

When compiling applications for Windows, you must declare signal callbacks with the G_MODULE_EXPORT decorator, or they will not be put in the symbol table:

G_MODULE_EXPORT void
hello_button__clicked (GtkButton *button,
                      gpointer data)
{
 // ...
}

On Linux and Unix, this is not necessary; applications should instead be compiled with the -Wl,--export-dynamic argument inside their compiler flags, and linked against gmodule-export-2.0.

Example UI Definition

<interface>
 <object class="GtkDialog" id="dialog1">
   <child internal-child="content_area">
     <object class="GtkBox">
       <child internal-child="action_area">
         <object class="GtkBox">
           <child>
             <object class="GtkButton" id="ok_button">
               <property name="label" translatable="yes">_Ok</property>
               <property name="use-underline">True</property>
               <signal name="clicked" handler="ok_button_clicked"/>
             </object>
           </child>
         </object>
       </child>
     </object>
   </child>
 </object>
</interface>

Using GtkBuildable for extending UI definitions

Objects can implement the [gtk.buildable.Buildable] interface to add custom elements and attributes to the XML. Typically, any extension will be documented in each type that implements the interface.

Templates

When describing a [gtk.widget.Widget], you can use the <template> tag to describe a UI bound to a specific widget type. GTK will automatically load the UI definition when instantiating the type, and bind children and signal handlers to instance fields and function symbols.

For more information, see the [[gtk.widget.Widget] documentation](class.Widget.html#building-composite-widgets-from-template-xml) for details.

A [gtk.builder_scope.BuilderScope] implementation for the C language.

[gtk.builder_cscope.BuilderCScope] instances use symbols explicitly added to @builder with prior calls to [gtk.builder_cscope.BuilderCScope.addCallbackSymbol]. If developers want to do that, they are encouraged to create their own scopes for that purpose.

In the case that symbols are not explicitly added; GTK will uses [gmodule.module_.Module]’s introspective features (by opening the module null) to look at the application’s symbol table. From here it tries to match the signal function names given in the interface description with symbols in the application.

Note that unless [gtk.builder_cscope.BuilderCScope.addCallbackSymbol] is called for all signal callbacks which are referenced by the loaded XML, this functionality will require that [gmodule.module_.Module] be supported on the platform.

[gtk.builder_list_item_factory.BuilderListItemFactory] is a [gtk.list_item_factory.ListItemFactory] that creates widgets by instantiating [gtk.builder.Builder] UI templates.

The templates must be extending [gtk.list_item.ListItem], and typically use [gtk.expression.Expression]s to obtain data from the items in the model.

Example:

<interface>
   <template class="GtkListItem">
     <property name="child">
       <object class="GtkLabel">
         <property name="xalign">0</property>
         <binding name="label">
           <lookup name="name" type="SettingsKey">
             <lookup name="item">GtkListItem</lookup>
           </lookup>
         </binding>
       </object>
     </property>
   </template>
 </interface>

[gtk.builder_scope.BuilderScope] is an interface to provide language binding support to [gtk.builder.Builder].

The goal of [gtk.builder_scope.BuilderScope] is to look up programming-language-specific values for strings that are given in a [gtk.builder.Builder] UI file.

The primary intended audience is bindings that want to provide deeper integration of [gtk.builder.Builder] into the language.

A [gtk.builder_scope.BuilderScope] instance may be used with multiple [gtk.builder.Builder] objects, even at once.

By default, GTK will use its own implementation of [gtk.builder_scope.BuilderScope] for the C language which can be created via [gtk.builder_cscope.BuilderCScope.new_].

If you implement [gtk.builder_scope.BuilderScope] for a language binding, you may want to (partially) derive from or fall back to a [gtk.builder_cscope.BuilderCScope], as that class implements support for automatic lookups from C symbols.

The virtual function table to implement for [gtk.builder_scope.BuilderScope] implementations. Default implementations for each function do exist, but they usually just fail, so it is suggested that implementations implement all of them.

The [gtk.button.Button] widget is generally used to trigger a callback function that is called when the button is pressed.

!An example GtkButton

The [gtk.button.Button] widget can hold any valid child widget. That is, it can hold almost any other standard [gtk.widget.Widget]. The most commonly used child is the [gtk.label.Label].

CSS nodes

[gtk.button.Button] has a single CSS node with name button. The node will get the style classes .image-button or .text-button, if the content is just an image or label, respectively. It may also receive the .flat style class. When activating a button via the keyboard, the button will temporarily gain the .keyboard-activating style class.

Other style classes that are commonly used with [gtk.button.Button] include .suggested-action and .destructive-action. In special cases, buttons can be made round by adding the .circular style class.

Button-like widgets like [gtk.toggle_button.ToggleButton], [gtk.menu_button.MenuButton], [gtk.volume_button.VolumeButton], [gtk.lock_button.LockButton], [gtk.color_button.ColorButton] or [gtk.font_button.FontButton] use style classes such as .toggle, .popup, .scale, .lock, .color on the button node to differentiate themselves from a plain [gtk.button.Button].

Accessibility

[gtk.button.Button] uses the [gtk.types.AccessibleRole.Button] role.

A variant of [gtk.closure_expression.ClosureExpression] using a C closure.

[gtk.calendar.Calendar] is a widget that displays a Gregorian calendar, one month at a time.

!An example GtkCalendar

A [gtk.calendar.Calendar] can be created with [gtk.calendar.Calendar.new_].

The date that is currently displayed can be altered with [gtk.calendar.Calendar.selectDay].

To place a visual marker on a particular day, use [gtk.calendar.Calendar.markDay] and to remove the marker, [gtk.calendar.Calendar.unmarkDay]. Alternative, all marks can be cleared with [gtk.calendar.Calendar.clearMarks].

The selected date can be retrieved from a [gtk.calendar.Calendar] using [gtk.calendar.Calendar.getDate].

Users should be aware that, although the Gregorian calendar is the legal calendar in most countries, it was adopted progressively between 1582 and 1929. Display before these dates is likely to be historically incorrect.

CSS nodes

calendar.view
├── header
│   ├── button
│   ├── stack.month
│   ├── button
│   ├── button
│   ├── label.year
│   ╰── button
╰── grid
   ╰── label[.day-name][.week-number][.day-number][.other-month][.today]

[gtk.calendar.Calendar] has a main node with name calendar. It contains a subnode called header containing the widgets for switching between years and months.

The grid subnode contains all day labels, including week numbers on the left (marked with the .week-number css class) and day names on top (marked with the .day-name css class).

Day labels that belong to the previous or next month get the .other-month style class. The label of the current day get the .today style class.

Marked day labels get the :selected state assigned.

A [gtk.shortcut_action.ShortcutAction] that invokes a callback.

An abstract class for laying out [gtk.cell_renderer.CellRenderer]s

The [gtk.cell_area.CellArea] is an abstract class for [gtk.cell_layout.CellLayout] widgets (also referred to as "layouting widgets") to interface with an arbitrary number of [gtk.cell_renderer.CellRenderer]s and interact with the user for a given [gtk.tree_model.TreeModel] row.

The cell area handles events, focus navigation, drawing and size requests and allocations for a given row of data.

Usually users dont have to interact with the [gtk.cell_area.CellArea] directly unless they are implementing a cell-layouting widget themselves.

Requesting area sizes

As outlined in

GTK uses a height-for-width geometry management system to compute the sizes of widgets and user interfaces. [gtk.cell_area.CellArea] uses the same semantics to calculate the size of an area for an arbitrary number of [gtk.tree_model.TreeModel] rows.

When requesting the size of a cell area one needs to calculate the size for a handful of rows, and this will be done differently by different layouting widgets. For instance a [gtk.tree_view_column.TreeViewColumn] always lines up the areas from top to bottom while a [gtk.icon_view.IconView] on the other hand might enforce that all areas received the same width and wrap the areas around, requesting height for more cell areas when allocated less width.

It’s also important for areas to maintain some cell alignments with areas rendered for adjacent rows (cells can appear “columnized” inside an area even when the size of cells are different in each row). For this reason the [gtk.cell_area.CellArea] uses a [gtk.cell_area_context.CellAreaContext] object to store the alignments and sizes along the way (as well as the overall largest minimum and natural size for all the rows which have been calculated with the said context).

The [gtk.cell_area_context.CellAreaContext] is an opaque object specific to the [gtk.cell_area.CellArea] which created it (see [gtk.cell_area.CellArea.createContext]).

The owning cell-layouting widget can create as many contexts as it wishes to calculate sizes of rows which should receive the same size in at least one orientation (horizontally or vertically), However, it’s important that the same [gtk.cell_area_context.CellAreaContext] which was used to request the sizes for a given [gtk.tree_model.TreeModel] row be used when rendering or processing events for that row.

In order to request the width of all the rows at the root level of a [gtk.tree_model.TreeModel] one would do the following:

GtkTreeIter iter;
int minimum_width;
int natural_width;

valid = gtk_tree_model_get_iter_first (model, &iter);
while (valid)
 {
   gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE);
   gtk_cell_area_get_preferred_width (area, context, widget, NULL, NULL);

   valid = gtk_tree_model_iter_next (model, &iter);
 }

gtk_cell_area_context_get_preferred_width (context, &minimum_width, &natural_width);

Note that in this example it’s not important to observe the returned minimum and natural width of the area for each row unless the cell-layouting object is actually interested in the widths of individual rows. The overall width is however stored in the accompanying [gtk.cell_area_context.CellAreaContext] object and can be consulted at any time.

This can be useful since [gtk.cell_layout.CellLayout] widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The [gtk.cell_layout.CellLayout] widget in that case would calculate the required width of the rows in an idle or timeout source (see func@GLib.timeout_add) and when the widget is requested its actual width in vfunc@Gtk.Widget.measure it can simply consult the width accumulated so far in the [gtk.cell_area_context.CellAreaContext] object.

A simple example where rows are rendered from top to bottom and take up the full width of the layouting widget would look like:

static void
foo_get_preferred_width (GtkWidget *widget,
                        int       *minimum_size,
                        int       *natural_size)
{
 Foo *self = FOO (widget);
 FooPrivate *priv = foo_get_instance_private (self);

 foo_ensure_at_least_one_handfull_of_rows_have_been_requested (self);

 gtk_cell_area_context_get_preferred_width (priv->context, minimum_size, natural_size);
}

In the above example the Foo widget has to make sure that some row sizes have been calculated (the amount of rows that Foo judged was appropriate to request space for in a single timeout iteration) before simply returning the amount of space required by the area via the [gtk.cell_area_context.CellAreaContext].

Requesting the height for width (or width for height) of an area is a similar task except in this case the [gtk.cell_area_context.CellAreaContext] does not store the data (actually, it does not know how much space the layouting widget plans to allocate it for every row. It’s up to the layouting widget to render each row of data with the appropriate height and width which was requested by the [gtk.cell_area.CellArea]).

In order to request the height for width of all the rows at the root level of a [gtk.tree_model.TreeModel] one would do the following:

GtkTreeIter iter;
int minimum_height;
int natural_height;
int full_minimum_height = 0;
int full_natural_height = 0;

valid = gtk_tree_model_get_iter_first (model, &iter);
while (valid)
 {
   gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE);
   gtk_cell_area_get_preferred_height_for_width (area, context, widget,
                                                 width, &minimum_height, &natural_height);

   if (width_is_for_allocation)
      cache_row_height (&iter, minimum_height, natural_height);

   full_minimum_height += minimum_height;
   full_natural_height += natural_height;

   valid = gtk_tree_model_iter_next (model, &iter);
 }

Note that in the above example we would need to cache the heights returned for each row so that we would know what sizes to render the areas for each row. However we would only want to really cache the heights if the request is intended for the layouting widgets real allocation.

In some cases the layouting widget is requested the height for an arbitrary for_width, this is a special case for layouting widgets who need to request size for tens of thousands of rows. For this case it’s only important that the layouting widget calculate one reasonably sized chunk of rows and return that height synchronously. The reasoning here is that any layouting widget is at least capable of synchronously calculating enough height to fill the screen height (or scrolled window height) in response to a single call to vfunc@Gtk.Widget.measure. Returning a perfect height for width that is larger than the screen area is inconsequential since after the layouting receives an allocation from a scrolled window it simply continues to drive the scrollbar values while more and more height is required for the row heights that are calculated in the background.

Rendering Areas

Once area sizes have been acquired at least for the rows in the visible area of the layouting widget they can be rendered at vfunc@Gtk.Widget.snapshot time.

A crude example of how to render all the rows at the root level runs as follows:

GtkAllocation allocation;
GdkRectangle cell_area = { 0, };
GtkTreeIter iter;
int minimum_width;
int natural_width;

gtk_widget_get_allocation (widget, &allocation);
cell_area.width = allocation.width;

valid = gtk_tree_model_get_iter_first (model, &iter);
while (valid)
 {
   cell_area.height = get_cached_height_for_row (&iter);

   gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE);
   gtk_cell_area_render (area, context, widget, cr,
                         &cell_area, &cell_area, state_flags, FALSE);

   cell_area.y += cell_area.height;

   valid = gtk_tree_model_iter_next (model, &iter);
 }

Note that the cached height in this example really depends on how the layouting widget works. The layouting widget might decide to give every row its minimum or natural height or, if the model content is expected to fit inside the layouting widget without scrolling, it would make sense to calculate the allocation for each row at the time the widget is allocated using func@Gtk.distribute_natural_allocation.

Handling Events and Driving Keyboard Focus

Passing events to the area is as simple as handling events on any normal widget and then passing them to the [gtk.cell_area.CellArea.event] API as they come in. Usually [gtk.cell_area.CellArea] is only interested in button events, however some customized derived areas can be implemented who are interested in handling other events. Handling an event can trigger the signal@Gtk.CellArea::focus-changed signal to fire; as well as signal@Gtk.CellArea::add-editable in the case that an editable cell was clicked and needs to start editing. You can call [gtk.cell_area.CellArea.stopEditing] at any time to cancel any cell editing that is currently in progress.

The [gtk.cell_area.CellArea] drives keyboard focus from cell to cell in a way similar to [gtk.widget.Widget]. For layouting widgets that support giving focus to cells it’s important to remember to pass [gtk.types.CellRendererState.Focused] to the area functions for the row that has focus and to tell the area to paint the focus at render time.

Layouting widgets that accept focus on cells should implement the vfunc@Gtk.Widget.focus virtual method. The layouting widget is always responsible for knowing where [gtk.tree_model.TreeModel] rows are rendered inside the widget, so at vfunc@Gtk.Widget.focus time the layouting widget should use the [gtk.cell_area.CellArea] methods to navigate focus inside the area and then observe the [gtk.types.DirectionType] to pass the focus to adjacent rows and areas.

A basic example of how the vfunc@Gtk.Widget.focus virtual method should be implemented:

static gboolean
foo_focus (GtkWidget       *widget,
          GtkDirectionType direction)
{
 Foo *self = FOO (widget);
 FooPrivate *priv = foo_get_instance_private (self);
 int focus_row = priv->focus_row;
 gboolean have_focus = FALSE;

 if (!gtk_widget_has_focus (widget))
   gtk_widget_grab_focus (widget);

 valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, priv->focus_row);
 while (valid)
   {
     gtk_cell_area_apply_attributes (priv->area, priv->model, &iter, FALSE, FALSE);

     if (gtk_cell_area_focus (priv->area, direction))
       {
          priv->focus_row = focus_row;
          have_focus = TRUE;
          break;
       }
     else
       {
         if (direction == GTK_DIR_RIGHT ||
             direction == GTK_DIR_LEFT)
           break;
         else if (direction == GTK_DIR_UP ||
                  direction == GTK_DIR_TAB_BACKWARD)
          {
             if (focus_row == 0)
               break;
             else
              {
                 focus_row--;
                 valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, focus_row);
              }
           }
         else
           {
             if (focus_row == last_row)
               break;
             else
               {
                 focus_row++;
                 valid = gtk_tree_model_iter_next (priv->model, &iter);
               }
           }
       }
   }
   return have_focus;
}

Note that the layouting widget is responsible for matching the [gtk.types.DirectionType] values to the way it lays out its cells.

Cell Properties

The [gtk.cell_area.CellArea] introduces cell properties for [gtk.cell_renderer.CellRenderer]s. This provides some general interfaces for defining the relationship cell areas have with their cells. For instance in a [gtk.cell_area_box.CellAreaBox] a cell might “expand” and receive extra space when the area is allocated more than its full natural request, or a cell might be configured to “align” with adjacent rows which were requested and rendered with the same [gtk.cell_area_context.CellAreaContext].

Use [gtk.cell_area_class.CellAreaClass.installCellProperty] to install cell properties for a cell area class and [gtk.cell_area_class.CellAreaClass.findCellProperty] or [gtk.cell_area_class.CellAreaClass.listCellProperties] to get information about existing cell properties.

To set the value of a cell property, use [gtk.cell_area.CellArea.cellSetProperty], [gtk.cell_area.CellArea.cellSet] or [gtk.cell_area.CellArea.cellSetValist]. To obtain the value of a cell property, use [gtk.cell_area.CellArea.cellGetProperty] [gtk.cell_area.CellArea.cellGet] or [gtk.cell_area.CellArea.cellGetValist].

A cell area that renders GtkCellRenderers into a row or a column

The [gtk.cell_area_box.CellAreaBox] renders cell renderers into a row or a column depending on its [gtk.types.Orientation].

GtkCellAreaBox uses a notion of packing. Packing refers to adding cell renderers with reference to a particular position in a [gtk.cell_area_box.CellAreaBox]. There are two reference positions: the start and the end of the box. When the [gtk.cell_area_box.CellAreaBox] is oriented in the [gtk.types.Orientation.Vertical] orientation, the start is defined as the top of the box and the end is defined as the bottom. In the [gtk.types.Orientation.Horizontal] orientation start is defined as the left side and the end is defined as the right side.

Alignments of [gtk.cell_renderer.CellRenderer]s rendered in adjacent rows can be configured by configuring the [gtk.cell_area_box.CellAreaBox] align child cell property with [gtk.cell_area.CellArea.cellSetProperty] or by specifying the "align" argument to [gtk.cell_area_box.CellAreaBox.packStart] and [gtk.cell_area_box.CellAreaBox.packEnd].

Stores geometrical information for a series of rows in a GtkCellArea

The [gtk.cell_area_context.CellAreaContext] object is created by a given [gtk.cell_area.CellArea] implementation via its GtkCellAreaClass.create_context() virtual method and is used to store cell sizes and alignments for a series of [gtk.tree_model.TreeModel] rows that are requested and rendered in the same context.

[gtk.cell_layout.CellLayout] widgets can create any number of contexts in which to request and render groups of data rows. However, it’s important that the same context which was used to request sizes for a given [gtk.tree_model.TreeModel] row also be used for the same row when calling other [gtk.cell_area.CellArea] APIs such as [gtk.cell_area.CellArea.render] and [gtk.cell_area.CellArea.event].

Interface for widgets that can be used for editing cells

The [gtk.cell_editable.CellEditable] interface must be implemented for widgets to be usable to edit the contents of a [gtk.tree_view.TreeView] cell. It provides a way to specify how temporary widgets should be configured for editing, get the new value, etc.

An interface for packing cells

[gtk.cell_layout.CellLayout] is an interface to be implemented by all objects which want to provide a [gtk.tree_view_column.TreeViewColumn] like API for packing cells, setting attributes and data funcs.

One of the notable features provided by implementations of [gtk.cell_layout.CellLayout] are attributes. Attributes let you set the properties in flexible ways. They can just be set to constant values like regular properties. But they can also be mapped to a column of the underlying tree model with [gtk.cell_layout.CellLayout.setAttributes], which means that the value of the attribute can change from cell to cell as they are rendered by the cell renderer. Finally, it is possible to specify a function with [gtk.cell_layout.CellLayout.setCellDataFunc] that is called to determine the value of the attribute for each cell that is rendered.

GtkCellLayouts as GtkBuildable

Implementations of GtkCellLayout which also implement the GtkBuildable interface ([gtk.cell_view.CellView], [gtk.icon_view.IconView], [gtk.combo_box.ComboBox], [gtk.entry_completion.EntryCompletion], [gtk.tree_view_column.TreeViewColumn]) accept [gtk.cell_renderer.CellRenderer] objects as <child> elements in UI definitions. They support a custom <attributes> element for their children, which can contain multiple <attribute> elements. Each <attribute> element has a name attribute which specifies a property of the cell renderer; the content of the element is the attribute value.

This is an example of a UI definition fragment specifying attributes:

<object class="GtkCellView">
 <child>
   <object class="GtkCellRendererText"/>
   <attributes>
     <attribute name="text">0</attribute>
   </attributes>
 </child>
</object>

Furthermore for implementations of [gtk.cell_layout.CellLayout] that use a [gtk.cell_area.CellArea] to lay out cells (all [gtk.cell_layout.CellLayout]s in GTK use a [gtk.cell_area.CellArea])

in the format by specifying the custom <cell-packing> attribute which can contain multiple <property> elements.

Here is a UI definition fragment specifying cell properties:

<object class="GtkTreeViewColumn">
 <child>
   <object class="GtkCellRendererText"/>
   <cell-packing>
     <property name="align">True</property>
     <property name="expand">False</property>
   </cell-packing>
 </child>
</object>

Subclassing GtkCellLayout implementations

When subclassing a widget that implements [gtk.cell_layout.CellLayout] like [gtk.icon_view.IconView] or [gtk.combo_box.ComboBox], there are some considerations related to the fact that these widgets internally use a [gtk.cell_area.CellArea]. The cell area is exposed as a construct-only property by these widgets. This means that it is possible to e.g. do

GtkWIdget *combo =
 g_object_new (GTK_TYPE_COMBO_BOX, "cell-area", my_cell_area, NULL);

to use a custom cell area with a combo box. But construct properties are only initialized after instance init() functions have run, which means that using functions which rely on the existence of the cell area in your subclass init() function will cause the default cell area to be instantiated. In this case, a provided construct property value will be ignored (with a warning, to alert you to the problem).

static void
my_combo_box_init (MyComboBox *b)
{
 GtkCellRenderer *cell;

 cell = gtk_cell_renderer_pixbuf_new ();

 // The following call causes the default cell area for combo boxes,
 // a GtkCellAreaBox, to be instantiated
 gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (b), cell, FALSE);
 ...
}

GtkWidget *
my_combo_box_new (GtkCellArea *area)
{
 // This call is going to cause a warning about area being ignored
 return g_object_new (MY_TYPE_COMBO_BOX, "cell-area", area, NULL);
}

If supporting alternative cell areas with your derived widget is not important, then this does not have to concern you. If you want to support alternative cell areas, you can do so by moving the problematic calls out of init() and into a constructor() for your class.

An object for rendering a single cell

The [gtk.cell_renderer.CellRenderer] is a base class of a set of objects used for rendering a cell to a [cairo.context.Context]. These objects are used primarily by the [gtk.tree_view.TreeView] widget, though they aren’t tied to them in any specific way. It is worth noting that [gtk.cell_renderer.CellRenderer] is not a [gtk.widget.Widget] and cannot be treated as such.

The primary use of a [gtk.cell_renderer.CellRenderer] is for drawing a certain graphical elements on a [cairo.context.Context]. Typically, one cell renderer is used to draw many cells on the screen. To this extent, it isn’t expected that a CellRenderer keep any permanent state around. Instead, any state is set just prior to use using [gobject.object.ObjectWrap]s property system. Then, the cell is measured using [gtk.cell_renderer.CellRenderer.getPreferredSize]. Finally, the cell is rendered in the correct location using [gtk.cell_renderer.CellRenderer.snapshot].

There are a number of rules that must be followed when writing a new [gtk.cell_renderer.CellRenderer]. First and foremost, it’s important that a certain set of properties will always yield a cell renderer of the same size, barring a style change. The [gtk.cell_renderer.CellRenderer] also has a number of generic properties that are expected to be honored by all children.

Beyond merely rendering a cell, cell renderers can optionally provide active user interface elements. A cell renderer can be “activatable” like [gtk.cell_renderer.CellRenderer]Toggle, which toggles when it gets activated by a mouse click, or it can be “editable” like [gtk.cell_renderer.CellRenderer]Text, which allows the user to edit the text using a widget implementing the [gtk.cell_editable.CellEditable] interface, e.g. [gtk.entry.Entry]. To make a cell renderer activatable or editable, you have to implement the [gtk.cell_renderer.CellRenderer]Class.activate or [gtk.cell_renderer.CellRenderer]Class.start_editing virtual functions, respectively.

Many properties of [gtk.cell_renderer.CellRenderer] and its subclasses have a corresponding “set” property, e.g. “cell-background-set” corresponds to “cell-background”. These “set” properties reflect whether a property has been set or not. You should not set them independently.

Renders a keyboard accelerator in a cell

[gtk.cell_renderer_accel.CellRendererAccel] displays a keyboard accelerator (i.e. a key combination like Control + a). If the cell renderer is editable, the accelerator can be changed by simply typing the new combination.

Renders a combobox in a cell

[gtk.cell_renderer_combo.CellRendererCombo] renders text in a cell like [gtk.cell_renderer_text.CellRendererText] from which it is derived. But while [gtk.cell_renderer_text.CellRendererText] offers a simple entry to edit the text, [gtk.cell_renderer_combo.CellRendererCombo] offers a [gtk.combo_box.ComboBox] widget to edit the text. The values to display in the combo box are taken from the tree model specified in the [gtk.cell_renderer_combo.CellRendererCombo]:model property.

The combo cell renderer takes care of adding a text cell renderer to the combo box and sets it to display the column specified by its [gtk.cell_renderer_combo.CellRendererCombo]:text-column property. Further properties of the combo box can be set in a handler for the GtkCellRenderer::editing-started signal.

Renders a pixbuf in a cell

A [gtk.cell_renderer_pixbuf.CellRendererPixbuf] can be used to render an image in a cell. It allows to render either a given [gdkpixbuf.pixbuf.Pixbuf] (set via the GtkCellRendererPixbuf:pixbuf property) or a named icon (set via the GtkCellRendererPixbuf:icon-name property).

To support the tree view, [gtk.cell_renderer_pixbuf.CellRendererPixbuf] also supports rendering two alternative pixbufs, when the GtkCellRenderer:is-expander property is true. If the GtkCellRenderer:is-expanded property is true and the GtkCellRendererPixbuf:pixbuf-expander-open property is set to a pixbuf, it renders that pixbuf, if the GtkCellRenderer:is-expanded property is false and the GtkCellRendererPixbuf:pixbuf-expander-closed property is set to a pixbuf, it renders that one.

Renders numbers as progress bars

[gtk.cell_renderer_progress.CellRendererProgress] renders a numeric value as a progress par in a cell. Additionally, it can display a text on top of the progress bar.

Renders a spin button in a cell

[gtk.cell_renderer_spin.CellRendererSpin] renders text in a cell like [gtk.cell_renderer_text.CellRendererText] from which it is derived. But while [gtk.cell_renderer_text.CellRendererText] offers a simple entry to edit the text, [gtk.cell_renderer_spin.CellRendererSpin] offers a [gtk.spin_button.SpinButton] widget. Of course, that means that the text has to be parseable as a floating point number.

The range of the spinbutton is taken from the adjustment property of the cell renderer, which can be set explicitly or mapped to a column in the tree model, like all properties of cell renders. [gtk.cell_renderer_spin.CellRendererSpin] also has properties for the GtkCellRendererSpin:climb-rate and the number of GtkCellRendererSpin:digits to display. Other [gtk.spin_button.SpinButton] properties can be set in a handler for the GtkCellRenderer::editing-started signal.

Renders a spinning animation in a cell

[gtk.cell_renderer_spinner.CellRendererSpinner] renders a spinning animation in a cell, very similar to [gtk.spinner.Spinner]. It can often be used as an alternative to a [gtk.cell_renderer_progress.CellRendererProgress] for displaying indefinite activity, instead of actual progress.

To start the animation in a cell, set the GtkCellRendererSpinner:active property to true and increment the GtkCellRendererSpinner:pulse property at regular intervals. The usual way to set the cell renderer properties for each cell is to bind them to columns in your tree model using e.g. [gtk.tree_view_column.TreeViewColumn.addAttribute].

Renders text in a cell

A [gtk.cell_renderer_text.CellRendererText] renders a given text in its cell, using the font, color and style information provided by its properties. The text will be ellipsized if it is too long and the GtkCellRendererText:ellipsize property allows it.

If the GtkCellRenderer:mode is [gtk.types.CellRendererMode.Editable], the [gtk.cell_renderer_text.CellRendererText] allows to edit its text using an entry.

Renders a toggle button in a cell

[gtk.cell_renderer_toggle.CellRendererToggle] renders a toggle button in a cell. The button is drawn as a radio or a checkbutton, depending on the GtkCellRendererToggle:radio property. When activated, it emits the GtkCellRendererToggle::toggled signal.

A widget displaying a single row of a GtkTreeModel

A [gtk.cell_view.CellView] displays a single row of a [gtk.tree_model.TreeModel] using a [gtk.cell_area.CellArea] and [gtk.cell_area_context.CellAreaContext]. A [gtk.cell_area_context.CellAreaContext] can be provided to the [gtk.cell_view.CellView] at construction time in order to keep the cellview in context of a group of cell views, this ensures that the renderers displayed will be properly aligned with each other (like the aligned cells in the menus of [gtk.combo_box.ComboBox]).

[gtk.cell_view.CellView] is [gtk.orientable.Orientable] in order to decide in which orientation the underlying [gtk.cell_area_context.CellAreaContext] should be allocated. Taking the [gtk.combo_box.ComboBox] menu as an example, cellviews should be oriented horizontally if the menus are listed top-to-bottom and thus all share the same width but may have separate individual heights (left-to-right menus should be allocated vertically since they all share the same height but may have variable widths).

CSS nodes

GtkCellView has a single CSS node with name cellview.

[gtk.center_box.CenterBox] arranges three children in a row, keeping the middle child centered as well as possible.

!An example GtkCenterBox

To add children to [gtk.center_box.CenterBox], use [gtk.center_box.CenterBox.setStartWidget], [gtk.center_box.CenterBox.setCenterWidget] and [gtk.center_box.CenterBox.setEndWidget].

The sizing and positioning of children can be influenced with the align and expand properties of the children.

GtkCenterBox as GtkBuildable

The [gtk.center_box.CenterBox] implementation of the [gtk.buildable.Buildable] interface supports placing children in the 3 positions by specifying “start”, “center” or “end” as the “type” attribute of a <child> element.

CSS nodes

[gtk.center_box.CenterBox] uses a single CSS node with the name “box”,

The first child of the [gtk.center_box.CenterBox] will be allocated depending on the text direction, i.e. in left-to-right layouts it will be allocated on the left and in right-to-left layouts on the right.

In vertical orientation, the nodes of the children are arranged from top to bottom.

Accessibility

Until GTK 4.10, [gtk.center_box.CenterBox] used the [gtk.types.AccessibleRole.Group] role.

Starting from GTK 4.12, [gtk.center_box.CenterBox] uses the [gtk.types.AccessibleRole.Generic] role.

[gtk.center_layout.CenterLayout] is a layout manager that manages up to three children.

The start widget is allocated at the start of the layout (left in left-to-right locales and right in right-to-left ones), and the end widget at the end.

The center widget is centered regarding the full width of the layout's.

A [gtk.check_button.CheckButton] places a label next to an indicator.

!Example GtkCheckButtons

A [gtk.check_button.CheckButton] is created by calling either [gtk.check_button.CheckButton.new_] or [gtk.check_button.CheckButton.newWithLabel].

The state of a [gtk.check_button.CheckButton] can be set specifically using [gtk.check_button.CheckButton.setActive], and retrieved using [gtk.check_button.CheckButton.getActive].

Inconsistent state

In addition to "on" and "off", check buttons can be an "in between" state that is neither on nor off. This can be used e.g. when the user has selected a range of elements (such as some text or spreadsheet cells) that are affected by a check button, and the current values in that range are inconsistent.

To set a [gtk.check_button.CheckButton] to inconsistent state, use [gtk.check_button.CheckButton.setInconsistent].

Grouping

Check buttons can be grouped together, to form mutually exclusive groups - only one of the buttons can be toggled at a time, and toggling another one will switch the currently toggled one off.

Grouped check buttons use a different indicator, and are commonly referred to as radio buttons.

!Example GtkCheckButtons

To add a [gtk.check_button.CheckButton] to a group, use [gtk.check_button.CheckButton.setGroup].

When the code must keep track of the state of a group of radio buttons, it is recommended to keep track of such state through a stateful [gio.action.Action] with a target for each button. Using the toggled signals to keep track of the group changes and state is discouraged.

CSS nodes

checkbutton[.text-button]
├── check
╰── [label]

A [gtk.check_button.CheckButton] has a main node with name checkbutton. If the [gtk.check_button.CheckButton.label] or [gtk.check_button.CheckButton.child] properties are set, it contains a child widget. The indicator node is named check when no group is set, and radio if the checkbutton is grouped together with other checkbuttons.

Accessibility

[gtk.check_button.CheckButton] uses the [gtk.types.AccessibleRole.Checkbox] role.

An expression using a custom [gobject.closure.Closure] to compute the value from its parameters.

The [gtk.color_button.ColorButton] allows to open a color chooser dialog to change the color.

!An example GtkColorButton

It is suitable widget for selecting a color in a preference dialog.

CSS nodes

colorbutton
╰── button.color
   ╰── [content]

[gtk.color_button.ColorButton] has a single CSS node with name colorbutton which contains a button node. To differentiate it from a plain [gtk.button.Button], it gets the .color style class.

[gtk.color_chooser.ColorChooser] is an interface that is implemented by widgets for choosing colors.

Depending on the situation, colors may be allowed to have alpha (translucency).

In GTK, the main widgets that implement this interface are [gtk.color_chooser_widget.ColorChooserWidget], [gtk.color_chooser_dialog.ColorChooserDialog] and [gtk.color_button.ColorButton].

A dialog for choosing a color.

!An example GtkColorChooserDialog

[gtk.color_chooser_dialog.ColorChooserDialog] implements the [gtk.color_chooser.ColorChooser] interface and does not provide much API of its own.

To create a [gtk.color_chooser_dialog.ColorChooserDialog], use [gtk.color_chooser_dialog.ColorChooserDialog.new_].

To change the initially selected color, use [gtk.color_chooser.ColorChooser.setRgba]. To get the selected color use [gtk.color_chooser.ColorChooser.getRgba].

[gtk.color_chooser_dialog.ColorChooserDialog] has been deprecated in favor of [gtk.color_dialog.ColorDialog].

CSS nodes

[gtk.color_chooser_dialog.ColorChooserDialog] has a single CSS node with the name window and style class .colorchooser.

The [gtk.color_chooser_widget.ColorChooserWidget] widget lets the user select a color.

By default, the chooser presents a predefined palette of colors, plus a small number of settable custom colors. It is also possible to select a different color with the single-color editor.

To enter the single-color editing mode, use the context menu of any color of the palette, or use the '+' button to add a new custom color.

The chooser automatically remembers the last selection, as well as custom colors.

To create a [gtk.color_chooser_widget.ColorChooserWidget], use [gtk.color_chooser_widget.ColorChooserWidget.new_].

To change the initially selected color, use [gtk.color_chooser.ColorChooser.setRgba]. To get the selected color use [gtk.color_chooser.ColorChooser.getRgba].

The [gtk.color_chooser_widget.ColorChooserWidget] is used in the [gtk.color_chooser_dialog.ColorChooserDialog] to provide a dialog for selecting colors.

CSS names

[gtk.color_chooser_widget.ColorChooserWidget] has a single CSS node with name colorchooser.

A [gtk.color_dialog.ColorDialog] object collects the arguments that are needed to present a color chooser dialog to the user, such as a title for the dialog and whether it should be modal.

The dialog is shown with the [gtk.color_dialog.ColorDialog.chooseRgba] function. This API follows the GIO async pattern, and the result can be obtained by calling [gtk.color_dialog.ColorDialog.chooseRgbaFinish].

See [gtk.color_dialog_button.ColorDialogButton] for a convenient control that uses [gtk.color_dialog.ColorDialog] and presents the results.

The [gtk.color_dialog_button.ColorDialogButton] is a wrapped around a [gtk.color_dialog.ColorDialog] and allows to open a color chooser dialog to change the color.

!An example GtkColorDialogButton

It is suitable widget for selecting a color in a preference dialog.

CSS nodes

colorbutton
╰── button.color
   ╰── [content]

[gtk.color_dialog_button.ColorDialogButton] has a single CSS node with name colorbutton which contains a button node. To differentiate it from a plain [gtk.button.Button], it gets the .color style class.

[gtk.column_view.ColumnView] presents a large dynamic list of items using multiple columns with headers.

[gtk.column_view.ColumnView] uses the factories of its columns to generate a cell widget for each column, for each visible item and displays them together as the row for this item.

The property@Gtk.ColumnView:show-row-separators and property@Gtk.ColumnView:show-column-separators properties offer a simple way to display separators between the rows or columns.

[gtk.column_view.ColumnView] allows the user to select items according to the selection characteristics of the model. For models that allow multiple selected items, it is possible to turn on rubberband selection, using property@Gtk.ColumnView:enable-rubberband.

The column view supports sorting that can be customized by the user by clicking on column headers. To set this up, the [gtk.sorter.Sorter] returned by [gtk.column_view.ColumnView.getSorter] must be attached to a sort model for the data that the view is showing, and the columns must have sorters attached to them by calling [gtk.column_view_column.ColumnViewColumn.setSorter]. The initial sort order can be set with [gtk.column_view.ColumnView.sortByColumn].

The column view also supports interactive resizing and reordering of columns, via Drag-and-Drop of the column headers. This can be enabled or disabled with the [gtk.column_view.ColumnView.reorderable] and [gtk.column_view_column.ColumnViewColumn.resizable] properties.

To learn more about the list widget framework, see the

CSS nodes

columnview[.column-separators][.rich-list][.navigation-sidebar][.data-table]
├── header
│   ├── <column header>
┊   ┊
│   ╰── <column header>
│
├── listview
│
┊
╰── [rubberband]

[gtk.column_view.ColumnView] uses a single CSS node named columnview. It may carry the .column-separators style class, when property@Gtk.ColumnView:show-column-separators property is set. Header widgets appear below a node with name header. The rows are contained in a [gtk.list_view.ListView] widget, so there is a listview node with the same structure as for a standalone [gtk.list_view.ListView] widget. If property@Gtk.ColumnView:show-row-separators is set, it will be passed on to the list view, causing its CSS node to carry the .separators style class. For rubberband selection, a node with name rubberband is used.

The main columnview node may also carry style classes to select the style of list presentation: .rich-list, .navigation-sidebar or .data-table.

Accessibility

[gtk.column_view.ColumnView] uses the [gtk.types.AccessibleRole.TreeGrid] role, header title widgets are using the [gtk.types.AccessibleRole.ColumnHeader] role. The row widgets are using the [gtk.types.AccessibleRole.Row] role, and individual cells are using the [gtk.types.AccessibleRole.GridCell] role

[gtk.column_view_cell.ColumnViewCell] is used by [gtk.column_view_column.ColumnViewColumn] to represent items in a cell in [gtk.column_view.ColumnView].

The [gtk.column_view_cell.ColumnViewCell]s are managed by the columnview widget (with its factory) and cannot be created by applications, but they need to be populated by application code. This is done by calling [gtk.column_view_cell.ColumnViewCell.setChild].

[gtk.column_view_cell.ColumnViewCell]s exist in 2 stages:

1. The unbound stage where the listitem is not currently connected to

an item in the list. In that case, the [gtk.column_view_cell.ColumnViewCell.item] property is set to null.

1. The bound stage where the listitem references an item from the list.

The [gtk.column_view_cell.ColumnViewCell.item] property is not null.

[gtk.column_view_column.ColumnViewColumn] represents the columns being added to a [gtk.column_view.ColumnView].

The main ingredient for a [gtk.column_view_column.ColumnViewColumn] is the [gtk.list_item_factory.ListItemFactory] that tells the columnview how to create cells for this column from items in the model.

Columns have a title, and can optionally have a header menu set with [gtk.column_view_column.ColumnViewColumn.setHeaderMenu].

A sorter can be associated with a column using [gtk.column_view_column.ColumnViewColumn.setSorter], to let users influence sorting by clicking on the column header.

[gtk.column_view_row.ColumnViewRow] is used by [gtk.column_view.ColumnView] to allow configuring how rows are displayed.

It is not used to set the widgets displayed in the individual cells. For that see method@GtkColumnViewColumn.set_factory and class@GtkColumnViewCell.

[gtk.column_view_sorter.ColumnViewSorter] is a sorter implementation that is geared towards the needs of [gtk.column_view.ColumnView].

The sorter returned by [gtk.column_view.ColumnView.getSorter] is a [gtk.column_view_sorter.ColumnViewSorter].

In column views, sorting can be configured by associating sorters with columns, and users can invert sort order by clicking on column headers. The API of [gtk.column_view_sorter.ColumnViewSorter] is designed to allow saving and restoring this configuration.

If you are only interested in the primary sort column (i.e. the column where a sort indicator is shown in the header), then you can just look at property@Gtk.ColumnViewSorter:primary-sort-column and property@Gtk.ColumnViewSorter:primary-sort-order.

If you want to store the full sort configuration, including secondary sort columns that are used for tie breaking, then you can use [gtk.column_view_sorter.ColumnViewSorter.getNthSortColumn]. To get notified about changes, use [gtk.sorter.Sorter.changed].

To restore a saved sort configuration on a [gtk.column_view.ColumnView], use code like:

sorter = gtk_column_view_get_sorter (view);
for (i = gtk_column_view_sorter_get_n_sort_columns (sorter) - 1; i >= 0; i--)
 {
   column = gtk_column_view_sorter_get_nth_sort_column (sorter, i, &order);
   gtk_column_view_sort_by_column (view, column, order);
 }

A [gtk.combo_box.ComboBox] is a widget that allows the user to choose from a list of valid choices.

!An example GtkComboBox

The [gtk.combo_box.ComboBox] displays the selected choice; when activated, the [gtk.combo_box.ComboBox] displays a popup which allows the user to make a new choice.

The [gtk.combo_box.ComboBox] uses the model-view pattern; the list of valid choices is specified in the form of a tree model, and the display of the choices can be adapted to the data in the model by using cell renderers, as you would in a tree view. This is possible since [gtk.combo_box.ComboBox] implements the [gtk.cell_layout.CellLayout] interface. The tree model holding the valid choices is not restricted to a flat list, it can be a real tree, and the popup will reflect the tree structure.

To allow the user to enter values not in the model, the property@Gtk.ComboBox:has-entry property allows the [gtk.combo_box.ComboBox] to contain a [gtk.entry.Entry]. This entry can be accessed by calling [gtk.combo_box.ComboBox.getChild] on the combo box.

For a simple list of textual choices, the model-view API of [gtk.combo_box.ComboBox] can be a bit overwhelming. In this case, [gtk.combo_box_text.ComboBoxText] offers a simple alternative. Both [gtk.combo_box.ComboBox] and [gtk.combo_box_text.ComboBoxText] can contain an entry.

CSS nodes

combobox
├── box.linked
│   ╰── button.combo
│       ╰── box
│           ├── cellview
│           ╰── arrow
╰── window.popup

A normal combobox contains a box with the .linked class, a button with the .combo class and inside those buttons, there are a cellview and an arrow.

combobox
├── box.linked
│   ├── entry.combo
│   ╰── button.combo
│       ╰── box
│           ╰── arrow
╰── window.popup

A [gtk.combo_box.ComboBox] with an entry has a single CSS node with name combobox. It contains a box with the .linked class. That box contains an entry and a button, both with the .combo class added. The button also contains another node with name arrow.

Accessibility

[gtk.combo_box.ComboBox] uses the [gtk.types.AccessibleRole.ComboBox] role.

A [gtk.combo_box_text.ComboBoxText] is a simple variant of [gtk.combo_box.ComboBox] for text-only use cases.

!An example GtkComboBoxText

[gtk.combo_box_text.ComboBoxText] hides the model-view complexity of [gtk.combo_box.ComboBox].

To create a [gtk.combo_box_text.ComboBoxText], use [gtk.combo_box_text.ComboBoxText.new_] or [gtk.combo_box_text.ComboBoxText.newWithEntry].

You can add items to a [gtk.combo_box_text.ComboBoxText] with [gtk.combo_box_text.ComboBoxText.appendText], [gtk.combo_box_text.ComboBoxText.insertText] or [gtk.combo_box_text.ComboBoxText.prependText] and remove options with [gtk.combo_box_text.ComboBoxText.remove].

If the [gtk.combo_box_text.ComboBoxText] contains an entry (via the property@Gtk.ComboBox:has-entry property), its contents can be retrieved using [gtk.combo_box_text.ComboBoxText.getActiveText].

You should not call [gtk.combo_box.ComboBox.setModel] or attempt to pack more cells into this combo box via its [gtk.cell_layout.CellLayout] interface.

GtkComboBoxText as GtkBuildable

The [gtk.combo_box_text.ComboBoxText] implementation of the [gtk.buildable.Buildable] interface supports adding items directly using the <items> element and specifying <item> elements for each item. Each <item> element can specify the “id” corresponding to the appended text and also supports the regular translation attributes “translatable”, “context” and “comments”.

Here is a UI definition fragment specifying [gtk.combo_box_text.ComboBoxText] items:

<object class="GtkComboBoxText">
 <items>
   <item translatable="yes" id="factory">Factory</item>
   <item translatable="yes" id="home">Home</item>
   <item translatable="yes" id="subway">Subway</item>
 </items>
</object>

CSS nodes

combobox
╰── box.linked
   ├── entry.combo
   ├── button.combo
   ╰── window.popup

[gtk.combo_box_text.ComboBoxText] has a single CSS node with name combobox. It adds the style class .combo to the main CSS nodes of its entry and button children, and the .linked class to the node of its internal box.

A constant value in a [gtk.expression.Expression].

[gtk.constraint.Constraint] describes a constraint between attributes of two widgets, expressed as a linear equation.

The typical equation for a constraint is:

target.target_attr = source.source_attr × multiplier + constant

Each [gtk.constraint.Constraint] is part of a system that will be solved by a [gtk.constraint_layout.ConstraintLayout] in order to allocate and position each child widget or guide.

The source and target, as well as their attributes, of a [gtk.constraint.Constraint] instance are immutable after creation.

A [gtk.constraint_guide.ConstraintGuide] is an invisible layout element in a [gtk.constraint_layout.ConstraintLayout].

The [gtk.constraint_layout.ConstraintLayout] treats guides like widgets. They can be used as the source or target of a [gtk.constraint.Constraint].

Guides have a minimum, maximum and natural size. Depending on the constraints that are applied, they can act like a guideline that widgets can be aligned to, or like *flexible space*.

Unlike a [gtk.widget.Widget], a [gtk.constraint_guide.ConstraintGuide] will not be drawn.

A layout manager using constraints to describe relations between widgets.

[gtk.constraint_layout.ConstraintLayout] is a layout manager that uses relations between widget attributes, expressed via [gtk.constraint.Constraint] instances, to measure and allocate widgets.

How do constraints work

Constraints are objects defining the relationship between attributes of a widget; you can read the description of the [gtk.constraint.Constraint] class to have a more in depth definition.

By taking multiple constraints and applying them to the children of a widget using [gtk.constraint_layout.ConstraintLayout], it's possible to describe complex layout policies; each constraint applied to a child or to the parent widgets contributes to the full description of the layout, in terms of parameters for resolving the value of each attribute.

It is important to note that a layout is defined by the totality of constraints; removing a child, or a constraint, from an existing layout without changing the remaining constraints may result in an unstable or unsolvable layout.

Constraints have an implicit "reading order"; you should start describing each edge of each child, as well as their relationship with the parent container, from the top left (or top right, in RTL languages), horizontally first, and then vertically.

A constraint-based layout with too few constraints can become "unstable", that is: have more than one solution. The behavior of an unstable layout is undefined.

A constraint-based layout with conflicting constraints may be unsolvable, and lead to an unstable layout. You can use the [gtk.constraint.Constraint.strength] property of [gtk.constraint.Constraint] to "nudge" the layout towards a solution.

GtkConstraintLayout as GtkBuildable

[gtk.constraint_layout.ConstraintLayout] implements the [gtk.buildable.Buildable] interface and has a custom "constraints" element which allows describing constraints in a [gtk.builder.Builder] UI file.

An example of a UI definition fragment specifying a constraint:

<object class="GtkConstraintLayout">
   <constraints>
     <constraint target="button" target-attribute="start"
                 relation="eq"
                 source="super" source-attribute="start"
                 constant="12"
                 strength="required" />
     <constraint target="button" target-attribute="width"
                 relation="ge"
                 constant="250"
                 strength="strong" />
   </constraints>
 </object>

The definition above will add two constraints to the GtkConstraintLayout:

• a required constraint between the leading edge of "button" and

the leading edge of the widget using the constraint layout, plus 12 pixels

• a strong, constant constraint making the width of "button" greater

than, or equal to 250 pixels

The "target" and "target-attribute" attributes are required.

The "source" and "source-attribute" attributes of the "constraint" element are optional; if they are not specified, the constraint is assumed to be a constant.

The "relation" attribute is optional; if not specified, the constraint is assumed to be an equality.

The "strength" attribute is optional; if not specified, the constraint is assumed to be required.

The "source" and "target" attributes can be set to "super" to indicate that the constraint target is the widget using the GtkConstraintLayout.

There can be "constant" and "multiplier" attributes.

Additionally, the "constraints" element can also contain a description of the GtkConstraintGuides used by the layout:

<constraints>
   <guide min-width="100" max-width="500" name="hspace"/>
   <guide min-height="64" nat-height="128" name="vspace" strength="strong"/>
 </constraints>

The "guide" element has the following optional attributes:

• "min-width", "nat-width", and "max-width", describe the minimum,

natural, and maximum width of the guide, respectively

• "min-height", "nat-height", and "max-height", describe the minimum,

natural, and maximum height of the guide, respectively

• "strength" describes the strength of the constraint on the natural

size of the guide; if not specified, the constraint is assumed to have a medium strength

• "name" describes a name for the guide, useful when debugging

Using the Visual Format Language

Complex constraints can be described using a compact syntax called VFL, or Visual Format Language.

The Visual Format Language describes all the constraints on a row or column, typically starting from the leading edge towards the trailing one. Each element of the layout is composed by "views", which identify a [gtk.constraint_target.ConstraintTarget].

For instance:

[button]-[textField]

Describes a constraint that binds the trailing edge of "button" to the leading edge of "textField", leaving a default space between the two.

Using VFL is also possible to specify predicates that describe constraints on attributes like width and height:

// Width must be greater than, or equal to 50
 [button(>=50)]

 // Width of button1 must be equal to width of button2
 [button1(==button2)]

The default orientation for a VFL description is horizontal, unless otherwise specified:

// horizontal orientation, default attribute: width
 H:[button(>=150)]

 // vertical orientation, default attribute: height
 V:[button1(==button2)]

It's also possible to specify multiple predicates, as well as their strength:

// minimum width of button must be 150
 // natural width of button can be 250
 [button(>=150@required, ==250@medium)]

Finally, it's also possible to use simple arithmetic operators:

// width of button1 must be equal to width of button2
 // divided by 2 plus 12
 [button1(button2 / 2 + 12)]

[gtk.layout_child.LayoutChild] subclass for children in a [gtk.constraint_layout.ConstraintLayout].

The [gtk.constraint_target.ConstraintTarget] interface is implemented by objects that can be used as source or target in [gtk.constraint.Constraint]s.

Besides [gtk.widget.Widget], it is also implemented by [gtk.constraint_guide.ConstraintGuide].

[gtk.css_provider.CssProvider] is an object implementing the [gtk.style_provider.StyleProvider] interface for CSS.

It is able to parse CSS-like input in order to style widgets.

An application can make GTK parse a specific CSS style sheet by calling [gtk.css_provider.CssProvider.loadFromFile] or [gtk.css_provider.CssProvider.loadFromResource] and adding the provider with [gtk.style_context.StyleContext.addProvider] or [gtk.style_context.StyleContext.addProviderForDisplay].

In addition, certain files will be read when GTK is initialized. First, the file $XDG_CONFIG_HOME/gtk-4.0/gtk.css is loaded if it exists. Then, GTK loads the first existing file among XDG_DATA_HOME/themes/THEME/gtk-VERSION/gtk-VARIANT.css, $HOME/.themes/THEME/gtk-VERSION/gtk-VARIANT.css, $XDG_DATA_DIRS/themes/THEME/gtk-VERSION/gtk-VARIANT.css and DATADIR/share/themes/THEME/gtk-VERSION/gtk-VARIANT.css, where THEME is the name of the current theme (see the property@Gtk.Settings:gtk-theme-name setting), VARIANT is the variant to load (see the property@Gtk.Settings:gtk-application-prefer-dark-theme setting), DATADIR is the prefix configured when GTK was compiled (unless overridden by the GTK_DATA_PREFIX environment variable), and VERSION is the GTK version number. If no file is found for the current version, GTK tries older versions all the way back to 4.0.

To track errors while loading CSS, connect to the signal@Gtk.CssProvider::parsing-error signal.

Defines a part of a CSS document.

Because sections are nested into one another, you can use [gtk.css_section.CssSection.getParent] to get the containing region.

[gtk.custom_filter.CustomFilter] determines whether to include items with a callback.

[gtk.custom_layout.CustomLayout] uses closures for size negotiation.

A GtkCustomLayout uses closures matching to the old [gtk.widget.Widget] virtual functions for size negotiation, as a convenience API to ease the porting towards the corresponding `GtkLayoutManager virtual functions.

[gtk.custom_sorter.CustomSorter] is a [gtk.sorter.Sorter] implementation that sorts via a callback function.

Dialogs are a convenient way to prompt the user for a small amount of input.

!An example GtkDialog

Typical uses are to display a message, ask a question, or anything else that does not require extensive effort on the user’s part.

The main area of a [gtk.dialog.Dialog] is called the "content area", and is yours to populate with widgets such a [gtk.label.Label] or [gtk.entry.Entry], to present your information, questions, or tasks to the user.

In addition, dialogs allow you to add "action widgets". Most commonly, action widgets are buttons. Depending on the platform, action widgets may be presented in the header bar at the top of the window, or at the bottom of the window. To add action widgets, create your [gtk.dialog.Dialog] using [gtk.dialog.Dialog.newWithButtons], or use [gtk.dialog.Dialog.addButton], [gtk.dialog.Dialog.addButtons], or [gtk.dialog.Dialog.addActionWidget].

GtkDialogs uses some heuristics to decide whether to add a close button to the window decorations. If any of the action buttons use the response ID [gtk.types.ResponseType.Close] or [gtk.types.ResponseType.Cancel], the close button is omitted.

Clicking a button that was added as an action widget will emit the [gtk.dialog.Dialog.response] signal with a response ID that you specified. GTK will never assign a meaning to positive response IDs; these are entirely user-defined. But for convenience, you can use the response IDs in the [gtk.types.ResponseType] enumeration (these all have values less than zero). If a dialog receives a delete event, the [gtk.dialog.Dialog.response] signal will be emitted with the [gtk.types.ResponseType.DeleteEvent] response ID.

Dialogs are created with a call to [gtk.dialog.Dialog.new_] or [gtk.dialog.Dialog.newWithButtons]. The latter is recommended; it allows you to set the dialog title, some convenient flags, and add buttons.

A “modal” dialog (that is, one which freezes the rest of the application from user input), can be created by calling [gtk.window.Window.setModal] on the dialog. When using [gtk.dialog.Dialog.newWithButtons], you can also pass the [gtk.types.DialogFlags.Modal] flag to make a dialog modal.

For the simple dialog in the following example, a [gtk.message_dialog.MessageDialog] would save some effort. But you’d need to create the dialog contents manually if you had more than a simple message in the dialog.

An example for simple [gtk.dialog.Dialog] usage:

// Function to open a dialog box with a message
void
quick_message (GtkWindow *parent, char *message)
{
GtkWidget *dialog, *label, *content_area;
GtkDialogFlags flags;

// Create the widgets
flags = GTK_DIALOG_DESTROY_WITH_PARENT;
dialog = gtk_dialog_new_with_buttons ("Message",
                                      parent,
                                      flags,
                                      _("_OK"),
                                      GTK_RESPONSE_NONE,
                                      NULL);
content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog));
label = gtk_label_new (message);

// Ensure that the dialog box is destroyed when the user responds

g_signal_connect_swapped (dialog,
                          "response",
                          G_CALLBACK (gtk_window_destroy),
                          dialog);

// Add the label, and show everything we’ve added

gtk_box_append (GTK_BOX (content_area), label);
gtk_widget_show (dialog);
}

GtkDialog as GtkBuildable

The [gtk.dialog.Dialog] implementation of the [gtk.buildable.Buildable] interface exposes the @content_area as an internal child with the name “content_area”.

[gtk.dialog.Dialog] supports a custom <action-widgets> element, which can contain multiple <action-widget> elements. The “response” attribute specifies a numeric response, and the content of the element is the id of widget (which should be a child of the dialogs @action_area). To mark a response as default, set the “default” attribute of the <action-widget> element to true.

[gtk.dialog.Dialog] supports adding action widgets by specifying “action” as the “type” attribute of a <child> element. The widget will be added either to the action area or the headerbar of the dialog, depending on the “use-header-bar” property. The response id has to be associated with the action widget using the <action-widgets> element.

An example of a [gtk.dialog.Dialog] UI definition fragment:

<object class="GtkDialog" id="dialog1">
 <child type="action">
   <object class="GtkButton" id="button_cancel"/>
 </child>
 <child type="action">
   <object class="GtkButton" id="button_ok">
   </object>
 </child>
 <action-widgets>
   <action-widget response="cancel">button_cancel</action-widget>
   <action-widget response="ok" default="true">button_ok</action-widget>
 </action-widgets>
</object>

Accessibility

[gtk.dialog.Dialog] uses the [gtk.types.AccessibleRole.Dialog] role.