A #GtkAllocation-struct of a widget represents region which has been allocated to the widget by its parent. It is a subregion of its parents allocation. See [GtkWidget’s geometry management section][geometry-management] for more information.

Accelerator flags used with [gtk.accel_group.AccelGroup.connect].

Controls how a widget deals with extra space in a single (x or y) dimension.

Alignment only matters if the widget receives a “too large” allocation, for example if you packed the widget with the #GtkWidget:expand flag inside a #GtkBox, 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_ALIGN_START and @GTK_ALIGN_END are interpreted relative to text direction.

GTK_ALIGN_BASELINE support for it is optional for containers and widgets, and it is only supported for vertical alignment. When its not supported by a child or a container it is treated as @GTK_ALIGN_FILL.

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

Used to specify the placement of scroll arrows in scrolling menus.

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

An enum for determining the page role inside the #GtkAssistant. It's 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.

Denotes the expansion properties that a widget will have when it (or its parent) is resized.

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 verical space in the row is taller than the total requested height of the baseline-aligned children then it can use a #GtkBaselinePosition to select where to put the baseline inside the extra availible space.

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

Error codes that identify various errors that can occur while using #GtkBuilder.

Used to dictate the style that a #GtkButtonBox uses to layout the buttons it contains.

The role specifies the desired appearance of a #GtkModelButton.

Prebuilt sets of buttons for the dialog. If none of these choices are appropriate, simply use [gtk.types.ButtonsType.None] then 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.

These options can be used to influence the display and behaviour of a #GtkCalendar.

Determines if the edited accelerators are GTK+ accelerators. If they are, consumed modifiers are suppressed, only accelerators accepted by GTK+ are allowed, and the accelerators are rendered in the same way as they are in menus.

Identifies how the user can interact with a particular cell.

Tells how a cell is to be rendered.

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.

Error codes for GTK_CSS_PROVIDER_ERROR.

The different types of sections indicate parts of a CSS document as parsed by GTK’s CSS parser. They are oriented towards the

but may contain extensions.

More types might be added in the future as the parser incorporates more features.

See also: #GtkEntry::delete-from-cursor.

The #GtkDestDefaults enumeration specifies the various types of action that will be taken on behalf of the user for a drag destination site.

Flags used to influence dialog construction.

Focus movement types.

Gives an indication why a drag operation failed. The value can by obtained by connecting to the #GtkWidget::drag-failed signal.

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

Describes the behavior of a #GtkEventControllerScroll.

Describes the state of a #GdkEventSequence in a #GtkGesture.

Used to specify the style of the expanders drawn by a #GtkTreeView.

Describes whether a #GtkFileChooser is being used to open existing files or to save to a possibly new file.

Used as a return value of handlers for the #GtkFileChooser::confirm-overwrite signal of a #GtkFileChooser. This value determines whether the file chooser will present the stock confirmation dialog, accept the user’s choice of a filename, or let the user choose another filename.

These identify the various errors that can occur while calling #GtkFileChooser functions.

These flags indicate what parts of a #GtkFileFilterInfo struct are filled or need to be filled.

This enumeration specifies the granularity of font selection that is desired in a font chooser.

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

Style for input method preedit. See also #GtkSettings:gtk-im-preedit-style

Style for input method status. See also #GtkSettings:gtk-im-status-style

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

Built-in stock icon sizes.

Error codes for GtkIconTheme operations.

An enum for determining where a dropped item goes.

Describes the image data representation used by a #GtkImage. If you want to get the image from the widget, you can only get the currently-stored representation. e.g. if the [gtk.image.Image.getStorageType] returns #GTK_IMAGE_PIXBUF, then you can call [gtk.image.Image.getPixbuf] but not [gtk.image.Image.getStock]. 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 #GtkInputPurpose of the entry.

Some common sense is expected when using these flags - mixing @GTK_INPUT_HINT_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_INPUT_PURPOSE_DIGITS and @GTK_INPUT_PURPOSE_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”.

Describes how a rendered element connects to adjacent elements.

Used for justifying the text inside a #GtkLabel widget. (See also #GtkAlignment).

Describes how #GtkLevelBar 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.

An enumeration representing directional movements within a menu.

The type of message being displayed in the dialog.

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

Represents the orientation of widgets and other objects which can be switched between horizontal and vertical orientation on the fly, like #GtkToolbar or #GtkGesturePan.

Determines how widgets should be packed inside menubars and menuitems contained in menubars.

Represents the packing location #GtkBox children. (See: #GtkVBox, #GtkHBox, and #GtkButtonBox).

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 #GtkGesturePan

Priorities for path lookups. See also [gtk.binding_set.BindingSet.addPath].

Widget path types. See also [gtk.binding_set.BindingSet.addPath].

These flags serve two purposes. First, the application can call [gtk.places_sidebar.PlacesSidebar.setOpenFlags] using these flags as a bitmask. This tells the sidebar that the application is able to open folders selected from the sidebar in various ways, for example, in new tabs or in new windows in addition to the normal mode.

Second, when one of these values gets passed back to the application in the #GtkPlacesSidebar::open-location signal, it means that the application should open the selected location in the normal way, in a new tab, or in a new window. The sidebar takes care of determining the desired way to open the location, based on the modifier keys that the user is pressing at the time the selection is made.

If the application never calls [gtk.places_sidebar.PlacesSidebar.setOpenFlags], then the sidebar will only use #GTK_PLACES_OPEN_NORMAL in the #GtkPlacesSidebar::open-location signal. This is the default mode of operation.

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

Describes constraints to positioning of popovers. More values may be added to this enumeration in the future.

Describes which edge of a widget a certain feature is positioned at, e.g. the tabs of a #GtkNotebook, the handle of a #GtkHandleBox or the label of a #GtkScale.

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

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

The @action parameter to [gtk.print_operation.PrintOperation.run] determines what action the print operation should perform.

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 the stage at which events are fed into a #GtkEventController.

Deprecated

The #GtkRcTokenType enumeration represents the tokens in the RC file. It is exposed so that theme engines can reuse these tokens when parsing the theme-engine specific portions of a RC file.

These identify the various errors that can occur while calling #GtkRecentChooser functions.

These flags indicate what parts of a #GtkRecentFilterInfo struct are filled or need to be filled.

Error codes for #GtkRecentManager operations

Used to specify the sorting method to be applyed to the recently used resource list.

Describes a region within a widget.

Indicated the relief to be drawn around a #GtkButton.

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 #GtkRevealer widget is shown or hidden.

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 stepper arrows at the end of range widgets.

Used to change the appearance of an outline typically provided by a #GtkFrame.

Note that many themes do not differentiate the appearance of the various shadow types: Either their is no visible shadow (@GTK_SHADOW_NONE), or there is (any other value).

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.

The spin button update policy determines whether the spin button displays values even if they are outside the bounds of its adjustment. 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].

These enumeration values describe the possible transitions between pages in a #GtkStack 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.

This type indicates the current state of a widget; the state determines how the widget is drawn. The #GtkStateType enumeration is also used to identify different colors in a #GtkStyle for drawing, so states can be used for subparts of a widget as well as entire widgets.

Flags that modify the behavior of [gtk.style_context.StyleContext.toString_]. New values may be added to this enumeration.

The #GtkTargetFlags enumeration is used to specify constraints on a #GtkTargetEntry.

These values are used as “info” for the targets contained in the lists returned by [gtk.text_buffer.TextBuffer.getCopyTargetList] and [gtk.text_buffer.TextBuffer.getPasteTargetList].

The values counts down from -1 to avoid clashes with application added drag destinations which usually start at 0.

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_TEXT_SEARCH_VISIBLE_ONLY nor #GTK_TEXT_SEARCH_TEXT_ONLY are enabled, the match must be exact; the special 0xFFFC character will match embedded pixbufs or child widgets.

Used to reference the layers of #GtkTextView for the purpose of customized drawing with the ::draw_layer vfunc.

Used to reference the parts of #GtkTextView.

Flags used to specify the supported drag targets.

Whether spacers are vertical lines or just blank.

Used to customize the appearance of a #GtkToolbar. Note that setting the toolbar style overrides the user’s preferences for the default toolbar style. Note that if the button has only a label set and GTK_TOOLBAR_ICONS is used, the label will be visible, and vice versa.

These flags indicate various properties of a #GtkTreeModel.

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_TREE_MODEL_ITERS_PERSIST can be found in the overview of this section.

The sizing method the column uses to determine its width. Please note that @GTK_TREE_VIEW_COLUMN_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.

These enumeration values are used by [gtk.uimanager.UIManager.addUi] to determine what UI element to create.

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

Kinds of widget-specific help. Used by the ::show-help signal.

Window placement can be influenced using this enumeration. Note that using #GTK_WIN_POS_CENTER_ALWAYS is almost always a bad idea. It won’t necessarily work well with all window managers or on all windowing systems.

A #GtkWindow can be one of these types. Most things you’d consider a “window” should have type #GTK_WINDOW_TOPLEVEL; windows with this type are managed by the window manager and have a frame by default (call [gtk.window.Window.setDecorated] to toggle the frame). Windows with type #GTK_WINDOW_POPUP are ignored by the window manager; window manager keybindings won’t work on them, the window manager won’t decorate the window with a frame, many GTK+ features that rely on the window manager will not work (e.g. resize grips and maximization/minimization). #GTK_WINDOW_POPUP is used to implement widgets such as #GtkMenu or tooltips that you normally don’t think of as windows per se. Nearly all windows should be #GTK_WINDOW_TOPLEVEL. In particular, do not use #GTK_WINDOW_POPUP just to turn off the window borders; use [gtk.window.Window.setDecorated] for that.

Describes a type of line wrapping.

The GtkAboutDialog offers a simple way to display information about a program like its 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.

About dialogs often contain links and email addresses. GtkAboutDialog displays these as clickable links. By default, it calls [gtk.global.showUriOnWindow] when a user clicks one. The behaviour can be overridden with the #GtkAboutDialog::activate-link signal.

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

To make constructing a GtkAboutDialog as convenient as possible, you can use the function [gtk.global.showAboutDialog] 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 GtkAboutDialog, as shown in the following example:

GdkPixbuf *example_logo = gdk_pixbuf_new_from_file ("./logo.png", NULL);
gtk_show_about_dialog (NULL,
                      "program-name", "ExampleCode",
                      "logo", example_logo,
                      "title", _("About ExampleCode"),
                      NULL);

It is also possible to show a #GtkAboutDialog like any other #GtkDialog, e.g. using [gtk.dialog.Dialog.run]. In this case, you might need to know that the “Close” button returns the #GTK_RESPONSE_CANCEL response id.

A #GtkAccelGroup represents a group of keyboard accelerators, typically attached to a toplevel #GtkWindow (with [gtk.window.Window.addAccelGroup]). Usually you won’t need to create a #GtkAccelGroup directly; instead, when using #GtkUIManager, GTK+ automatically sets up the accelerators for your menus in the ui manager’s #GtkAccelGroup.

Note that “accelerators” are different from “mnemonics”. Accelerators are shortcuts for activating a menu item; they appear alongside the menu item they’re a shortcut for. For example “Ctrl+Q” might appear alongside the “Quit” menu item. Mnemonics are shortcuts for GUI elements such as text entries or buttons; they appear as underlined characters. See [gtk.label.Label.newWithMnemonic]. Menu items can have both accelerators and mnemonics, of course.

The #GtkAccelLabel widget is a subclass of #GtkLabel that also displays an accelerator key on the right of the label text, e.g. “Ctrl+S”. It is commonly used in menus to show the keyboard short-cuts for commands.

The accelerator key to display is typically not set explicitly (although it can be, with [gtk.accel_label.AccelLabel.setAccel]). Instead, the #GtkAccelLabel displays the accelerators which have been added to a particular widget. This widget is set by calling [gtk.accel_label.AccelLabel.setAccelWidget].

For example, a #GtkMenuItem widget may have an accelerator added to emit the “activate” signal when the “Ctrl+S” key combination is pressed. A #GtkAccelLabel is created and added to the #GtkMenuItem, and [gtk.accel_label.AccelLabel.setAccelWidget] is called with the #GtkMenuItem as the second argument. The #GtkAccelLabel will now display “Ctrl+S” after its label.

Note that creating a #GtkMenuItem with [gtk.menu_item.MenuItem.newWithLabel] (or one of the similar functions for #GtkCheckMenuItem and #GtkRadioMenuItem) automatically adds a #GtkAccelLabel to the #GtkMenuItem and calls [gtk.accel_label.AccelLabel.setAccelWidget] to set it up for you.

A #GtkAccelLabel will only display accelerators which have [gtk.types.AccelFlags.Visible] set (see #GtkAccelFlags). A #GtkAccelLabel can display multiple accelerators and even signal names, though it is almost always used to display just one accelerator key.

Creating a simple menu item with an accelerator key.

GtkWidget *window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
 GtkWidget *menu = gtk_menu_new ();
 GtkWidget *save_item;
 GtkAccelGroup *accel_group;

 // Create a GtkAccelGroup and add it to the window.
 accel_group = gtk_accel_group_new ();
 gtk_window_add_accel_group (GTK_WINDOW (window), accel_group);

 // Create the menu item using the convenience function.
 save_item = gtk_menu_item_new_with_label ("Save");
 gtk_widget_show (save_item);
 gtk_container_add (GTK_CONTAINER (menu), save_item);

 // Now add the accelerator to the GtkMenuItem. Note that since we
 // called gtk_menu_item_new_with_label() to create the GtkMenuItem
 // the GtkAccelLabel is automatically set up to display the
 // GtkMenuItem accelerators. We just need to make sure we use
 // GTK_ACCEL_VISIBLE here.
 gtk_widget_add_accelerator (save_item, "activate", accel_group,
                             GDK_KEY_s, GDK_CONTROL_MASK, GTK_ACCEL_VISIBLE);

CSS nodes

label
╰── accelerator

Like #GtkLabel, GtkAccelLabel has a main CSS node with the name label. It adds a subnode with name accelerator.

Accelerator maps are used to define runtime configurable accelerators. Functions for manipulating them are are usually used by higher level convenience mechanisms like #GtkUIManager and are thus considered “low-level”. You’ll want to use them if you’re manually creating menus that should have user-configurable accelerators.

An accelerator is uniquely defined by:

• accelerator path
• accelerator key
• accelerator modifiers

The accelerator path must consist of “<WINDOWTYPE>/Category1/Category2/.../Action”, where WINDOWTYPE should be a unique application-specific identifier that corresponds to the kind of window the accelerator is being used in, e.g. “Gimp-Image”, “Abiword-Document” or “Gnumeric-Settings”. The “Category1/.../Action” portion is most appropriately chosen by the action the accelerator triggers, i.e. for accelerators on menu items, choose the item’s menu path, e.g. “File/Save As”, “Image/View/Zoom” or “Edit/Select All”. So a full valid accelerator path may look like: “<Gimp-Toolbox>/File/Dialogs/Tool Options...”.

All accelerators are stored inside one global #GtkAccelMap that can be obtained using [gtk.accel_map.AccelMap.get]. See [Monitoring changes][monitoring-changes] for additional details.

Manipulating accelerators

New accelerators can be added using [gtk.accel_map.AccelMap.addEntry]. To search for specific accelerator, use [gtk.accel_map.AccelMap.lookupEntry]. Modifications of existing accelerators should be done using [gtk.accel_map.AccelMap.changeEntry].

In order to avoid having some accelerators changed, they can be locked using [gtk.accel_map.AccelMap.lockPath]. Unlocking is done using [gtk.accel_map.AccelMap.unlockPath].

Saving and loading accelerator maps

Accelerator maps can be saved to and loaded from some external resource. For simple saving and loading from file, [gtk.accel_map.AccelMap.save] and [gtk.accel_map.AccelMap.load] are provided. Saving and loading can also be done by providing file descriptor to [gtk.accel_map.AccelMap.saveFd] and [gtk.accel_map.AccelMap.loadFd].

Monitoring changes

#GtkAccelMap object is only useful for monitoring changes of accelerators. By connecting to #GtkAccelMap::changed signal, one can monitor changes of all accelerators. It is also possible to monitor only single accelerator path by using it as a detail of the #GtkAccelMap::changed signal.

The #GtkAccessible class is the base class for accessible implementations for #GtkWidget subclasses. It is a thin wrapper around #AtkObject, which adds facilities for associating a widget with its accessible object.

An accessible implementation for a third-party widget should derive from #GtkAccessible and implement the suitable interfaces from ATK, such as #AtkText or #AtkSelection. To establish the connection between the widget class and its corresponding acccessible implementation, override the get_accessible vfunc in #GtkWidgetClass.

In GTK+ 3.10, GtkAction has been deprecated. Use #GAction

instead, and associate actions with #GtkActionable widgets. Use #GMenuModel for creating menus with [gtk.menu.Menu.newFromModel].

Actions represent operations that the user can be perform, along with some information how it should be presented in the interface. Each action provides methods to create icons, menu items and toolbar items representing itself.

As well as the callback that is called when the action gets activated, the following also gets associated with the action:

• a name (not translated, for path lookup)

• a label (translated, for display)

• an accelerator

• whether label indicates a stock id

• a tooltip (optional, translated)

• a toolbar label (optional, shorter than label)

The action will also have some state information:

• visible (shown/hidden)

• sensitive (enabled/disabled)

Apart from regular actions, there are [toggle actions][GtkToggleAction], which can be toggled between two states and [radio actions][GtkRadioAction], of which only one in a group can be in the “active” state. Other actions can be implemented as #GtkAction subclasses.

Each action can have one or more proxy widgets. To act as an action proxy, widget needs to implement #GtkActivatable interface. Proxies mirror the state of the action and should change when the action’s state changes. Properties that are always mirrored by proxies are #GtkAction:sensitive and #GtkAction:visible. #GtkAction:gicon, #GtkAction:icon-name, #GtkAction:label, #GtkAction:short-label and #GtkAction:stock-id properties are only mirorred if proxy widget has #GtkActivatable:use-action-appearance property set to true.

When the proxy is activated, it should activate its action.

GtkActionBar is designed to present contextual actions. 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.

CSS nodes

GtkActionBar has a single CSS node with name actionbar.

#GtkActionEntry structs are used with [gtk.action_group.ActionGroup.addActions] to construct actions.

Actions are organised into groups. An action group is essentially a map from names to #GtkAction objects.

All actions that would make sense to use in a particular context should be in a single group. Multiple action groups may be used for a particular user interface. In fact, it is expected that most nontrivial applications will make use of multiple groups. For example, in an application that can edit multiple documents, one group holding global actions (e.g. quit, about, new), and one group per document holding actions that act on that document (eg. save, cut/copy/paste, etc). Each window’s menus would be constructed from a combination of two action groups.

Accelerators ## {#Action-Accel}

Accelerators are handled by the GTK+ accelerator map. All actions are assigned an accelerator path (which normally has the form <Actions>/group-name/action-name) and a shortcut is associated with this accelerator path. All menuitems and toolitems take on this accelerator path. The GTK+ accelerator map code makes sure that the correct shortcut is displayed next to the menu item.

GtkActionGroup as GtkBuildable # {#GtkActionGroup-BUILDER-UI}

The #GtkActionGroup implementation of the #GtkBuildable interface accepts #GtkAction objects as <child> elements in UI definitions.

Note that it is probably more common to define actions and action groups in the code, since they are directly related to what the code can do.

The GtkActionGroup implementation of the GtkBuildable interface supports a custom <accelerator> element, which has attributes named “key“ and “modifiers“ and allows to specify accelerators. This is similar to the <accelerator> element of #GtkWidget, the main difference is that it doesn’t allow you to specify a signal.

A #GtkDialog UI definition fragment.

<object class="GtkActionGroup" id="actiongroup">
 <child>
     <object class="GtkAction" id="About">
         <property name="name">About</property>
         <property name="stock_id">gtk-about</property>
         <signal handler="about_activate" name="activate"/>
     </object>
     <accelerator key="F1" modifiers="GDK_CONTROL_MASK | GDK_SHIFT_MASK"/>
 </child>
</object>

This interface provides a convenient way of associating widgets with actions on a #GtkApplicationWindow or #GtkApplication.

It primarily consists of two properties: #GtkActionable:action-name and #GtkActionable:action-target. There are also some convenience APIs for setting these properties.

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

The interface vtable for #GtkActionable.

Activatable widgets can be connected to a #GtkAction and reflects the state of its action. A #GtkActivatable can also provide feedback through its action, as they are responsible for activating their related actions.

Implementing GtkActivatable

When extending a class that is already #GtkActivatable; it is only necessary to implement the #GtkActivatable->sync_action_properties() and #GtkActivatable->update() methods and chain up to the parent implementation, however when introducing a new #GtkActivatable class; the #GtkActivatable:related-action and #GtkActivatable:use-action-appearance properties need to be handled by the implementor. Handling these properties is mostly a matter of installing the action pointer and boolean flag on your instance, and calling [gtk.activatable.Activatable.doSetRelatedAction] and [gtk.activatable.Activatable.syncActionProperties] at the appropriate times.

A class fragment implementing #GtkActivatable

enum {
...

PROP_ACTIVATABLE_RELATED_ACTION,
PROP_ACTIVATABLE_USE_ACTION_APPEARANCE
}

struct _FooBarPrivate
{

 ...

 GtkAction      *action;
 gboolean        use_action_appearance;
};

...

static void foo_bar_activatable_interface_init         (GtkActivatableIface  *iface);
static void foo_bar_activatable_update                 (GtkActivatable       *activatable,
						           GtkAction            *action,
						           const gchar          *property_name);
static void foo_bar_activatable_sync_action_properties (GtkActivatable       *activatable,
						           GtkAction            *action);
...

static void
foo_bar_class_init (FooBarClass *klass)
{

 ...

 g_object_class_override_property (gobject_class, PROP_ACTIVATABLE_RELATED_ACTION, "related-action");
 g_object_class_override_property (gobject_class, PROP_ACTIVATABLE_USE_ACTION_APPEARANCE, "use-action-appearance");

 ...
}

static void
foo_bar_activatable_interface_init (GtkActivatableIface  *iface)
{
 iface->update = foo_bar_activatable_update;
 iface->sync_action_properties = foo_bar_activatable_sync_action_properties;
}

... Break the reference using gtk_activatable_do_set_related_action()...

static void
foo_bar_dispose (GObject *object)
{
 FooBar *bar = FOO_BAR (object);
 FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);

 ...

 if (priv->action)
   {
     gtk_activatable_do_set_related_action (GTK_ACTIVATABLE (bar), NULL);
     priv->action = NULL;
   }
 G_OBJECT_CLASS (foo_bar_parent_class)->dispose (object);
}

... Handle the “related-action” and “use-action-appearance” properties ...

static void
foo_bar_set_property (GObject         *object,
                     guint            prop_id,
                     const GValue    *value,
                     GParamSpec      *pspec)
{
 FooBar *bar = FOO_BAR (object);
 FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);

 switch (prop_id)
   {

     ...

   case PROP_ACTIVATABLE_RELATED_ACTION:
     foo_bar_set_related_action (bar, g_value_get_object (value));
     break;
   case PROP_ACTIVATABLE_USE_ACTION_APPEARANCE:
     foo_bar_set_use_action_appearance (bar, g_value_get_boolean (value));
     break;
   default:
     G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
     break;
   }
}

static void
foo_bar_get_property (GObject         *object,
                        guint            prop_id,
                        GValue          *value,
                        GParamSpec      *pspec)
{
 FooBar *bar = FOO_BAR (object);
 FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);

 switch (prop_id)
   {

     ...

   case PROP_ACTIVATABLE_RELATED_ACTION:
     g_value_set_object (value, priv->action);
     break;
   case PROP_ACTIVATABLE_USE_ACTION_APPEARANCE:
     g_value_set_boolean (value, priv->use_action_appearance);
     break;
   default:
     G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
     break;
   }
}

static void
foo_bar_set_use_action_appearance (FooBar   *bar,
				   gboolean  use_appearance)
{
 FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);

 if (priv->use_action_appearance != use_appearance)
   {
     priv->use_action_appearance = use_appearance;

     gtk_activatable_sync_action_properties (GTK_ACTIVATABLE (bar), priv->action);
   }
}

... call gtk_activatable_do_set_related_action() and then assign the action pointer,
no need to reference the action here since gtk_activatable_do_set_related_action() already
holds a reference here for you...
static void
foo_bar_set_related_action (FooBar    *bar,
			    GtkAction *action)
{
 FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (bar);

 if (priv->action == action)
   return;

 gtk_activatable_do_set_related_action (GTK_ACTIVATABLE (bar), action);

 priv->action = action;
}

... Selectively reset and update activatable depending on the use-action-appearance property ...
static void
gtk_button_activatable_sync_action_properties (GtkActivatable       *activatable,
		                                  GtkAction            *action)
{
 GtkButtonPrivate *priv = GTK_BUTTON_GET_PRIVATE (activatable);

 if (!action)
   return;

 if (gtk_action_is_visible (action))
   gtk_widget_show (GTK_WIDGET (activatable));
 else
   gtk_widget_hide (GTK_WIDGET (activatable));

 gtk_widget_set_sensitive (GTK_WIDGET (activatable), gtk_action_is_sensitive (action));

 ...

 if (priv->use_action_appearance)
   {
     if (gtk_action_get_stock_id (action))
	foo_bar_set_stock (button, gtk_action_get_stock_id (action));
     else if (gtk_action_get_label (action))
	foo_bar_set_label (button, gtk_action_get_label (action));

     ...

   }
}

static void
foo_bar_activatable_update (GtkActivatable       *activatable,
			       GtkAction            *action,
			       const gchar          *property_name)
{
 FooBarPrivate *priv = FOO_BAR_GET_PRIVATE (activatable);

 if (strcmp (property_name, "visible") == 0)
   {
     if (gtk_action_is_visible (action))
	gtk_widget_show (GTK_WIDGET (activatable));
     else
	gtk_widget_hide (GTK_WIDGET (activatable));
   }
 else if (strcmp (property_name, "sensitive") == 0)
   gtk_widget_set_sensitive (GTK_WIDGET (activatable), gtk_action_is_sensitive (action));

 ...

 if (!priv->use_action_appearance)
   return;

 if (strcmp (property_name, "stock-id") == 0)
   foo_bar_set_stock (button, gtk_action_get_stock_id (action));
 else if (strcmp (property_name, "label") == 0)
   foo_bar_set_label (button, gtk_action_get_label (action));

 ...
}

This method can be called with a null action at times.

The #GtkAdjustment object represents a value which has an associated lower and upper bound, together with step and page increments, and a page size. It is used within several GTK+ widgets, including #GtkSpinButton, #GtkViewport, and #GtkRange (which is a base class for #GtkScrollbar and #GtkScale).

The #GtkAdjustment object does not update the value itself. Instead it is left up to the owner of the #GtkAdjustment to control the value.

The #GtkAlignment widget controls the alignment and size of its child widget. It has four settings: xscale, yscale, xalign, and yalign.

The scale settings are used to specify how much the child widget should expand to fill the space allocated to the #GtkAlignment. The values can range from 0 (meaning the child doesn’t expand at all) to 1 (meaning the child expands to fill all of the available space).

The align settings are used to place the child widget within the available area. The values range from 0 (top or left) to 1 (bottom or right). Of course, if the scale settings are both set to 1, the alignment settings have no effect.

GtkAlignment has been deprecated in 3.14 and should not be used in newly-written code. The desired effect can be achieved by using the #GtkWidget:halign, #GtkWidget:valign and #GtkWidget:margin properties on the child widget.

#GtkAppChooser is an interface that can be implemented by widgets which allow the user to choose an application (typically for the purpose of opening a file). The main objects that implement this interface are #GtkAppChooserWidget, #GtkAppChooserDialog and #GtkAppChooserButton.

Applications are represented by GIO #GAppInfo 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 #GtkAppChooserWidget 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 #GtkAppChooser, use [gtk.app_chooser.AppChooser.getAppInfo].

The #GtkAppChooserButton is a widget that lets the user select an application. It implements the #GtkAppChooser interface.

Initially, a #GtkAppChooserButton selects the first application in its list, which will either be the most-recently used application or, if #GtkAppChooserButton:show-default-item is true, the default application.

The list of applications shown in a #GtkAppChooserButton includes the recommended applications for the given content type. When #GtkAppChooserButton:show-default-item is set, the default application is also included. To let the user chooser other applications, you can set the #GtkAppChooserButton:show-dialog-item property, which allows to open a full #GtkAppChooserDialog.

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

To track changes in the selected application, use the #GtkComboBox::changed signal.

#GtkAppChooserDialog shows a #GtkAppChooserWidget inside a #GtkDialog.

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

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

#GtkAppChooserWidget is a widget for selecting applications. It is the main building block for #GtkAppChooserDialog. 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.

#GtkAppChooserWidget offers detailed control over what applications are shown, using the #GtkAppChooserWidget:show-default, #GtkAppChooserWidget:show-recommended, #GtkAppChooserWidget:show-fallback, #GtkAppChooserWidget:show-other and #GtkAppChooserWidget:show-all properties. See the #GtkAppChooser documentation for more information about these groups of applications.

To keep track of the selected application, use the #GtkAppChooserWidget::application-selected and #GtkAppChooserWidget::application-activated signals.

CSS nodes

GtkAppChooserWidget has a single CSS node with name appchooser.

#GtkApplication is a class that handles many important aspects of a GTK+ application in a convenient fashion, without enforcing a one-size-fits-all application model.

Currently, GtkApplication 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 GtkApplication works fine with plain #GtkWindows, it is recommended to use it together with #GtkApplicationWindow.

When GDK threads are enabled, GtkApplication will acquire the GDK lock when invoking actions that arrive from other processes. The GDK lock is not touched for local action invocations. In order to have actions invoked in a predictable context it is therefore recommended that the GDK lock be held while invoking actions locally with [gio.action_group.ActionGroup.activateAction]. The same applies to actions associated with #GtkApplicationWindow and to the “activate” and “open” #GApplication methods.

Automatic resources ## {#automatic-resources}

#GtkApplication will automatically load menus from the #GtkBuilder resource located at "gtk/menus.ui", relative to the application's resource base path (see [gio.application.Application.setResourceBasePath]). The menu with the ID "app-menu" is taken as the application's app menu and 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.

If the resources "gtk/menus-appmenu.ui" or "gtk/menus-traditional.ui" are present then these files will be used in preference, depending on the value of [gtk.application.Application.prefersAppMenu]. If the resource "gtk/menus-common.ui" is present it will be loaded as well. This is useful for storing items that are referenced from both "gtk/menus-appmenu.ui" and "gtk/menus-traditional.ui".

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

#GtkApplication 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 #GtkShortcutsWindow with ID "help_overlay" then GtkApplication associates an instance of this shortcuts window with each #GtkApplicationWindow and sets up keyboard accelerators (Control-F1 and Control-?) 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 ## {#gtkapplication}

GtkApplication optionally registers with a session manager of the users session (if you set the #GtkApplication:register-session property) and offers various functionality related to the session life-cycle.

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

See Also ## {#seealso}

#GtkApplicationWindow is a #GtkWindow subclass that offers some extra functionality for better integration with #GtkApplication features. Notably, it can handle both the application menu as well as the menubar. See [gtk.application.Application.setAppMenu] and [gtk.application.Application.setMenubar].

This class implements the #GActionGroup and #GActionMap interfaces, to let you add window-specific actions that will be exported by the associated #GtkApplication, 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 #GMenuModel.

Note that widgets that are placed inside a #GtkApplicationWindow can also activate these actions, if they implement the #GtkActionable interface.

As with #GtkApplication, the GDK lock will be acquired when processing actions arriving from other processes and should therefore be held when activating actions locally (if GDK threads are enabled).

The settings #GtkSettings:gtk-shell-shows-app-menu and #GtkSettings:gtk-shell-shows-menubar tell GTK+ whether the desktop environment is showing the application menu and menubar models outside the application as part of the desktop shell. For instance, on OS X, both menus will be displayed remotely; on Windows neither will be. gnome-shell (starting with version 3.4) will display the application menu, but not the menubar.

If the desktop environment does not display the menubar, then #GtkApplicationWindow will automatically show a #GtkMenuBar for it. This behaviour can be overridden with the #GtkApplicationWindow:show-menubar property. If the desktop environment does not display the application menu, then it will automatically be included in the menubar or in the windows client-side decorations.

A GtkApplicationWindow with a menubar

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

GtkBuilder *builder = gtk_builder_new_from_string (
   "<interface>"
   "  <menu id='menubar'>"
   "    <submenu label='_Edit'>"
   "      <item label='_Copy' action='win.copy'/>"
   "      <item label='_Paste' action='win.paste'/>"
   "    </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);

Handling fallback yourself

The XML format understood by #GtkBuilder for #GMenuModel consists of a toplevel <menu> element, which contains one or more <item> elements. Each <item> element contains <attribute> and <link> elements with a mandatory name attribute. <link> elements have the same content model as <menu>. Instead of <link name="submenu> or <link name="section">, you can use <submenu> or <section> elements.

Attribute values can be translated using gettext, like other #GtkBuilder content. <attribute> elements can be marked for translation with a translatable="yes" attribute. It is also possible to specify message context and translator comments, using the context and comments attributes. To make use of this, the #GtkBuilder must have been given the gettext domain to use.

The following attributes are used when constructing menu items:

• "label": a user-visible string to display
• "action": the prefixed name of the action to trigger
• "target": the parameter to use when activating the action
• "icon" and "verb-icon": names of icons that may be displayed
• "submenu-action": name of an action that may be used to determine

if a submenu can be opened

• "hidden-when": a string used to determine when the item will be hidden.

Possible values include "action-disabled", "action-missing", "macos-menubar".

The following attributes are used when constructing sections:

• "label": a user-visible string to use as section heading
• "display-hint": a string used to determine special formatting for the section.

Possible values include "horizontal-buttons".

• "text-direction": a string used to determine the #GtkTextDirection to use

when "display-hint" is set to "horizontal-buttons". Possible values include "rtl", "ltr", and "none".

The following attributes are used when constructing submenus:

• "label": a user-visible string to display
• "icon": icon name to display

GtkArrow should be used to draw simple arrows that need to point in one of the four cardinal directions (up, down, left, or right). The style of the arrow can be one of shadow in, shadow out, etched in, or etched out. Note that these directions and style types may be amended in versions of GTK+ to come.

GtkArrow will fill any space alloted to it, but since it is inherited from #GtkMisc, it can be padded and/or aligned, to fill exactly the space the programmer desires.

Arrows are created with a call to [gtk.arrow.Arrow.new_]. The direction or style of an arrow can be changed after creation by using [gtk.arrow.Arrow.set].

GtkArrow has been deprecated; you can simply use a #GtkImage with a suitable icon name, such as “pan-down-symbolic“. When replacing GtkArrow by an image, pay attention to the fact that GtkArrow is doing automatic flipping between #GTK_ARROW_LEFT and #GTK_ARROW_RIGHT, depending on the text direction. To get the same effect with an image, use the icon names “pan-start-symbolic“ and “pan-end-symbolic“, which react to the text direction.

The #GtkAspectFrame is useful when you want pack a widget so that it can resize but always retains the same aspect ratio. For instance, one might be drawing a small preview of a larger image. #GtkAspectFrame derives from #GtkFrame, so it can draw a label and a frame around the child. The frame will be “shrink-wrapped” to the size of the child.

CSS nodes

GtkAspectFrame uses a CSS node with name frame.

A #GtkAssistant is a widget used to represent a generally complex operation splitted in several steps, guiding the user through its pages and controlling the page flow to collect the necessary data.

The design of GtkAssistant is that it controls what buttons to show and to make sensitive, based on what it knows about the page sequence and the [type][GtkAssistantPageType] of each page, in addition to state information like the page [completion][gtk-assistant-set-page-complete] and [committed][gtk-assistant-commit] status.

If you have a case that doesn’t quite fit in #GtkAssistants way of handling buttons, you can use the #GTK_ASSISTANT_PAGE_CUSTOM page type and handle buttons yourself.

GtkAssistant as GtkBuildable

The GtkAssistant implementation of the #GtkBuildable interface exposes the @action_area as internal children with the name “action_area”.

To add pages to an assistant in #GtkBuilder, simply add it as a child to the GtkAssistant object, and set its child properties as necessary.

CSS nodes

GtkAssistant has a single CSS node with the name assistant.

The #GtkBin widget is a container with just one child. It is not very useful itself, but it is useful for deriving subclasses, since it provides common code needed for handling a single child widget.

Many GTK+ widgets are subclasses of #GtkBin, including #GtkWindow, #GtkButton, #GtkFrame, #GtkHandleBox or #GtkScrolledWindow.

A #GtkBindingArg holds the data associated with an argument for a key binding signal emission as stored in #GtkBindingSignal.

Each key binding element of a binding sets binding list is represented by a GtkBindingEntry.

A binding set maintains a list of activatable key bindings. A single binding set can match multiple types of widgets. Similar to style contexts, can be matched by any information contained in a widgets #GtkWidgetPath. When a binding within a set is matched upon activation, an action signal is emitted on the target widget to carry out the actual activation.

A GtkBindingSignal stores the necessary information to activate a widget in response to a key press via a signal emission.

A struct that specifies a border around a rectangular area that can be of different width on each side.

The GtkBox widget arranges child widgets into a single row or column, depending upon the value of its #GtkOrientable:orientation property. Within the other dimension, all children are allocated the same size. Of course, the #GtkWidget:halign and #GtkWidget:valign properties can be used on the children to influence their allocation.

GtkBox uses a notion of packing. Packing refers to adding widgets with reference to a particular position in a #GtkContainer. For a GtkBox, there are two reference positions: the start and the end of the box. For a vertical #GtkBox, the start is defined as the top of the box and the end is defined as the bottom. For a horizontal #GtkBox the start is defined as the left side and the end is defined as the right side.

Use repeated calls to [gtk.box.Box.packStart] to pack widgets into a GtkBox from start to end. Use [gtk.box.Box.packEnd] to add widgets from end to start. You may intersperse these calls and add widgets from both ends of the same GtkBox.

Because GtkBox is a #GtkContainer, you may also use [gtk.container.Container.add] to insert widgets into the box, and they will be packed with the default values for expand and fill child properties. Use [gtk.container.Container.remove] to remove widgets from the GtkBox.

Use [gtk.box.Box.setHomogeneous] to specify whether or not all children of the GtkBox 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 GtkBox. Note that spacing is added between the children, while padding added by [gtk.box.Box.packStart] or [gtk.box.Box.packEnd] is added on either side of the widget it belongs to.

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

Use [gtk.box.Box.setChildPacking] to reset the expand, fill and padding child properties. Use [gtk.box.Box.queryChildPacking] to query these fields.

CSS nodes

GtkBox uses a single CSS node with name box.

In horizontal orientation, the nodes of the children are always arranged from left to right. So :first-child will always select the leftmost child, regardless of text direction.

GtkBuildable allows objects to extend and customize their deserialization from [GtkBuilder UI descriptions][BUILDER-UI]. The interface includes methods for setting names and properties of objects, parsing custom tags and constructing child objects.

The GtkBuildable 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 #GtkBuilder. 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 #GtkBuilder format or run any extra routines at deserialization time.

The #GtkBuildableIface interface contains method that are necessary to allow #GtkBuilder to construct an object from a #GtkBuilder UI definition.

A GtkBuilder is an auxiliary object that reads textual descriptions of a user interface and instantiates the described objects. To create a GtkBuilder 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 GtkBuilder 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 GtkBuilder 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.widget.Widget.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.widget.Widget.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.

The function [gtk.builder.Builder.connectSignals] and variants thereof can be used to connect handlers to the named signals in the description.

GtkBuilder UI Definitions # {#BUILDER-UI}

GtkBuilder parses textual descriptions of user interfaces which are specified in an XML format which can be roughly described by the RELAX NG schema below. We refer to these descriptions as “GtkBuilder UI definitions” or just “UI definitions” if the context is clear. Do not confuse GtkBuilder UI Definitions with [GtkUIManager UI Definitions][XML-UI], which are more limited in scope. It is common to use .ui as the filename extension for files containing GtkBuilder UI definitions.

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. 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 (most often widgets inside a container, but also e.g. actions in an action group, or columns in a tree model). A <child> element contains an <object> element which describes the child object. 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>. The builder will error out if the version requirements are not met.

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 explictly with the "type-func" attribute. As a special case, GtkBuilder allows to use an object that has been constructed by a #GtkUIManager in another part of the UI definition by specifying the id of the #GtkUIManager in the “constructor” attribute and the name of the object in the “id” attribute.

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 ___ (3 underscores) for its own purposes.

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

GtkBuilder 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, strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted as false), enumerations (can be specified by their name, nick or integer value), flags (can be specified by their name, nick, integer value, optionally combined with “|”, e.g. “GTK_VISIBLE|GTK_REALIZED”) and colors (in a format understood by [gdk.rgba.RGBA.parse]).

GVariants can be specified in the format understood by [glib.variant.Variant.parse], and 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, GtkBuilder 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.

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, "bind-property" to specify the source property and optionally "bind-flags" to specify the binding flags. Internally builder implements this using GBinding objects. For more information see [gobject.object.ObjectWrap.bindProperty]

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. By default, GTK+ tries to find the handler using [gmodule.module_.Module.symbol], but this can be changed by passing a custom #GtkBuilderConnectFunc to [gtk.builder.Builder.connectSignalsFull]. The remaining attributes, “after”, “swapped” and “object”, have the same meaning as the corresponding parameters of the [gobject.global.signalConnectObject] or [gobject.global.signalConnectData] functions. A “last_modification_time” attribute is also allowed, but it does not have a meaning to the builder.

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 @vbox of a #GtkDialog). This can be achieved by setting the “internal-child” property of the <child> element to a true value. Note that GtkBuilder still requires an <object> element for the internal child, even if it has already been constructed.

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.

A GtkBuilder UI Definition

<interface>
 <object class="GtkDialog" id="dialog1">
   <child internal-child="vbox">
     <object class="GtkBox" id="vbox1">
       <property name="border-width">10</property>
       <child internal-child="action_area">
         <object class="GtkButtonBox" id="hbuttonbox1">
           <property name="border-width">20</property>
           <child>
             <object class="GtkButton" id="ok_button">
               <property name="label">gtk-ok</property>
               <property name="use-stock">TRUE</property>
               <signal name="clicked" handler="ok_button_clicked"/>
             </object>
           </child>
         </object>
       </child>
     </object>
   </child>
 </object>
</interface>

Beyond this general structure, several object classes define their own XML DTD fragments for filling in the ANY placeholders in the DTD above. Note that a custom element in a <child> element gets parsed by the custom tag handler of the parent object, while a custom element in an <object> element gets parsed by the custom tag handler of the object.

These XML fragments are explained in the documentation of the respective objects.

Additionally, since 3.10 a special <template> tag has been added to the format allowing one to define a widget class’s components. See the [GtkWidget documentation][composite-templates] for details.

The #GtkButton widget is generally used to trigger a callback function that is called when the button is pressed. The various signals and how to use them are outlined below.

The #GtkButton widget can hold any valid child widget. That is, it can hold almost any other standard #GtkWidget. The most commonly used child is the #GtkLabel.

CSS nodes

GtkButton 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.

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

Button-like widgets like #GtkToggleButton, #GtkMenuButton, #GtkVolumeButton, #GtkLockButton, #GtkColorButton, #GtkFontButton or #GtkFileChooserButton use style classes such as .toggle, .popup, .scale, .lock, .color, .font, .file to differentiate themselves from a plain GtkButton.

#GtkCalendar is a widget that displays a Gregorian calendar, one month at a time. It can be created with [gtk.calendar.Calendar.new_].

The month and year currently displayed can be altered with [gtk.calendar.Calendar.selectMonth]. The exact day can be selected from the displayed month using [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 way in which the calendar itself is displayed can be altered using [gtk.calendar.Calendar.setDisplayOptions].

The selected date can be retrieved from a #GtkCalendar 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.

The #GtkCellArea is an abstract class for #GtkCellLayout widgets (also referred to as "layouting widgets") to interface with an arbitrary number of #GtkCellRenderers and interact with the user for a given #GtkTreeModel 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 #GtkCellArea directly unless they are implementing a cell-layouting widget themselves.

Requesting area sizes

As outlined in [GtkWidget’s geometry management section][geometry-management], GTK+ uses a height-for-width geometry management system to compute the sizes of widgets and user interfaces. #GtkCellArea uses the same semantics to calculate the size of an area for an arbitrary number of #GtkTreeModel 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 #GtkTreeViewColumn always lines up the areas from top to bottom while a #GtkIconView 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 #GtkCellArea uses a #GtkCellAreaContext 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 #GtkCellAreaContext is an opaque object specific to the #GtkCellArea 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 #GtkCellAreaContext which was used to request the sizes for a given #GtkTreeModel 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 #GtkTreeModel one would do the following:

GtkTreeIter iter;
gint        minimum_width;
gint        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 #GtkCellAreaContext object and can be consulted at any time.

This can be useful since #GtkCellLayout widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The #GtkCellLayout widget in that case would calculate the required width of the rows in an idle or timeout source (see [glib.global.timeoutAdd]) and when the widget is requested its actual width in #GtkWidgetClass.get_preferred_width() it can simply consult the width accumulated so far in the #GtkCellAreaContext 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,
                        gint            *minimum_size,
                        gint            *natural_size)
{
 Foo        *foo  = FOO (widget);
 FooPrivate *priv = foo->priv;

 foo_ensure_at_least_one_handfull_of_rows_have_been_requested (foo);

 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 #GtkCellAreaContext.

Requesting the height for width (or width for height) of an area is a similar task except in this case the #GtkCellAreaContext 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 #GtkCellArea).

In order to request the height for width of all the rows at the root level of a #GtkTreeModel one would do the following:

GtkTreeIter iter;
gint        minimum_height;
gint        natural_height;
gint        full_minimum_height = 0;
gint        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 #GtkWidgetClass.get_preferred_height_for_width(). 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 aquired at least for the rows in the visible area of the layouting widget they can be rendered at #GtkWidgetClass.draw() 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;
gint          minimum_width;
gint          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 #GtkWidget::size-allocate time using [gtk.global.distributeNaturalAllocation].

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 #GtkCellArea 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 #GtkCellArea::focus-changed signal to fire; as well as #GtkCellArea::add-editable in the case that an editable cell was clicked and needs to start editing. You can call [gtk.cell_area.CellArea.stopEditing] at any time to cancel any cell editing that is currently in progress.

The #GtkCellArea drives keyboard focus from cell to cell in a way similar to #GtkWidget. 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 #GtkWidgetClass.focus() virtual method. The layouting widget is always responsible for knowing where #GtkTreeModel rows are rendered inside the widget, so at #GtkWidgetClass.focus() time the layouting widget should use the #GtkCellArea methods to navigate focus inside the area and then observe the GtkDirectionType to pass the focus to adjacent rows and areas.

A basic example of how the #GtkWidgetClass.focus() virtual method should be implemented:

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

 focus_row = priv->focus_row;

 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 GtkDirectionType values to the way it lays out its cells.

Cell Properties

The #GtkCellArea introduces cell properties for #GtkCellRenderers in very much the same way that #GtkContainer introduces [child properties][child-properties] for #GtkWidgets. This provides some general interfaces for defining the relationship cell areas have with their cells. For instance in a #GtkCellAreaBox 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 #GtkCellAreaContext.

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].

The #GtkCellAreaBox renders cell renderers into a row or a column depending on its #GtkOrientation.

GtkCellAreaBox uses a notion of packing. Packing refers to adding cell renderers with reference to a particular position in a #GtkCellAreaBox. There are two reference positions: the start and the end of the box. When the #GtkCellAreaBox 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 #GtkCellRenderers rendered in adjacent rows can be configured by configuring the #GtkCellAreaBox 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].

The #GtkCellAreaContext object is created by a given #GtkCellArea implementation via its #GtkCellAreaClass.create_context() virtual method and is used to store cell sizes and alignments for a series of #GtkTreeModel rows that are requested and rendered in the same context.

#GtkCellLayout 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 #GtkTreeModel row also be used for the same row when calling other #GtkCellArea APIs such as [gtk.cell_area.CellArea.render] and [gtk.cell_area.CellArea.event].

The #GtkCellEditable interface must be implemented for widgets to be usable to edit the contents of a #GtkTreeView cell. It provides a way to specify how temporary widgets should be configured for editing, get the new value, etc.

#GtkCellLayout is an interface to be implemented by all objects which want to provide a #GtkTreeViewColumn like API for packing cells, setting attributes and data funcs.

One of the notable features provided by implementations of GtkCellLayout 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 (#GtkCellView, #GtkIconView, #GtkComboBox, #GtkEntryCompletion, #GtkTreeViewColumn) accept GtkCellRenderer 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 GtkCellLayout that use a #GtkCellArea to lay out cells (all GtkCellLayouts in GTK+ use a GtkCellArea) [cell properties][cell-properties] can also be defined in the format by specifying the custom <cell-packing> attribute which can contain multiple <property> elements defined in the normal way.

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 #GtkCellLayout like #GtkIconView or #GtkComboBox, there are some considerations related to the fact that these widgets internally use a #GtkCellArea. The cell area is exposed as a construct-only property by these widgets. This means that it is possible to e.g. do

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.

The #GtkCellRenderer is a base class of a set of objects used for rendering a cell to a #cairo_t. These objects are used primarily by the #GtkTreeView widget, though they aren’t tied to them in any specific way. It is worth noting that #GtkCellRenderer is not a #GtkWidget and cannot be treated as such.

The primary use of a #GtkCellRenderer is for drawing a certain graphical elements on a #cairo_t. 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 #GObjects property system. Then, the cell is measured using [gtk.cell_renderer.CellRenderer.getSize]. Finally, the cell is rendered in the correct location using [gtk.cell_renderer.CellRenderer.render].

There are a number of rules that must be followed when writing a new #GtkCellRenderer. First and foremost, it’s important that a certain set of properties will always yield a cell renderer of the same size, barring a #GtkStyle change. The #GtkCellRenderer 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 #GtkCellRendererToggle, which toggles when it gets activated by a mouse click, or it can be “editable” like #GtkCellRendererText, which allows the user to edit the text using a widget implementing the #GtkCellEditable interface, e.g. #GtkEntry. To make a cell renderer activatable or editable, you have to implement the #GtkCellRendererClass.activate or #GtkCellRendererClass.start_editing virtual functions, respectively.

Many properties of #GtkCellRenderer 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.

#GtkCellRendererAccel 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.

The #GtkCellRendererAccel cell renderer was added in GTK+ 2.10.

#GtkCellRendererCombo renders text in a cell like #GtkCellRendererText from which it is derived. But while #GtkCellRendererText offers a simple entry to edit the text, #GtkCellRendererCombo offers a #GtkComboBox widget to edit the text. The values to display in the combo box are taken from the tree model specified in the #GtkCellRendererCombo: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 #GtkCellRendererCombo:text-column property. Further properties of the combo box can be set in a handler for the #GtkCellRenderer::editing-started signal.

The #GtkCellRendererCombo cell renderer was added in GTK+ 2.6.

A #GtkCellRendererPixbuf can be used to render an image in a cell. It allows to render either a given #GdkPixbuf (set via the #GtkCellRendererPixbuf:pixbuf property) or a named icon (set via the #GtkCellRendererPixbuf:icon-name property).

To support the tree view, #GtkCellRendererPixbuf 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.

#GtkCellRendererProgress renders a numeric value as a progress par in a cell. Additionally, it can display a text on top of the progress bar.

The #GtkCellRendererProgress cell renderer was added in GTK+ 2.6.

#GtkCellRendererSpin renders text in a cell like #GtkCellRendererText from which it is derived. But while #GtkCellRendererText offers a simple entry to edit the text, #GtkCellRendererSpin offers a #GtkSpinButton 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. #GtkCellRendererSpin also has properties for the #GtkCellRendererSpin:climb-rate and the number of #GtkCellRendererSpin:digits to display. Other #GtkSpinButton properties can be set in a handler for the #GtkCellRenderer::editing-started signal.

The #GtkCellRendererSpin cell renderer was added in GTK+ 2.10.

GtkCellRendererSpinner renders a spinning animation in a cell, very similar to #GtkSpinner. It can often be used as an alternative to a #GtkCellRendererProgress 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].

A #GtkCellRendererText 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 #GtkCellRendererText allows to edit its text using an entry.

#GtkCellRendererToggle 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 #GtkCellView displays a single row of a #GtkTreeModel using a #GtkCellArea and #GtkCellAreaContext. A #GtkCellAreaContext can be provided to the #GtkCellView 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 eachother (like the aligned cells in the menus of #GtkComboBox).

#GtkCellView is #GtkOrientable in order to decide in which orientation the underlying #GtkCellAreaContext should be allocated. Taking the #GtkComboBox 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.

A #GtkCheckButton places a discrete #GtkToggleButton next to a widget, (usually a #GtkLabel). See the section on #GtkToggleButton widgets for more information about toggle/check buttons.

The important signal ( #GtkToggleButton::toggled ) is also inherited from #GtkToggleButton.

CSS nodes

checkbutton
├── check
╰── <child>

A GtkCheckButton with indicator (see [gtk.toggle_button.ToggleButton.setMode]) has a main CSS node with name checkbutton and a subnode with name check.

button.check
├── check
╰── <child>

A GtkCheckButton without indicator changes the name of its main node to button and adds a .check style class to it. The subnode is invisible in this case.

A #GtkCheckMenuItem is a menu item that maintains the state of a boolean value in addition to a #GtkMenuItem usual role in activating application code.

A check box indicating the state of the boolean value is displayed at the left side of the #GtkMenuItem. Activating the #GtkMenuItem toggles the value.

CSS nodes

menuitem
├── check.left
╰── <child>