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 gtk.accessible.Accessible.

The possible accessible relations of a gtk.accessible.Accessible.

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

The accessible role for a gtk.accessible.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 gtk.accessible.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 gtk.box.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 gtk.cell_renderer_accel.CellRendererAccel.accelMode.

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 gtk.constraint.Constraint.

The relation between two terms of a constraint.

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

The strength of a gtk.constraint.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.CssParserErrors, 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 gtk.gesture.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 gtk.types.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 gtk.label.Label widget.

Describes how gtk.level_bar.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 gtk.message_dialog.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 gtk.label.Label.naturalWrapMode 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 gtk.box.Box or gtk.gesture_pan.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 gtk.window_controls.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 gtk.gesture_pan.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 gtk.notebook.Notebook, or the label of a gtk.scale.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 gtk.event_controller.EventController for handling events targeting other widgets.

Describes the stage at which events are fed into a gtk.event_controller.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 gtk.shortcut.Shortcuts added to a gtk.shortcut_controller.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 gtk.settings.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 gtk.about_dialog.AboutDialog.activateLink 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:

GFile *logo_file = g_file_new_for_path ("./logo.png");
GdkTexture *example_logo = gdk_texture_new_from_file (logo_file, NULL);
g_object_unref (logo_file);

gtk_show_about_dialog (NULL,
                       "program-name", "ExampleCode",
                       "logo", example_logo,
                       "title", _("About ExampleCode"),
                       NULL);

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: gtk.actionable.Actionable.actionName and gtk.actionable.Actionable.actionTarget. 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 gtk.app_chooser_button.AppChooserButton.showDefaultItem 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 gtk.app_chooser_button.AppChooserButton.showDefaultItem is set, the default application is also included. To let the user chooser other applications, you can set the gtk.app_chooser_button.AppChooserButton.showDialogItem 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 gtk.app_chooser_button.AppChooserButton.customItemActivated 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 gtk.app_chooser_widget.AppChooserWidget.showDefault, gtk.app_chooser_widget.AppChooserWidget.showRecommended, gtk.app_chooser_widget.AppChooserWidget.showFallback, gtk.app_chooser_widget.AppChooserWidget.showOther and gtk.app_chooser_widget.AppChooserWidget.showAll 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 gtk.app_chooser_widget.AppChooserWidget.applicationSelected and gtk.app_chooser_widget.AppChooserWidget.applicationActivated 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.Windows, 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 <kbd>Control</kbd>+<kbd>?</kbd> to open it. To create a menu item that displays the shortcuts window, associate the item with the action win.show-help-overlay.

A simple application

A simple example 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 gtk.application.Application.registerSession 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

HowDoI: Using GtkApplication, Getting Started with GTK: Basics

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 gtk.settings.Settings.gtkShellShowsAppMenu and gtk.settings.Settings.gtkShellShowsMenubar 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 gtk.application_window.ApplicationWindow.showMenubar 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.Assistants 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.FileInfos returned from that function.

The gio.file_info.FileInfos 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 between the children.

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.Expressions 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.CellRenderers

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.CellRenderers 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 GtkWidget’s geometry management section, 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 gtk.cell_area.CellArea.focusChanged signal to fire; as well as gtk.cell_area.CellArea.addEditable 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.CellRenderers. 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.CellRenderers 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.CellLayouts in GTK use a gtk.cell_area.CellArea) cell properties can also be defined 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.ObjectWraps 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.CellRendererToggle, which toggles when it gets activated by a mouse click, or it can be “editable” like gtk.cell_renderer.CellRendererText, 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.CellRendererClass.activate or gtk.cell_renderer.CellRendererClass.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 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 gtk.column_view.ColumnView.showRowSeparators and gtk.column_view.ColumnView.showColumnSeparators properties offer a simple way to display separators between the rows or columns.