GtkApplication is a high-level API for writing applications.

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

Currently, 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 [classGtk.Window]s, it is recommended to use it together with [classGtk.ApplicationWindow].

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 g_application_set_resource_base_path()). The menu with the ID “menubar” is taken as the application’s menubar. Additional menus (most interesting submenus) can be named and accessed via [methodGtk.Application.get_menu_by_id] which allows for dynamic population of a part of the menu structure.

It is also possible to provide the menubar manually using [methodGtk.Application.set_menubar].

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 [methodGtk.IconTheme.add_resource_path] for more information.

If there is a resource located at “gtk/help-overlay.ui” which defines a [classGtk.ShortcutsWindow] with ID “help_overlay” then GtkApplication associates an instance of this shortcuts window with each [classGtk.ApplicationWindow] and sets up the keyboard accelerator <kbd>Control</kbd>+<kbd>?</kbd> to open it. To create a menu item that displays the shortcuts window, associate the item with the action win.show-help-overlay.

A simple application

A simple example is available in the GTK source code repository

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

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

See Also

HowDoI: Using GtkApplication, Getting Started with GTK: Basics

The Application type acts as a reference-counted owner of an underlying GtkApplication instance. It provides the methods that can operate on this data type through ApplicationProtocol conformance. Use Application as a strong reference or owner of a GtkApplication instance.

A GtkCheckButton places a label next to an indicator.

A GtkCheckButton is created by calling either [ctorGtk.CheckButton.new] or [ctorGtk.CheckButton.new_with_label].

The state of a GtkCheckButton can be set specifically using [methodGtk.CheckButton.set_active], and retrieved using [methodGtk.CheckButton.get_active].

Inconsistent state

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

To set a GtkCheckButton to inconsistent state, use [methodGtk.CheckButton.set_inconsistent].

Grouping

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

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

To add a GtkCheckButton to a group, use [methodGtk.CheckButton.set_group].

CSS nodes

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

A GtkCheckButton has a main node with name checkbutton. If the [propertyGtk.CheckButton:label] property is set, it contains a label child. The indicator node is named check when no group is set, and radio if the checkbutton is grouped together with other checkbuttons.

Accessibility

GtkCheckButton uses the GTK_ACCESSIBLE_ROLE_CHECKBOX role.

The CheckButton type acts as a reference-counted owner of an underlying GtkCheckButton instance. It provides the methods that can operate on this data type through CheckButtonProtocol conformance. Use CheckButton as a strong reference or owner of a GtkCheckButton instance.

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

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

The main area of a GtkDialog is called the “content area”, and is yours to populate with widgets such a GtkLabel or GtkEntry, to present your information, questions, or tasks to the user.

In addition, dialogs allow you to add “action widgets”. Most commonly, action widgets are buttons. Depending on the platform, action widgets may be presented in the header bar at the top of the window, or at the bottom of the window. To add action widgets, create your GtkDialog using [ctorGtk.Dialog.new_with_buttons], or use [methodGtk.Dialog.add_button], [methodGtk.Dialog.add_buttons], or [methodGtk.Dialog.add_action_widget].

GtkDialogs uses some heuristics to decide whether to add a close button to the window decorations. If any of the action buttons use the response ID GTK_RESPONSE_CLOSE or GTK_RESPONSE_CANCEL, the close button is omitted.

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

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

A “modal” dialog (that is, one which freezes the rest of the application from user input), can be created by calling [methodGtk.Window.set_modal] on the dialog. When using [ctorGtk.Dialog.new_with_buttons], you can also pass the GTK_DIALOG_MODAL flag to make a dialog modal.

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

An example for simple GtkDialog usage:

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

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

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

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

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

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

GtkDialog as GtkBuildable

The GtkDialog implementation of the GtkBuildable interface exposes the content_area as an internal child with the name “content_area”.

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

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

An example of a GtkDialog UI definition fragment:

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

Accessibility

GtkDialog uses the GTK_ACCESSIBLE_ROLE_DIALOG role.

The Dialog type acts as a reference-counted owner of an underlying GtkDialog instance. It provides the methods that can operate on this data type through DialogProtocol conformance. Use Dialog as a strong reference or owner of a GtkDialog instance.

GtkFileChooserDialog is a dialog suitable for use with “File Open” or “File Save” commands.

This widget works by putting a [classGtk.FileChooserWidget] inside a [classGtk.Dialog]. It exposes the [ifaceGtk.FileChooser] interface, so you can use all of the [ifaceGtk.FileChooser] functions on the file chooser dialog as well as those for [classGtk.Dialog].

Note that GtkFileChooserDialog does not have any methods of its own. Instead, you should use the functions that work on a [ifaceGtk.FileChooser].

If you want to integrate well with the platform you should use the [classGtk.FileChooserNative] API, which will use a platform-specific dialog if available and fall back to GtkFileChooserDialog otherwise.

Typical usage

In the simplest of cases, you can the following code to use GtkFileChooserDialog to select a file for opening:

static void
on_open_response (GtkDialog *dialog,
                  int        response)
{
  if (response == GTK_RESPONSE_ACCEPT)
    {
      GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);

      `g_autoptr(GFile)` file = gtk_file_chooser_get_file (chooser);

      open_file (file);
    }

  gtk_window_destroy (GTK_WINDOW (dialog));
}

  // ...
  GtkWidget *dialog;
  GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;

  dialog = gtk_file_chooser_dialog_new ("Open File",
                                        parent_window,
                                        action,
                                        `_("_Cancel")`,
                                        GTK_RESPONSE_CANCEL,
                                        `_("_Open")`,
                                        GTK_RESPONSE_ACCEPT,
                                        NULL);

  gtk_widget_show (dialog);

  g_signal_connect (dialog, "response",
                    G_CALLBACK (on_open_response),
                    NULL);

To use a dialog for saving, you can use this:

static void
on_save_response (GtkDialog *dialog,
                  int        response)
{
  if (response == GTK_RESPONSE_ACCEPT)
    {
      GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);

      `g_autoptr(GFile)` file = gtk_file_chooser_get_file (chooser);

      save_to_file (file);
    }

  gtk_window_destroy (GTK_WINDOW (dialog));
}

  // ...
  GtkWidget *dialog;
  GtkFileChooser *chooser;
  GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;

  dialog = gtk_file_chooser_dialog_new ("Save File",
                                        parent_window,
                                        action,
                                        `_("_Cancel")`,
                                        GTK_RESPONSE_CANCEL,
                                        `_("_Save")`,
                                        GTK_RESPONSE_ACCEPT,
                                        NULL);
  chooser = GTK_FILE_CHOOSER (dialog);

  if (user_edited_a_new_document)
    gtk_file_chooser_set_current_name (chooser, `_("Untitled document")`);
  else
    gtk_file_chooser_set_file (chooser, existing_filename);

  gtk_widget_show (dialog);

  g_signal_connect (dialog, "response",
                    G_CALLBACK (on_save_response),
                    NULL);

Setting up a file chooser dialog

There are various cases in which you may need to use a GtkFileChooserDialog:

• To select a file for opening, use GTK_FILE_CHOOSER_ACTION_OPEN.

• To save a file for the first time, use GTK_FILE_CHOOSER_ACTION_SAVE, and suggest a name such as “Untitled” with [methodGtk.FileChooser.set_current_name].

• To save a file under a different name, use GTK_FILE_CHOOSER_ACTION_SAVE, and set the existing file with [methodGtk.FileChooser.set_file].

• To choose a folder instead of a filem use GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.

In general, you should only cause the file chooser to show a specific folder when it is appropriate to use [methodGtk.FileChooser.set_file], i.e. when you are doing a “Save As” command and you already have a file saved somewhere.

Response Codes

GtkFileChooserDialog inherits from [classGtk.Dialog], so buttons that go in its action area have response codes such as GTK_RESPONSE_ACCEPT and GTK_RESPONSE_CANCEL. For example, you could call [ctorGtk.FileChooserDialog.new] as follows:

GtkWidget *dialog;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;

dialog = gtk_file_chooser_dialog_new ("Open File",
                                      parent_window,
                                      action,
                                      `_("_Cancel")`,
                                      GTK_RESPONSE_CANCEL,
                                      `_("_Open")`,
                                      GTK_RESPONSE_ACCEPT,
                                      NULL);

This will create buttons for “Cancel” and “Open” that use predefined response identifiers from [enumGtk.ResponseType]. For most dialog boxes you can use your own custom response codes rather than the ones in [enumGtk.ResponseType], but GtkFileChooserDialog assumes that its “accept”-type action, e.g. an “Open” or “Save” button, will have one of the following response codes:

• GTK_RESPONSE_ACCEPT
• GTK_RESPONSE_OK
• GTK_RESPONSE_YES
• GTK_RESPONSE_APPLY

This is because GtkFileChooserDialog must intercept responses and switch to folders if appropriate, rather than letting the dialog terminate — the implementation uses these known response codes to know which responses can be blocked if appropriate.

To summarize, make sure you use a predefined response code when you use GtkFileChooserDialog to ensure proper operation.

The FileChooserDialog type acts as a reference-counted owner of an underlying GtkFileChooserDialog instance. It provides the methods that can operate on this data type through FileChooserDialogProtocol conformance. Use FileChooserDialog as a strong reference or owner of a GtkFileChooserDialog instance.

GtkFileChooserNative is an abstraction of a dialog suitable for use with “File Open” or “File Save as” commands.

By default, this just uses a GtkFileChooserDialog to implement the actual dialog. However, on some platforms, such as Windows and macOS, the native platform file chooser is used instead. When the application is running in a sandboxed environment without direct filesystem access (such as Flatpak), GtkFileChooserNative may call the proper APIs (portals) to let the user choose a file and make it available to the application.

While the API of GtkFileChooserNative closely mirrors GtkFileChooserDialog, the main difference is that there is no access to any GtkWindow or GtkWidget for the dialog. This is required, as there may not be one in the case of a platform native dialog.

Showing, hiding and running the dialog is handled by the [classGtk.NativeDialog] functions.

Note that unlike GtkFileChooserDialog, GtkFileChooserNative objects are not toplevel widgets, and GTK does not keep them alive. It is your responsibility to keep a reference until you are done with the object.

Typical usage

In the simplest of cases, you can the following code to use GtkFileChooserNative to select a file for opening:

static void
on_response (GtkNativeDialog *native,
             int              response)
{
  if (response == GTK_RESPONSE_ACCEPT)
    {
      GtkFileChooser *chooser = GTK_FILE_CHOOSER (native);
      GFile *file = gtk_file_chooser_get_file (chooser);

      open_file (file);

      g_object_unref (file);
    }

  g_object_unref (native);
}

  // ...
  GtkFileChooserNative *native;
  GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;

  native = gtk_file_chooser_native_new ("Open File",
                                        parent_window,
                                        action,
                                        "_Open",
                                        "_Cancel");

  g_signal_connect (native, "response", G_CALLBACK (on_response), NULL);
  gtk_native_dialog_show (GTK_NATIVE_DIALOG (native));

To use a GtkFileChooserNative for saving, you can use this:

static void
on_response (GtkNativeDialog *native,
             int              response)
{
  if (response == GTK_RESPONSE_ACCEPT)
    {
      GtkFileChooser *chooser = GTK_FILE_CHOOSER (native);
      GFile *file = gtk_file_chooser_get_file (chooser);

      save_to_file (file);

      g_object_unref (file);
    }

  g_object_unref (native);
}

  // ...
  GtkFileChooserNative *native;
  GtkFileChooser *chooser;
  GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;

  native = gtk_file_chooser_native_new ("Save File",
                                        parent_window,
                                        action,
                                        "_Save",
                                        "_Cancel");
  chooser = GTK_FILE_CHOOSER (native);

  if (user_edited_a_new_document)
    gtk_file_chooser_set_current_name (chooser, `_("Untitled document")`);
  else
    gtk_file_chooser_set_file (chooser, existing_file, NULL);

  g_signal_connect (native, "response", G_CALLBACK (on_response), NULL);
  gtk_native_dialog_show (GTK_NATIVE_DIALOG (native));

For more information on how to best set up a file dialog, see the [classGtk.FileChooserDialog] documentation.

Response Codes

GtkFileChooserNative inherits from [classGtk.NativeDialog], which means it will return GTK_RESPONSE_ACCEPT if the user accepted, and GTK_RESPONSE_CANCEL if he pressed cancel. It can also return GTK_RESPONSE_DELETE_EVENT if the window was unexpectedly closed.

Differences from GtkFileChooserDialog

There are a few things in the [ifaceGtk.FileChooser] interface that are not possible to use with GtkFileChooserNative, as such use would prohibit the use of a native dialog.

No operations that change the dialog work while the dialog is visible. Set all the properties that are required before showing the dialog.

Win32 details

On windows the IFileDialog implementation (added in Windows Vista) is used. It supports many of the features that GtkFileChooser has, but there are some things it does not handle:

• Any [classGtk.FileFilter] added using a mimetype

If any of these features are used the regular GtkFileChooserDialog will be used in place of the native one.

Portal details

When the org.freedesktop.portal.FileChooser portal is available on the session bus, it is used to bring up an out-of-process file chooser. Depending on the kind of session the application is running in, this may or may not be a GTK file chooser.

macOS details

On macOS the NSSavePanel and NSOpenPanel classes are used to provide native file chooser dialogs. Some features provided by GtkFileChooser are not supported:

• Shortcut folders.

The FileChooserNative type acts as a reference-counted owner of an underlying GtkFileChooserNative instance. It provides the methods that can operate on this data type through FileChooserNativeProtocol conformance. Use FileChooserNative as a strong reference or owner of a GtkFileChooserNative instance.

GtkATContext is an abstract class provided by GTK to communicate to platform-specific assistive technologies API.

Each platform supported by GTK implements a GtkATContext subclass, and is responsible for updating the accessible state in response to state changes in GtkAccessible.

The ATContext type acts as a reference-counted owner of an underlying GtkATContext instance. It provides the methods that can operate on this data type through ATContextProtocol conformance. Use ATContext as a strong reference or owner of a GtkATContext instance.

The GtkAboutDialog offers a simple way to display information about a program.

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

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

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

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

To make constructing a GtkAboutDialog as convenient as possible, you can use the function [funcGtk.show_about_dialog] which constructs and shows a dialog and keeps it around so that it can be shown again.

Note that GTK sets a default title of _("About %s") on the dialog window (where s is replaced by the name of the application, but in order to ensure proper translation of the title, applications should set the title property explicitly when constructing a GtkAboutDialog, as shown in the following example:

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

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

CSS nodes

GtkAboutDialog has a single CSS node with the name window and style class .aboutdialog.

The AboutDialog type acts as a reference-counted owner of an underlying GtkAboutDialog instance. It provides the methods that can operate on this data type through AboutDialogProtocol conformance. Use AboutDialog as a strong reference or owner of a GtkAboutDialog instance.

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

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

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

Each of the boxes contains children packed for that side.

The ActionBar type acts as a reference-counted owner of an underlying GtkActionBar instance. It provides the methods that can operate on this data type through ActionBarProtocol conformance. Use ActionBar as a strong reference or owner of a GtkActionBar instance.

A GtkShortcutAction that calls gtk_widget_activate().

The ActivateAction type acts as a reference-counted owner of an underlying GtkActivateAction instance. It provides the methods that can operate on this data type through ActivateActionProtocol conformance. Use ActivateAction as a strong reference or owner of a GtkActivateAction instance.

GtkAdjustment is a model for a numeric value.

The `GtkAdjustment has an associated lower and upper bound. It also contains step and page increments, and a page size.

Adjustments are used within several GTK widgets, including [classGtk.SpinButton], [classGtk.Viewport], [classGtk.Scrollbar] and [classGtk.Scale].

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 Adjustment type acts as a reference-counted owner of an underlying GtkAdjustment instance. It provides the methods that can operate on this data type through AdjustmentProtocol conformance. Use Adjustment as a strong reference or owner of a GtkAdjustment instance.

A GtkShortcutTrigger that combines two triggers.

The GtkAlternativeTrigger triggers when either of two trigger.

This can be cascaded to combine more than two triggers.

The AlternativeTrigger type acts as a reference-counted owner of an underlying GtkAlternativeTrigger instance. It provides the methods that can operate on this data type through AlternativeTriggerProtocol conformance. Use AlternativeTrigger as a strong reference or owner of a GtkAlternativeTrigger instance.

GtkAnyFilter matches an item when at least one of its filters matches.

To add filters to a GtkAnyFilter, use [methodGtk.MultiFilter.append].

The AnyFilter type acts as a reference-counted owner of an underlying GtkAnyFilter instance. It provides the methods that can operate on this data type through AnyFilterProtocol conformance. Use AnyFilter as a strong reference or owner of a GtkAnyFilter instance.

The GtkAppChooserButton lets the user select an application.

Initially, a GtkAppChooserButton selects the first application in its list, which will either be the most-recently used application or, if [propertyGtk.AppChooserButton: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 [propertyGtk.AppChooserButton:show-default-item] is set, the default application is also included. To let the user chooser other applications, you can set the [propertyGtk.AppChooserButton:show-dialog-item] property, which allows to open a full [classGtk.AppChooserDialog].

It is possible to add custom items to the list, using [methodGtk.AppChooserButton.append_custom_item]. These items cause the [signalGtk.AppChooserButton::custom-item-activated] signal to be emitted when they are selected.

To track changes in the selected application, use the [signalGtk.AppChooserButton::changed] signal.

CSS nodes

GtkAppChooserButton has a single CSS node with the name “appchooserbutton”.

The AppChooserButton type acts as a reference-counted owner of an underlying GtkAppChooserButton instance. It provides the methods that can operate on this data type through AppChooserButtonProtocol conformance. Use AppChooserButton as a strong reference or owner of a GtkAppChooserButton instance.

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 [methodGtk.AppChooserDialog.get_widget] and call its methods if the generic [ifaceGtk.AppChooser] interface is not sufficient for your needs.

To set the heading that is shown above the GtkAppChooserWidget, use [methodGtk.AppChooserDialog.set_heading].

The AppChooserDialog type acts as a reference-counted owner of an underlying GtkAppChooserDialog instance. It provides the methods that can operate on this data type through AppChooserDialogProtocol conformance. Use AppChooserDialog as a strong reference or owner of a GtkAppChooserDialog instance.

GtkAppChooserWidget is a widget for selecting applications.

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

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

To keep track of the selected application, use the [signalGtk.AppChooserWidget::application-selected] and [signalGtk.AppChooserWidget::application-activated] signals.

CSS nodes

GtkAppChooserWidget has a single CSS node with name appchooser.

The AppChooserWidget type acts as a reference-counted owner of an underlying GtkAppChooserWidget instance. It provides the methods that can operate on this data type through AppChooserWidgetProtocol conformance. Use AppChooserWidget as a strong reference or owner of a GtkAppChooserWidget instance.

GtkApplicationWindow is a GtkWindow subclass that integrates with GtkApplication.

Notably, GtkApplicationWindow can handle an application menubar.

This class implements the GActionGroup and GActionMap interfaces, to let you add window-specific actions that will be exported by the associated [classGtk.Application], together with its application-wide actions. Window-specific actions are prefixed with the “win.” prefix and application-wide actions are prefixed with the “app.” prefix. Actions must be addressed with the prefixed name when referring to them from a GMenuModel.

Note that widgets that are placed inside a GtkApplicationWindow can also activate these actions, if they implement the [ifaceGtk.Actionable] interface.

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

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

See [classGtk.PopoverMenu] for information about the XML language used by GtkBuilder for menu models.

See also: [methodGtk.Application.set_menubar].

A GtkApplicationWindow with a menubar

The code sample below shows how to set up a GtkApplicationWindow with a menu bar defined on the [classGtk.Application]:

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

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

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

// ...

GtkWidget *window = gtk_application_window_new (app);

The ApplicationWindow type acts as a reference-counted owner of an underlying GtkApplicationWindow instance. It provides the methods that can operate on this data type through ApplicationWindowProtocol conformance. Use ApplicationWindow as a strong reference or owner of a GtkApplicationWindow instance.

GtkAspectFrame preserves the aspect ratio of its child.

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

CSS nodes

GtkAspectFrame uses a CSS node with name frame.

The AspectFrame type acts as a reference-counted owner of an underlying GtkAspectFrame instance. It provides the methods that can operate on this data type through AspectFrameProtocol conformance. Use AspectFrame as a strong reference or owner of a GtkAspectFrame instance.

GtkAssistant is used to represent a complex as a series of steps.

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

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

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

GtkAssistant maintains a GtkAssistantPage object for each added child, which holds additional per-child properties. You obtain the GtkAssistantPage for a child with [methodGtk.Assistant.get_page].

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. If you need to set per-object properties, create a GtkAssistantPage object explicitly, and set the child widget as a property on it.

CSS nodes

GtkAssistant has a single CSS node with the name window and style class .assistant.

The Assistant type acts as a reference-counted owner of an underlying GtkAssistant instance. It provides the methods that can operate on this data type through AssistantProtocol conformance. Use Assistant as a strong reference or owner of a GtkAssistant instance.

GtkAssistantPage is an auxiliary object used by `GtkAssistant.

The AssistantPage type acts as a reference-counted owner of an underlying GtkAssistantPage instance. It provides the methods that can operate on this data type through AssistantPageProtocol conformance. Use AssistantPage as a strong reference or owner of a GtkAssistantPage instance.

GtkBinLayout is a GtkLayoutManager subclass useful for create “bins” of widgets.

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

The BinLayout type acts as a reference-counted owner of an underlying GtkBinLayout instance. It provides the methods that can operate on this data type through BinLayoutProtocol conformance. Use BinLayout as a strong reference or owner of a GtkBinLayout instance.

GtkAccessible is an interface for describing UI elements for Assistive Technologies.

Every accessible implementation has:

• a “role”, represented by a value of the [enumGtk.AccessibleRole] enumeration
• an “attribute”, represented by a set of [enumGtk.AccessibleState], [enumGtk.AccessibleProperty] and [enumGtk.AccessibleRelation] values

The role cannot be changed after instantiating a GtkAccessible implementation.

The attributes are updated every time a UI element’s state changes in a way that should be reflected by assistive technologies. For instance, if a GtkWidget visibility changes, the GTK_ACCESSIBLE_STATE_HIDDEN state will also change to reflect the [propertyGtk.Widget:visible] property.

The Accessible type acts as an owner of an underlying GtkAccessible instance. It provides the methods that can operate on this data type through AccessibleProtocol conformance. Use Accessible as a strong reference or owner of a GtkAccessible instance.

The GtkActionable interface provides a convenient way of asscociating widgets with actions.

It primarily consists of two properties: [propertyGtk.Actionable:action-name] and [propertyGtk.Actionable:action-target]. There are also some convenience APIs for setting these properties.

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

The Actionable type acts as a reference-counted owner of an underlying GtkActionable instance. It provides the methods that can operate on this data type through ActionableProtocol conformance. Use Actionable as a strong reference or owner of a GtkActionable instance.

GtkAppChooser is an interface for widgets which allow the user to choose an application.

The main objects that implement this interface are [classGtk.AppChooserWidget], [classGtk.AppChooserDialog] and [classGtk.AppChooserButton].

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 [methodGtk.AppChooser.get_app_info].

The AppChooser type acts as a reference-counted owner of an underlying GtkAppChooser instance. It provides the methods that can operate on this data type through AppChooserProtocol conformance. Use AppChooser as a strong reference or owner of a GtkAppChooser instance.

GtkBuildable allows objects to extend and customize their deserialization from ui files.

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

The 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 [classGtk.Builder]. There should be very little need for applications to call any of these functions directly.

An object only needs to implement this interface if it needs to extend the GtkBuilder XML format or run any extra routines at deserialization time.

The Buildable type acts as an owner of an underlying GtkBuildable instance. It provides the methods that can operate on this data type through BuildableProtocol conformance. Use Buildable as a strong reference or owner of a GtkBuildable instance.

A GtkBitset represents a set of unsigned integers.

Another name for this data structure is “bitmap”.

The current implementation is based on roaring bitmaps.

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

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

The main use case for GtkBitset is implementing complex selections for [ifaceGtk.SelectionModel].

The Bitset type acts as a reference-counted owner of an underlying GtkBitset instance. It provides the methods that can operate on this data type through BitsetProtocol conformance. Use Bitset as a strong reference or owner of a GtkBitset instance.

An opaque, stack-allocated struct for iterating over the elements of a GtkBitset.

Before a GtkBitsetIter can be used, it needs to be initialized with [funcGtk.BitsetIter.init_first], [funcGtk.BitsetIter.init_last] or [funcGtk.BitsetIter.init_at].

The BitsetIter type acts as an owner of an underlying GtkBitsetIter instance. It provides the methods that can operate on this data type through BitsetIterProtocol conformance. Use BitsetIter as a strong reference or owner of a GtkBitsetIter instance.

A struct that specifies a border around a rectangular area.

Each side can have different width.

The Border type acts as an owner of an underlying GtkBorder instance. It provides the methods that can operate on this data type through BorderProtocol conformance. Use Border as a strong reference or owner of a GtkBorder instance.

An opaque context struct for GtkBuildableParser.

The BuildableParseContext type acts as an owner of an underlying GtkBuildableParseContext instance. It provides the methods that can operate on this data type through BuildableParseContextProtocol conformance. Use BuildableParseContext as a strong reference or owner of a GtkBuildableParseContext instance.

A sub-parser for GtkBuildable implementations.

The BuildableParser type acts as an owner of an underlying GtkBuildableParser instance. It provides the methods that can operate on this data type through BuildableParserProtocol conformance. Use BuildableParser as a strong reference or owner of a GtkBuildableParser instance.

GtkBookmarkList is a list model that wraps GBookmarkFile.

It presents a GListModel and fills it asynchronously with the GFileInfos returned from that function.

The GFileInfos in the list have some attributes in the recent namespace added: recentprivate`(boolean) andrecent:applications` (stringv).

The BookmarkList type acts as a reference-counted owner of an underlying GtkBookmarkList instance. It provides the methods that can operate on this data type through BookmarkListProtocol conformance. Use BookmarkList as a strong reference or owner of a GtkBookmarkList instance.

GtkBoolFilter evaluates a boolean GtkExpression to determine whether to include items.

The BoolFilter type acts as a reference-counted owner of an underlying GtkBoolFilter instance. It provides the methods that can operate on this data type through BoolFilterProtocol conformance. Use BoolFilter as a strong reference or owner of a GtkBoolFilter instance.

The GtkBox widget arranges child widgets into a single row or column.

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

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

Use [methodGtk.Box.set_homogeneous] to specify whether or not all children of the GtkBox are forced to get the same amount of space.

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

Use [methodGtk.Box.reorder_child_after] to move a child to a different place in the box.

CSS nodes

GtkBox uses a single CSS node with name box.

Accessibility

GtkBox uses the GTK_ACCESSIBLE_ROLE_GROUP role.

The Box type acts as a reference-counted owner of an underlying GtkBox instance. It provides the methods that can operate on this data type through BoxProtocol conformance. Use Box as a strong reference or owner of a GtkBox instance.

GtkBoxLayout is a layout manager that arranges children in a single row or column.

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

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

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

The BoxLayout type acts as a reference-counted owner of an underlying GtkBoxLayout instance. It provides the methods that can operate on this data type through BoxLayoutProtocol conformance. Use BoxLayout as a strong reference or owner of a GtkBoxLayout instance.

A GtkBuilder reads XML descriptions of a user interface and instantiates the described objects.

To create a GtkBuilder from a user interface description, call [ctorGtk.Builder.new_from_file], [ctorGtk.Builder.new_from_resource] or [ctorGtk.Builder.new_from_string].

In the (unusual) case that you want to add user interface descriptions from multiple sources to the same GtkBuilder you can call [ctorGtk.Builder.new] to get an empty builder and populate it by (multiple) calls to [methodGtk.Builder.add_from_file], [methodGtk.Builder.add_from_resource] or [methodGtk.Builder.add_from_string].

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 [methodGtk.Window.destroy] to get rid of them and all the widgets they contain.

The functions [methodGtk.Builder.get_object] and [methodGtk.Builder.get_objects] 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 [methodGtk.Window.destroy]. Other widgets will either be part of a larger hierarchy constructed by the builder (in which case you should not have to worry about their lifecycle), or without a parent, in which case they have to be added to some container to make use of them. Non-widget objects need to be reffed with g_object_ref() to keep them beyond the lifespan of the builder.

GtkBuilder UI Definitions

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

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 [methodGtk.Builder.set_translation_domain] 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>”. GtkBuilder 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 explicitly with the “type-func” attribute.

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

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_INPUT_HINT_EMOJI|GTK_INPUT_HINT_LOWERCASE”) and colors (in a format understood by [methodGdk.RGBA.parse]).

GVariants can be specified in the format understood by g_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 [methodGtk.Builder.expose_object]. 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, and optionally, “bind-property” and “bind-flags” to specify the source property and source binding flags respectively. Internally, GtkBuilder implements this using GBinding objects. For more information see g_object_bind_property().

Sometimes it is necessary to refer to widgets which have implicitly been constructed by GTK as part of a composite widget, to set properties on them or to add further children (e.g. the content area of a 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.

Signal handlers and function pointers

Signal handlers are set up with the <signal> element. The “name” attribute specifies the name of the signal, and the “handler” attribute specifies the function to connect to the signal. The remaining attributes, “after”, “swapped” and “object”, have the same meaning as the corresponding parameters of the g_signal_connect_object() or g_signal_connect_data() functions. A “last_modification_time” attribute is also allowed, but it does not have a meaning to the builder.

If you rely on GModule support to lookup callbacks in the symbol table, the following details should be noted:

When compiling applications for Windows, you must declare signal callbacks with G_MODULE_EXPORT, or they will not be put in the symbol table. On Linux and Unix, this is not necessary; applications should instead be compiled with the -Wl,–export-dynamic CFLAGS, and linked against gmodule-export-2.0.

A GtkBuilder UI Definition

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

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.

A <template> tag can be used to define a widget class’s components. See the GtkWidget documentation for details.

The Builder type acts as a reference-counted owner of an underlying GtkBuilder instance. It provides the methods that can operate on this data type through BuilderProtocol conformance. Use Builder as a strong reference or owner of a GtkBuilder instance.

A GtkBuilderScope implementation for the C language.

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

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

Note that unless [methodGtk.BuilderCScope.add_callback_symbol] is called for all signal callbacks which are referenced by the loaded XML, this functionality will require that GModule be supported on the platform.

The BuilderCScope type acts as a reference-counted owner of an underlying GtkBuilderCScope instance. It provides the methods that can operate on this data type through BuilderCScopeProtocol conformance. Use BuilderCScope as a strong reference or owner of a GtkBuilderCScope instance.

GtkBuilderListItemFactory is a GtkListItemFactory that creates widgets by instantiating GtkBuilder UI templates.

The templates must be extending GtkListItem, and typically use GtkExpressions to obtain data from the items in the model.

Example:

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

The BuilderListItemFactory type acts as a reference-counted owner of an underlying GtkBuilderListItemFactory instance. It provides the methods that can operate on this data type through BuilderListItemFactoryProtocol conformance. Use BuilderListItemFactory as a strong reference or owner of a GtkBuilderListItemFactory instance.

The GtkButton widget is generally used to trigger a callback function that is called when the button is pressed.

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. When activating a button via the keyboard, the button will temporarily gain the .keyboard-activating style class.

Other style classes that are commonly used with 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 [classGtk.ToggleButton], [classGtk.MenuButton], [classGtk.VolumeButton], [classGtk.LockButton], [classGtk.ColorButton] or [classGtk.FontButton] use style classes such as .toggle, .popup, .scale, .lock, .color on the button node to differentiate themselves from a plain GtkButton.

Accessibility

GtkButton uses the GTK_ACCESSIBLE_ROLE_BUTTON role.

The Button type acts as a reference-counted owner of an underlying GtkButton instance. It provides the methods that can operate on this data type through ButtonProtocol conformance. Use Button as a strong reference or owner of a GtkButton instance.

A variant of GtkClosureExpression using a C closure.

The CClosureExpression type acts as a reference-counted owner of an underlying GtkCClosureExpression instance. It provides the methods that can operate on this data type through CClosureExpressionProtocol conformance. Use CClosureExpression as a strong reference or owner of a GtkCClosureExpression instance.

GtkBuilderScope is an interface to provide language binding support to GtkBuilder.

The goal of GtkBuilderScope is to look up programming-language-specific values for strings that are given in a GtkBuilder UI file.

The primary intended audience is bindings that want to provide deeper integration of GtkBuilder into the language.

A GtkBuilderScope instance may be used with multiple GtkBuilder objects, even at once.

By default, GTK will use its own implementation of GtkBuilderScope for the C language which can be created via [ctorGtk.BuilderCScope.new].

The BuilderScope type acts as an owner of an underlying GtkBuilderScope instance. It provides the methods that can operate on this data type through BuilderScopeProtocol conformance. Use BuilderScope as a strong reference or owner of a GtkBuilderScope instance.

Interface for widgets that can be used for editing cells

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.

The CellEditable type acts as a reference-counted owner of an underlying GtkCellEditable instance. It provides the methods that can operate on this data type through CellEditableProtocol conformance. Use CellEditable as a strong reference or owner of a GtkCellEditable instance.

GtkCalendar is a widget that displays a Gregorian calendar, one month at a time.

A GtkCalendar can be created with [ctorGtk.Calendar.new].

The date that is currently displayed can be altered with [methodGtk.Calendar.select_day].

To place a visual marker on a particular day, use [methodGtk.Calendar.mark_day] and to remove the marker, [methodGtk.Calendar.unmark_day]. Alternative, all marks can be cleared with [methodGtk.Calendar.clear_marks].

The selected date can be retrieved from a GtkCalendar using [methodGtk.Calendar.get_date].

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

CSS nodes

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

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

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

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

Marked day labels get the :selected state assigned.

The Calendar type acts as a reference-counted owner of an underlying GtkCalendar instance. It provides the methods that can operate on this data type through CalendarProtocol conformance. Use Calendar as a strong reference or owner of a GtkCalendar instance.

A GtkShortcutAction that invokes a callback.

The CallbackAction type acts as a reference-counted owner of an underlying GtkCallbackAction instance. It provides the methods that can operate on this data type through CallbackActionProtocol conformance. Use CallbackAction as a strong reference or owner of a GtkCallbackAction instance.

An abstract class for laying out GtkCellRenderers

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, 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_create_context()). 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:

(C Language Example):

GtkTreeIter iter;
int         minimum_width;
int         natural_width;

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

    valid = gtk_tree_model_iter_next (model, &iter);
  }
gtk_cell_area_context_get_preferred_width (context, &minimum_width, &natural_width);

Note that in this example it’s not important to observe the returned minimum and natural width of the area for each row unless the cell-layouting object is actually interested in the widths of individual rows. The overall width is however stored in the accompanying 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 g_timeout_add()) and when the widget is requested its actual width in [vfuncGtk.Widget.measure] 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:

(C Language Example):

static void
foo_get_preferred_width (GtkWidget       *widget,
                         int             *minimum_size,
                         int             *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:

(C Language Example):

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

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

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

    full_minimum_height += minimum_height;
    full_natural_height += natural_height;

    valid = gtk_tree_model_iter_next (model, &iter);
  }

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

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

Rendering Areas

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

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

(C Language Example):

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

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

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

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

    cell_area.y += cell_area.height;

    valid = gtk_tree_model_iter_next (model, &iter);
  }

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

Handling Events and Driving Keyboard Focus

Passing events to the area is as simple as handling events on any normal widget and then passing them to the gtk_cell_area_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 GtkCellAreafocus-changed signal to fire; as well as GtkCellAreaadd-editable in the case that an editable cell was clicked and needs to start editing. You can call gtk_cell_area_stop_editing() 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_CELL_RENDERER_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 [vfuncGtk.Widget.focus] virtual method. The layouting widget is always responsible for knowing where GtkTreeModel rows are rendered inside the widget, so at [vfuncGtk.Widget.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 [vfuncGtk.Widget.focus] virtual method should be implemented:

(C Language Example):

static gboolean
foo_focus (GtkWidget       *widget,
           GtkDirectionType direction)
{
  Foo        *foo  = FOO (widget);
  FooPrivate *priv = foo->priv;
  int         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. 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_install_cell_property() to install cell properties for a cell area class and gtk_cell_area_class_find_cell_property() or gtk_cell_area_class_list_cell_properties() to get information about existing cell properties.

To set the value of a cell property, use gtk_cell_area_cell_set_property(), gtk_cell_area_cell_set() or gtk_cell_area_cell_set_valist(). To obtain the value of a cell property, use gtk_cell_area_cell_get_property(), gtk_cell_area_cell_get() or gtk_cell_area_cell_get_valist().

The CellArea type acts as a reference-counted owner of an underlying GtkCellArea instance. It provides the methods that can operate on this data type through CellAreaProtocol conformance. Use CellArea as a strong reference or owner of a GtkCellArea instance.

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

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_ORIENTATION_VERTICAL orientation, the start is defined as the top of the box and the end is defined as the bottom. In the GTK_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_cell_set_property() or by specifying the “align” argument to gtk_cell_area_box_pack_start() and gtk_cell_area_box_pack_end().

The CellAreaBox type acts as a reference-counted owner of an underlying GtkCellAreaBox instance. It provides the methods that can operate on this data type through CellAreaBoxProtocol conformance. Use CellAreaBox as a strong reference or owner of a GtkCellAreaBox instance.

Stores geometrical information for a series of rows in a GtkCellArea

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_render() and gtk_cell_area_event().

The CellAreaContext type acts as a reference-counted owner of an underlying GtkCellAreaContext instance. It provides the methods that can operate on this data type through CellAreaContextProtocol conformance. Use CellAreaContext as a strong reference or owner of a GtkCellAreaContext instance.

An object for rendering a single cell

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_get_preferred_size(). Finally, the cell is rendered in the correct location using gtk_cell_renderer_snapshot().

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

The CellRenderer type acts as a reference-counted owner of an underlying GtkCellRenderer instance. It provides the methods that can operate on this data type through CellRendererProtocol conformance. Use CellRenderer as a strong reference or owner of a GtkCellRenderer instance.

Renders a keyboard accelerator in a cell

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 CellRendererAccel type acts as a reference-counted owner of an underlying GtkCellRendererAccel instance. It provides the methods that can operate on this data type through CellRendererAccelProtocol conformance. Use CellRendererAccel as a strong reference or owner of a GtkCellRendererAccel instance.

Renders a combobox in a cell

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 GtkCellRendererediting-started`` signal.

The CellRendererCombo type acts as a reference-counted owner of an underlying GtkCellRendererCombo instance. It provides the methods that can operate on this data type through CellRendererComboProtocol conformance. Use CellRendererCombo as a strong reference or owner of a GtkCellRendererCombo instance.

Renders a pixbuf in a cell

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.

The CellRendererPixbuf type acts as a reference-counted owner of an underlying GtkCellRendererPixbuf instance. It provides the methods that can operate on this data type through CellRendererPixbufProtocol conformance. Use CellRendererPixbuf as a strong reference or owner of a GtkCellRendererPixbuf instance.

Renders numbers as progress bars

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 CellRendererProgress type acts as a reference-counted owner of an underlying GtkCellRendererProgress instance. It provides the methods that can operate on this data type through CellRendererProgressProtocol conformance. Use CellRendererProgress as a strong reference or owner of a GtkCellRendererProgress instance.

Renders a spin button in a cell

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 GtkCellRendererediting-started`` signal.

The GtkCellRendererSpin cell renderer was added in GTK 2.10.

The CellRendererSpin type acts as a reference-counted owner of an underlying GtkCellRendererSpin instance. It provides the methods that can operate on this data type through CellRendererSpinProtocol conformance. Use CellRendererSpin as a strong reference or owner of a GtkCellRendererSpin instance.

Renders a spinning animation in a cell

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_add_attribute().

The CellRendererSpinner type acts as a reference-counted owner of an underlying GtkCellRendererSpinner instance. It provides the methods that can operate on this data type through CellRendererSpinnerProtocol conformance. Use CellRendererSpinner as a strong reference or owner of a GtkCellRendererSpinner instance.

Renders text in a cell

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_CELL_RENDERER_MODE_EDITABLE, the GtkCellRendererText allows to edit its text using an entry.

The CellRendererText type acts as a reference-counted owner of an underlying GtkCellRendererText instance. It provides the methods that can operate on this data type through CellRendererTextProtocol conformance. Use CellRendererText as a strong reference or owner of a GtkCellRendererText instance.

Renders a toggle button in a cell

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 GtkCellRendererToggletoggled`` signal.

The CellRendererToggle type acts as a reference-counted owner of an underlying GtkCellRendererToggle instance. It provides the methods that can operate on this data type through CellRendererToggleProtocol conformance. Use CellRendererToggle as a strong reference or owner of a GtkCellRendererToggle instance.

A widget displaying a single row of a GtkTreeModel

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 each other (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.

The CellView type acts as a reference-counted owner of an underlying GtkCellView instance. It provides the methods that can operate on this data type through CellViewProtocol conformance. Use CellView as a strong reference or owner of a GtkCellView instance.

GtkCenterBox arranges three children in a row, keeping the middle child centered as well as possible.

To add children to GtkCenterBox, use [methodGtk.CenterBox.set_start_widget], [methodGtk.CenterBox.set_center_widget] and [methodGtk.CenterBox.set_end_widget].

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

GtkCenterBox as GtkBuildable

The GtkCenterBox implementation of the GtkBuildable interface supports placing children in the 3 positions by specifying “start”, “center” or “end” as the “type” attribute of a <child> element.

CSS nodes

GtkCenterBox uses a single CSS node with the name “box”,

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

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

Accessibility

GtkCenterBox uses the GTK_ACCESSIBLE_ROLE_GROUP role.

The CenterBox type acts as a reference-counted owner of an underlying GtkCenterBox instance. It provides the methods that can operate on this data type through CenterBoxProtocol conformance. Use CenterBox as a strong reference or owner of a GtkCenterBox instance.

GtkCenterLayout is a layout manager that manages up to three children.

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

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

The CenterLayout type acts as a reference-counted owner of an underlying GtkCenterLayout instance. It provides the methods that can operate on this data type through CenterLayoutProtocol conformance. Use CenterLayout as a strong reference or owner of a GtkCenterLayout instance.

An expression using a custom GClosure to compute the value from its parameters.

The ClosureExpression type acts as a reference-counted owner of an underlying GtkClosureExpression instance. It provides the methods that can operate on this data type through ClosureExpressionProtocol conformance. Use ClosureExpression as a strong reference or owner of a GtkClosureExpression instance.

The GtkColorButton allows to open a color chooser dialog to change the color.

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

CSS nodes

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

GtkColorButton has a single CSS node with name colorbutton which contains a button node. To differentiate it from a plain GtkButton, it gets the .color style class.

The ColorButton type acts as a reference-counted owner of an underlying GtkColorButton instance. It provides the methods that can operate on this data type through ColorButtonProtocol conformance. Use ColorButton as a strong reference or owner of a GtkColorButton instance.

A dialog for choosing a color.

GtkColorChooserDialog implements the [ifaceGtk.ColorChooser] interface and does not provide much API of its own.

To create a GtkColorChooserDialog, use [ctorGtk.ColorChooserDialog.new].

To change the initially selected color, use [methodGtk.ColorChooser.set_rgba]. To get the selected color use [methodGtk.ColorChooser.get_rgba].

The ColorChooserDialog type acts as a reference-counted owner of an underlying GtkColorChooserDialog instance. It provides the methods that can operate on this data type through ColorChooserDialogProtocol conformance. Use ColorChooserDialog as a strong reference or owner of a GtkColorChooserDialog instance.

The GtkColorChooserWidget widget lets the user select a color.

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

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

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

To create a GtkColorChooserWidget, use [ctorGtk.ColorChooserWidget.new].

To change the initially selected color, use [methodGtk.ColorChooser.set_rgba]. To get the selected color use [methodGtk.ColorChooser.get_rgba].

The GtkColorChooserWidget is used in the [classGtk.ColorChooserDialog] to provide a dialog for selecting colors.

CSS names

GtkColorChooserWidget has a single CSS node with name colorchooser.

The ColorChooserWidget type acts as a reference-counted owner of an underlying GtkColorChooserWidget instance. It provides the methods that can operate on this data type through ColorChooserWidgetProtocol conformance. Use ColorChooserWidget as a strong reference or owner of a GtkColorChooserWidget instance.

GtkColumnView presents a large dynamic list of items using multiple columns with headers.

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

The [propertyGtk.ColumnView:show-row-separators] and [propertyGtk.ColumnView:show-column-separators] properties offer a simple way to display separators between the rows or columns.

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

The column view supports sorting that can be customized by the user by clicking on column headers. To set this up, the GtkSorter returned by [methodGtk.ColumnView.get_sorter] must be attached to a sort model for the data that the view is showing, and the columns must have sorters attached to them by calling [methodGtk.ColumnViewColumn.set_sorter]. The initial sort order can be set with [methodGtk.ColumnView.sort_by_column].

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

To learn more about the list widget framework, see the overview.

CSS nodes

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

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

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

Accessibility

GtkColumnView uses the GTK_ACCESSIBLE_ROLE_TREE_GRID role, header title widgets are using the GTK_ACCESSIBLE_ROLE_COLUMN_HEADER role. The row widgets are using the GTK_ACCESSIBLE_ROLE_ROW role, and individual cells are using the GTK_ACCESSIBLE_ROLE_GRID_CELL role

The ColumnView type acts as a reference-counted owner of an underlying GtkColumnView instance. It provides the methods that can operate on this data type through ColumnViewProtocol conformance. Use ColumnView as a strong reference or owner of a GtkColumnView instance.

GtkColumnViewColumn represents the columns being added to GtkColumnView.

The main ingredient for a GtkColumnViewColumn is the GtkListItemFactory that tells the columnview how to create cells for this column from items in the model.

Columns have a title, and can optionally have a header menu set with [methodGtk.ColumnViewColumn.set_header_menu].

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

The ColumnViewColumn type acts as a reference-counted owner of an underlying GtkColumnViewColumn instance. It provides the methods that can operate on this data type through ColumnViewColumnProtocol conformance. Use ColumnViewColumn as a strong reference or owner of a GtkColumnViewColumn instance.

A GtkComboBox is a widget that allows the user to choose from a list of valid choices.

The GtkComboBox displays the selected choice; when activated, the GtkComboBox displays a popup which allows the user to make a new choice.

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

To allow the user to enter values not in the model, the [propertyGtk.ComboBox:has-entry] property allows the GtkComboBox to contain a [classGtk.Entry]. This entry can be accessed by calling [methodGtk.ComboBox.get_child] on the combo box.

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

CSS nodes

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

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

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

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

Accessibility

GtkComboBox uses the GTK_ACCESSIBLE_ROLE_COMBO_BOX role.

The ComboBox type acts as a reference-counted owner of an underlying GtkComboBox instance. It provides the methods that can operate on this data type through ComboBoxProtocol conformance. Use ComboBox as a strong reference or owner of a GtkComboBox instance.

A GtkComboBoxText is a simple variant of GtkComboBox for text-only use cases.

GtkComboBoxText hides the model-view complexity of GtkComboBox.

To create a GtkComboBoxText, use [ctorGtk.ComboBoxText.new] or [ctorGtk.ComboBoxText.new_with_entry].

You can add items to a GtkComboBoxText with [methodGtk.ComboBoxText.append_text], [methodGtk.ComboBoxText.insert_text] or [methodGtk.ComboBoxText.prepend_text] and remove options with [methodGtk.ComboBoxText.remove].

If the GtkComboBoxText contains an entry (via the [propertyGtk.ComboBox:has-entry] property), its contents can be retrieved using [methodGtk.ComboBoxText.get_active_text].

You should not call [methodGtk.ComboBox.set_model] or attempt to pack more cells into this combo box via its [ifaceGtk.CellLayout] interface.

GtkComboBoxText as GtkBuildable

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

Here is a UI definition fragment specifying GtkComboBoxText items:

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

CSS nodes

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

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

The ComboBoxText type acts as a reference-counted owner of an underlying GtkComboBoxText instance. It provides the methods that can operate on this data type through ComboBoxTextProtocol conformance. Use ComboBoxText as a strong reference or owner of a GtkComboBoxText instance.

A constant value in a GtkExpression.

The ConstantExpression type acts as a reference-counted owner of an underlying GtkConstantExpression instance. It provides the methods that can operate on this data type through ConstantExpressionProtocol conformance. Use ConstantExpression as a strong reference or owner of a GtkConstantExpression instance.

GtkConstraint describes a constraint between attributes of two widgets, expressed as a linear equation.

The typical equation for a constraint is:

  target.target_attr = source.source_attr × multiplier + constant

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

The source and target, as well as their attributes, of a GtkConstraint instance are immutable after creation.

The Constraint type acts as a reference-counted owner of an underlying GtkConstraint instance. It provides the methods that can operate on this data type through ConstraintProtocol conformance. Use Constraint as a strong reference or owner of a GtkConstraint instance.

A GtkConstraintGuide is an invisible layout element in a GtkConstraintLayout.

The GtkConstraintLayout treats guides like widgets. They can be used as the source or target of a GtkConstraint.

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

Unlike a GtkWidget, a GtkConstraintGuide will not be drawn.

The ConstraintGuide type acts as a reference-counted owner of an underlying GtkConstraintGuide instance. It provides the methods that can operate on this data type through ConstraintGuideProtocol conformance. Use ConstraintGuide as a strong reference or owner of a GtkConstraintGuide instance.

A layout manager using constraints to describe relations between widgets.

GtkConstraintLayout is a layout manager that uses relations between widget attributes, expressed via [classGtk.Constraint] instances, to measure and allocate widgets.

How do constraints work

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

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

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

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

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

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

GtkConstraintLayout as GtkBuildable

GtkConstraintLayout implements the [ifaceGtk.Buildable] interface and has a custom “constraints” element which allows describing constraints in a [classGtk.Builder] UI file.

An example of a UI definition fragment specifying a constraint:

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

The definition above will add two constraints to the GtkConstraintLayout:

• a required constraint between the leading edge of “button” and the leading edge of the widget using the constraint layout, plus 12 pixels
• a strong, constant constraint making the width of “button” greater than, or equal to 250 pixels

The “target” and “target-attribute” attributes are required.

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

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

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

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

There can be “constant” and “multiplier” attributes.

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

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

The “guide” element has the following optional attributes:

• “min-width”, “nat-width”, and “max-width”, describe the minimum, natural, and maximum width of the guide, respectively
• “min-height”, “nat-height”, and “max-height”, describe the minimum, natural, and maximum height of the guide, respectively
• “strength” describes the strength of the constraint on the natural size of the guide; if not specified, the constraint is assumed to have a medium strength
• “name” describes a name for the guide, useful when debugging

Using the Visual Format Language

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

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

For instance:

  [button]-[textField]

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

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

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

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

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

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

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

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

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

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

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

The ConstraintLayout type acts as a reference-counted owner of an underlying GtkConstraintLayout instance. It provides the methods that can operate on this data type through ConstraintLayoutProtocol conformance. Use ConstraintLayout as a strong reference or owner of a GtkConstraintLayout instance.

GtkLayoutChild subclass for children in a GtkConstraintLayout.

The ConstraintLayoutChild type acts as a reference-counted owner of an underlying GtkConstraintLayoutChild instance. It provides the methods that can operate on this data type through ConstraintLayoutChildProtocol conformance. Use ConstraintLayoutChild as a strong reference or owner of a GtkConstraintLayoutChild instance.

GtkCssProvider is an object implementing the GtkStyleProvider interface for CSS.

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

An application can make GTK parse a specific CSS style sheet by calling [methodGtk.CssProvider.load_from_file] or [methodGtk.CssProvider.load_from_resource] and adding the provider with [methodGtk.StyleContext.add_provider] or [funcGtk.StyleContext.add_provider_for_display].

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

To track errors while loading CSS, connect to the [signalGtk.CssProvider::parsing-error] signal.

The CssProvider type acts as a reference-counted owner of an underlying GtkCssProvider instance. It provides the methods that can operate on this data type through CssProviderProtocol conformance. Use CssProvider as a strong reference or owner of a GtkCssProvider instance.

GtkCustomFilter determines whether to include items with a callback.

The CustomFilter type acts as a reference-counted owner of an underlying GtkCustomFilter instance. It provides the methods that can operate on this data type through CustomFilterProtocol conformance. Use CustomFilter as a strong reference or owner of a GtkCustomFilter instance.

GtkCustomLayout uses closures for size negotiation.

A GtkCustomLayoutuses closures matching to the old GtkWidget virtual functions for size negotiation, as a convenience API to ease the porting towards the corresponding `GtkLayoutManager virtual functions.

The CustomLayout type acts as a reference-counted owner of an underlying GtkCustomLayout instance. It provides the methods that can operate on this data type through CustomLayoutProtocol conformance. Use CustomLayout as a strong reference or owner of a GtkCustomLayout instance.

GtkCustomSorter is a GtkSorter implementation that sorts via a callback function.

The CustomSorter type acts as a reference-counted owner of an underlying GtkCustomSorter instance. It provides the methods that can operate on this data type through CustomSorterProtocol conformance. Use CustomSorter as a strong reference or owner of a GtkCustomSorter instance.

The CellRendererClassPrivate type acts as an owner of an underlying GtkCellRendererClassPrivate instance. It provides the methods that can operate on this data type through CellRendererClassPrivateProtocol conformance. Use CellRendererClassPrivate as a strong reference or owner of a GtkCellRendererClassPrivate instance.

Represents a location in a file or other source of data parsed by the CSS engine.

The bytes and line_bytes offsets are meant to be used to programmatically match data. The lines and line_chars offsets can be used for printing the location in a file.

Note that the lines parameter starts from 0 and is increased whenever a CSS line break is encountered. (CSS defines the C character sequences “\r\n”, “\r”, “\n” and “\f” as newlines.) If your document uses different rules for line breaking, you might want run into problems here.

The CssLocation type acts as an owner of an underlying GtkCssLocation instance. It provides the methods that can operate on this data type through CssLocationProtocol conformance. Use CssLocation as a strong reference or owner of a GtkCssLocation instance.

Defines a part of a CSS document.

Because sections are nested into one another, you can use gtk_css_section_get_parent() to get the containing region.

The CssSection type acts as a reference-counted owner of an underlying GtkCssSection instance. It provides the methods that can operate on this data type through CssSectionProtocol conformance. Use CssSection as a strong reference or owner of a GtkCssSection instance.

The CssStyleChange type acts as an owner of an underlying GtkCssStyleChange instance. It provides the methods that can operate on this data type through CssStyleChangeProtocol conformance. Use CssStyleChange as a strong reference or owner of a GtkCssStyleChange instance.

An interface for packing cells

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_set_attributes(), 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_set_cell_data_func() 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 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

(C Language Example):

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

(C Language Example):

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 CellLayout type acts as an owner of an underlying GtkCellLayout instance. It provides the methods that can operate on this data type through CellLayoutProtocol conformance. Use CellLayout as a strong reference or owner of a GtkCellLayout instance.

GtkColorChooser is an interface that is implemented by widgets for choosing colors.

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

In GTK, the main widgets that implement this interface are [classGtk.ColorChooserWidget], [classGtk.ColorChooserDialog] and [classGtk.ColorButton].

The ColorChooser type acts as an owner of an underlying GtkColorChooser instance. It provides the methods that can operate on this data type through ColorChooserProtocol conformance. Use ColorChooser as a strong reference or owner of a GtkColorChooser instance.

The GtkConstraintTarget interface is implemented by objects that can be used as source or target in GtkConstraints.

Besides GtkWidget, it is also implemented by GtkConstraintGuide.

The ConstraintTarget type acts as an owner of an underlying GtkConstraintTarget instance. It provides the methods that can operate on this data type through ConstraintTargetProtocol conformance. Use ConstraintTarget as a strong reference or owner of a GtkConstraintTarget instance.

GtkEditable is an interface for text editing widgets.

Typical examples of editable widgets are [classGtk.Entry] and [classGtk.SpinButton]. It contains functions for generically manipulating an editable widget, a large number of action signals used for key bindings, and several signals that an application can connect to modify the behavior of a widget.

As an example of the latter usage, by connecting the following handler to [signalGtk.Editable::insert-text], an application can convert all entry into a widget into uppercase.

Forcing entry to uppercase.

`include` <ctype.h>

void
insert_text_handler (GtkEditable *editable,
                     const char  *text,
                     int          length,
                     int         *position,
                     gpointer     data)
{
  char *result = g_utf8_strup (text, length);

  g_signal_handlers_block_by_func (editable,
                               (gpointer) insert_text_handler, data);
  gtk_editable_insert_text (editable, result, length, position);
  g_signal_handlers_unblock_by_func (editable,
                                     (gpointer) insert_text_handler, data);

  g_signal_stop_emission_by_name (editable, "insert_text");

  g_free (result);
}

Implementing GtkEditable

The most likely scenario for implementing GtkEditable on your own widget is that you will embed a GtkText inside a complex widget, and want to delegate the editable functionality to that text widget. GtkEditable provides some utility functions to make this easy.

In your class_init function, call [funcGtk.Editable.install_properties], passing the first available property ID:

static void
my_class_init (MyClass *class)
{
  ...
  g_object_class_install_properties (object_class, NUM_PROPERTIES, props);
  gtk_editable_install_properties (object_clas, NUM_PROPERTIES);
  ...
}

In your interface_init function for the GtkEditable interface, provide an implementation for the get_delegate vfunc that returns your text widget:

GtkEditable *
get_editable_delegate (GtkEditable *editable)
{
  return GTK_EDITABLE (MY_WIDGET (editable)->text_widget);
}

static void
my_editable_init (GtkEditableInterface *iface)
{
  iface->get_delegate = get_editable_delegate;
}

You don’t need to provide any other vfuncs. The default implementations work by forwarding to the delegate that the GtkEditableInterface.get_delegate() vfunc returns.

In your instance_init function, create your text widget, and then call [methodGtk.Editable.init_delegate]:

static void
my_widget_init (MyWidget *self)
{
  ...
  self->text_widget = gtk_text_new ();
  gtk_editable_init_delegate (GTK_EDITABLE (self));
  ...
}

In your dispose function, call [methodGtk.Editable.finish_delegate] before destroying your text widget:

static void
my_widget_dispose (GObject *object)
{
  ...
  gtk_editable_finish_delegate (GTK_EDITABLE (self));
  g_clear_pointer (&self->text_widget, gtk_widget_unparent);
  ...
}

Finally, use [funcGtk.Editable.delegate_set_property] in your set_property function (and similar for get_property), to set the editable properties:

  ...
  if (gtk_editable_delegate_set_property (object, prop_id, value, pspec))
    return;

  switch (prop_id)
  ...

It is important to note that if you create a GtkEditable that uses a delegate, the low level [signalGtk.Editable::insert-text] and [signalGtk.Editable::delete-text] signals will be propagated from the “wrapper” editable to the delegate, but they will not be propagated from the delegate to the “wrapper” editable, as they would cause an infinite recursion. If you wish to connect to the [signalGtk.Editable::insert-text] and [signalGtk.Editable::delete-text] signals, you will need to connect to them on the delegate obtained via [methodGtk.Editable.get_delegate].

The Editable type acts as a reference-counted owner of an underlying GtkEditable instance. It provides the methods that can operate on this data type through EditableProtocol conformance. Use Editable as a strong reference or owner of a GtkEditable instance.

GtkDirectoryList is a list model that wraps g_file_enumerate_children_async().

It presents a GListModel and fills it asynchronously with the GFileInfos returned from that function.

Enumeration will start automatically when a the [propertyGtk.DirectoryList:file] property is set.

While the GtkDirectoryList is being filled, the [propertyGtk.DirectoryList:loading] property will be set to true. You can listen to that property if you want to show information like a GtkSpinner or a “Loading…” text.

If loading fails at any point, the [propertyGtk.DirectoryList:error] property will be set to give more indication about the failure.

The GFileInfos returned from a GtkDirectoryList have the “standardfile” attribute set to the GFile they refer to. This way you can get at the file that is referred to in the same way you would via g_file_enumerator_get_child(). This means you do not need access to the GtkDirectoryList, but can access the GFile directly from the GFileInfo when operating with a GtkListView or similar.

The DirectoryList type acts as a reference-counted owner of an underlying GtkDirectoryList instance. It provides the methods that can operate on this data type through DirectoryListProtocol conformance. Use DirectoryList as a strong reference or owner of a GtkDirectoryList instance.

GtkDragIcon is a GtkRoot implementation for drag icons.

A drag icon moves with the pointer during a Drag-and-Drop operation and is destroyed when the drag ends.

To set up a drag icon and associate it with an ongoing drag operation, use [funcGtk.DragIcon.get_for_drag] to get the icon for a drag. You can then use it like any other widget and use [methodGtk.DragIcon.set_child] to set whatever widget should be used for the drag icon.

Keep in mind that drag icons do not allow user input.

The DragIcon type acts as a reference-counted owner of an underlying GtkDragIcon instance. It provides the methods that can operate on this data type through DragIconProtocol conformance. Use DragIcon as a strong reference or owner of a GtkDragIcon instance.

GtkDragSource is an event controller to initiate Drag-And-Drop operations.

GtkDragSource can be set up with the necessary ingredients for a DND operation ahead of time. This includes the source for the data that is being transferred, in the form of a [classGdk.ContentProvider], the desired action, and the icon to use during the drag operation. After setting it up, the drag source must be added to a widget as an event controller, using [methodGtk.Widget.add_controller].

static void
my_widget_init (MyWidget *self)
{
  GtkDragSource *drag_source = gtk_drag_source_new ();

  g_signal_connect (drag_source, "prepare", G_CALLBACK (on_drag_prepare), self);
  g_signal_connect (drag_source, "drag-begin", G_CALLBACK (on_drag_begin), self);

  gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (drag_source));
}

Setting up the content provider and icon ahead of time only makes sense when the data does not change. More commonly, you will want to set them up just in time. To do so, GtkDragSource has [signalGtk.DragSource::prepare] and [signalGtk.DragSource::drag-begin] signals.

The prepare signal is emitted before a drag is started, and can be used to set the content provider and actions that the drag should be started with.

static GdkContentProvider *
on_drag_prepare (GtkDragSource *source,
                 double         x,
                 double         y,
                 MyWidget      *self)
{
  // This widget supports two types of content: GFile objects
  // and GdkPixbuf objects; GTK will handle the serialization
  // of these types automatically
  GFile *file = my_widget_get_file (self);
  GdkPixbuf *pixbuf = my_widget_get_pixbuf (self);

  return gdk_content_provider_new_union ((GdkContentProvider *[2]) {
      gdk_content_provider_new_typed (G_TYPE_FILE, file),
      gdk_content_provider_new_typed (GDK_TYPE_PIXBUF, pixbuf),
    }, 2);
}

The drag-begin signal is emitted after the GdkDrag object has been created, and can be used to set up the drag icon.

static void
on_drag_begin (GtkDragSource *source,
               GtkDrag       *drag,
               MyWidget      *self)
{
  // Set the widget as the drag icon
  GdkPaintable *paintable = gtk_widget_paintable_new (GTK_WIDGET (self));
  gtk_drag_source_set_icon (source, paintable, 0, 0);
  g_object_unref (paintable);
}

During the DND operation, GtkDragSource emits signals that can be used to obtain updates about the status of the operation, but it is not normally necessary to connect to any signals, except for one case: when the supported actions include GDK_ACTION_MOVE, you need to listen for the [signalGtk.DragSource::drag-end] signal and delete the data after it has been transferred.

The DragSource type acts as a reference-counted owner of an underlying GtkDragSource instance. It provides the methods that can operate on this data type through DragSourceProtocol conformance. Use DragSource as a strong reference or owner of a GtkDragSource instance.

GtkDrawingArea is a widget that allows drawing with cairo.

It’s essentially a blank widget; you can draw on it. After creating a drawing area, the application may want to connect to:

• The [signalGtk.Widget::realize] signal to take any necessary actions when the widget is instantiated on a particular display. (Create GDK resources in response to this signal.)

• The [signalGtk.DrawingArea::resize] signal to take any necessary actions when the widget changes size.

• Call [methodGtk.DrawingArea.set_draw_func] to handle redrawing the contents of the widget.

The following code portion demonstrates using a drawing area to display a circle in the normal widget foreground color.

Simple GtkDrawingArea usage

static void
draw_function (GtkDrawingArea *area,
               cairo_t        *cr,
               int             width,
               int             height,
               gpointer        data)
{
  GdkRGBA color;
  GtkStyleContext *context;

  context = gtk_widget_get_style_context (GTK_WIDGET (area));

  cairo_arc (cr,
             width / 2.0, height / 2.0,
             MIN (width, height) / 2.0,
             0, 2 * G_PI);

  gtk_style_context_get_color (context,
                               &color);
  gdk_cairo_set_source_rgba (cr, &color);

  cairo_fill (cr);
}

int
main (int argc, char **argv)
{
  gtk_init ();

  GtkWidget *area = gtk_drawing_area_new ();
  gtk_drawing_area_set_content_width (GTK_DRAWING_AREA (area), 100);
  gtk_drawing_area_set_content_height (GTK_DRAWING_AREA (area), 100);
  gtk_drawing_area_set_draw_func (GTK_DRAWING_AREA (area),
                                  draw_function,
                                  NULL, NULL);
  return 0;
}

The draw function is normally called when a drawing area first comes onscreen, or when it’s covered by another window and then uncovered. You can also force a redraw by adding to the “damage region” of the drawing area’s window using [methodGtk.Widget.queue_draw]. This will cause the drawing area to call the draw function again.

The available routines for drawing are documented on the GDK Drawing Primitives page and the cairo documentation.

To receive mouse events on a drawing area, you will need to use event controllers. To receive keyboard events, you will need to set the “can-focus” property on the drawing area, and you should probably draw some user-visible indication that the drawing area is focused.

If you need more complex control over your widget, you should consider creating your own GtkWidget subclass.

The DrawingArea type acts as a reference-counted owner of an underlying GtkDrawingArea instance. It provides the methods that can operate on this data type through DrawingAreaProtocol conformance. Use DrawingArea as a strong reference or owner of a GtkDrawingArea instance.

GtkDropControllerMotion is an event controller tracking the pointer during Drag-and-Drop operations.

It is modeled after [classGtk.EventControllerMotion] so if you have used that, this should feel really familiar.

This controller is not able to accept drops, use [classGtk.DropTarget] for that purpose.

The DropControllerMotion type acts as a reference-counted owner of an underlying GtkDropControllerMotion instance. It provides the methods that can operate on this data type through DropControllerMotionProtocol conformance. Use DropControllerMotion as a strong reference or owner of a GtkDropControllerMotion instance.

GtkDropDown is a widget that allows the user to choose an item from a list of options.

The GtkDropDown displays the selected choice.

The options are given to GtkDropDown in the form of GListModel and how the individual options are represented is determined by a [classGtk.ListItemFactory]. The default factory displays simple strings.

GtkDropDown knows how to obtain strings from the items in a [classGtk.StringList]; for other models, you have to provide an expression to find the strings via [methodGtk.DropDown.set_expression].

GtkDropDown can optionally allow search in the popup, which is useful if the list of options is long. To enable the search entry, use [methodGtk.DropDown.set_enable_search].

CSS nodes

GtkDropDown has a single CSS node with name dropdown, with the button and popover nodes as children.

Accessibility

GtkDropDown uses the GTK_ACCESSIBLE_ROLE_COMBO_BOX role.

The DropDown type acts as a reference-counted owner of an underlying GtkDropDown instance. It provides the methods that can operate on this data type through DropDownProtocol conformance. Use DropDown as a strong reference or owner of a GtkDropDown instance.

GtkDropTarget is an event controller to receive Drag-and-Drop operations.

The most basic way to use a GtkDropTarget to receive drops on a widget is to create it via [ctorGtk.DropTarget.new], passing in the GType of the data you want to receive and connect to the [signalGtk.DropTarget::drop] signal to receive the data:

static gboolean
on_drop (GtkDropTarget *target,
         const GValue  *value,
         double         x,
         double         y,
         gpointer       data)
{
  MyWidget *self = data;

  // Call the appropriate setter depending on the type of data
  // that we received
  if (G_VALUE_HOLDS (value, G_TYPE_FILE))
    my_widget_set_file (self, g_value_get_object (value));
  else if (G_VALUE_HOLDS (value, GDK_TYPE_PIXBUF))
    my_widget_set_pixbuf (self, g_value_get_object (value));
  else
    return FALSE;

  return TRUE;
}

static void
my_widget_init (MyWidget *self)
{
  GtkDropTarget *target =
    gtk_drop_target_new (G_TYPE_INVALID, GDK_ACTION_COPY);

  // This widget accepts two types of drop types: GFile objects
  // and GdkPixbuf objects
  gtk_drop_target_set_gtypes (target, (GTypes [2]) {
    G_TYPE_FILE,
    GDK_TYPE_PIXBUF,
  }, 2);

  gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (target));
}

GtkDropTarget supports more options, such as:

• rejecting potential drops via the [signalGtk.DropTarget::accept] signal and the [methodGtk.DropTarget.reject] function to let other drop targets handle the drop
• tracking an ongoing drag operation before the drop via the [signalGtk.DropTarget::enter], [signalGtk.DropTarget::motion] and [signalGtk.DropTarget::leave] signals
• configuring how to receive data by setting the [propertyGtk.DropTarget:preload] property and listening for its availability via the [propertyGtk.DropTarget:value] property

However, GtkDropTarget is ultimately modeled in a synchronous way and only supports data transferred via GType. If you want full control over an ongoing drop, the [classGtk.DropTargetAsync] object gives you this ability.

While a pointer is dragged over the drop target’s widget and the drop has not been rejected, that widget will receive the GTK_STATE_FLAG_DROP_ACTIVE state, which can be used to style the widget.

If you are not interested in receiving the drop, but just want to update UI state during a Drag-and-Drop operation (e.g. switching tabs), you can use [classGtk.DropControllerMotion].

The DropTarget type acts as a reference-counted owner of an underlying GtkDropTarget instance. It provides the methods that can operate on this data type through DropTargetProtocol conformance. Use DropTarget as a strong reference or owner of a GtkDropTarget instance.

GtkDropTargetAsync is an event controller to receive Drag-and-Drop operations, asynchronously.

It is the more complete but also more complex method of handling drop operations compared to [classGtk.DropTarget], and you should only use it if GtkDropTarget doesn’t provide all the features you need.

To use a GtkDropTargetAsync to receive drops on a widget, you create a GtkDropTargetAsync object, configure which data formats and actions you support, connect to its signals, and then attach it to the widget with [methodGtk.Widget.add_controller].

During a drag operation, the first signal that a GtkDropTargetAsync emits is [signalGtk.DropTargetAsync::accept], which is meant to determine whether the target is a possible drop site for the ongoing drop. The default handler for the accept signal accepts the drop if it finds a compatible data format and an action that is supported on both sides.

If it is, and the widget becomes a target, you will receive a [signalGtk.DropTargetAsync::drag-enter] signal, followed by [signalGtk.DropTargetAsync::drag-motion] signals as the pointer moves, optionally a [signalGtk.DropTargetAsync::drop] signal when a drop happens, and finally a [signalGtk.DropTargetAsync::drag-leave] signal when the pointer moves off the widget.

The drag-enter and drag-motion handler return a GdkDragAction to update the status of the ongoing operation. The drop handler should decide if it ultimately accepts the drop and if it does, it should initiate the data transfer and finish the operation by calling [methodGdk.Drop.finish].

Between the drag-enter and drag-leave signals the widget is a current drop target, and will receive the GTK_STATE_FLAG_DROP_ACTIVE state, which can be used by themes to style the widget as a drop target.

The DropTargetAsync type acts as a reference-counted owner of an underlying GtkDropTargetAsync instance. It provides the methods that can operate on this data type through DropTargetAsyncProtocol conformance. Use DropTargetAsync as a strong reference or owner of a GtkDropTargetAsync instance.

A GtkEditableLabel is a label that allows users to edit the text by switching to an “edit mode”.

GtkEditableLabel does not have API of its own, but it implements the [ifaceGtk.Editable] interface.

The default bindings for activating the edit mode is to click or press the Enter key. The default bindings for leaving the edit mode are the Enter key (to save the results) or the Escape key (to cancel the editing).

CSS nodes

editablelabel[.editing]
╰── stack
    ├── label
    ╰── text

GtkEditableLabel has a main node with the name editablelabel. When the entry is in editing mode, it gets the .editing style class.

For all the subnodes added to the text node in various situations, see [classGtk.Text].

The EditableLabel type acts as a reference-counted owner of an underlying GtkEditableLabel instance. It provides the methods that can operate on this data type through EditableLabelProtocol conformance. Use EditableLabel as a strong reference or owner of a GtkEditableLabel instance.

An opaque structure representing a watched GtkExpression.

The contents of GtkExpressionWatch should only be accessed through the provided API.

The ExpressionWatch type acts as a reference-counted owner of an underlying GtkExpressionWatch instance. It provides the methods that can operate on this data type through ExpressionWatchProtocol conformance. Use ExpressionWatch as a strong reference or owner of a GtkExpressionWatch instance.

The GtkEmojiChooser is used by text widgets such as GtkEntry or GtkTextView to let users insert Emoji characters.

GtkEmojiChooser emits the [signalGtk.EmojiChooser::emoji-picked] signal when an Emoji is selected.

CSS nodes

popover
├── box.emoji-searchbar
│   ╰── entry.search
╰── box.emoji-toolbar
    ├── button.image-button.emoji-section
    ├── ...
    ╰── button.image-button.emoji-section

Every GtkEmojiChooser consists of a main node called popover. The contents of the popover are largely implementation defined and supposed to inherit general styles. The top searchbar used to search emoji and gets the .emoji-searchbar style class itself. The bottom toolbar used to switch between different emoji categories consists of buttons with the .emoji-section style class and gets the .emoji-toolbar style class itself.

The EmojiChooser type acts as a reference-counted owner of an underlying GtkEmojiChooser instance. It provides the methods that can operate on this data type through EmojiChooserProtocol conformance. Use EmojiChooser as a strong reference or owner of a GtkEmojiChooser instance.

GtkEntry is a single line text entry widget.

A fairly large set of key bindings are supported by default. If the entered text is longer than the allocation of the widget, the widget will scroll so that the cursor position is visible.

When using an entry for passwords and other sensitive information, it can be put into “password mode” using [methodGtk.Entry.set_visibility]. In this mode, entered text is displayed using a “invisible” character. By default, GTK picks the best invisible character that is available in the current font, but it can be changed with [methodGtk.Entry.set_invisible_char].

GtkEntry has the ability to display progress or activity information behind the text. To make an entry display such information, use [methodGtk.Entry.set_progress_fraction] or [methodGtk.Entry.set_progress_pulse_step].

Additionally, GtkEntry can show icons at either side of the entry. These icons can be activatable by clicking, can be set up as drag source and can have tooltips. To add an icon, use [methodGtk.Entry.set_icon_from_gicon] or one of the various other functions that set an icon from an icon name or a paintable. To trigger an action when the user clicks an icon, connect to the [signalGtk.Entry::icon-press] signal. To allow DND operations from an icon, use [methodGtk.Entry.set_icon_drag_source]. To set a tooltip on an icon, use [methodGtk.Entry.set_icon_tooltip_text] or the corresponding function for markup.

Note that functionality or information that is only available by clicking on an icon in an entry may not be accessible at all to users which are not able to use a mouse or other pointing device. It is therefore recommended that any such functionality should also be available by other means, e.g. via the context menu of the entry.

CSS nodes

entry[.flat][.warning][.error]
├── text[.readonly]
├── image.left
├── image.right
╰── [progress[.pulse]]

GtkEntry has a main node with the name entry. Depending on the properties of the entry, the style classes .read-only and .flat may appear. The style classes .warning and .error may also be used with entries.

When the entry shows icons, it adds subnodes with the name image and the style class .left or .right, depending on where the icon appears.

When the entry shows progress, it adds a subnode with the name progress. The node has the style class .pulse when the shown progress is pulsing.

For all the subnodes added to the text node in various situations, see [classGtk.Text].

GtkEntry as GtkBuildable

The GtkEntry implementation of the GtkBuildable interface supports a custom <attributes> element, which supports any number of <attribute> elements. The <attribute> element has attributes named “name“, “value“, “start“ and “end“ and allows you to specify PangoAttribute values for this label.

An example of a UI definition fragment specifying Pango attributes:

<object class="GtkEntry">
  <attributes>
    <attribute name="weight" value="PANGO_WEIGHT_BOLD"/>
    <attribute name="background" value="red" start="5" end="10"/>
  </attributes>
</object>

The start and end attributes specify the range of characters to which the Pango attribute applies. If start and end are not specified, the attribute is applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup embedded in the translatable content instead.

Accessibility

GtkEntry uses the GTK_ACCESSIBLE_ROLE_TEXT_BOX role.

The Entry type acts as a reference-counted owner of an underlying GtkEntry instance. It provides the methods that can operate on this data type through EntryProtocol conformance. Use Entry as a strong reference or owner of a GtkEntry instance.

A GtkEntryBuffer hold the text displayed in a GtkText widget.

A single GtkEntryBuffer object can be shared by multiple widgets which will then share the same text content, but not the cursor position, visibility attributes, icon etc.

GtkEntryBuffer may be derived from. Such a derived class might allow text to be stored in an alternate location, such as non-pageable memory, useful in the case of important passwords. Or a derived class could integrate with an application’s concept of undo/redo.

The EntryBuffer type acts as a reference-counted owner of an underlying GtkEntryBuffer instance. It provides the methods that can operate on this data type through EntryBufferProtocol conformance. Use EntryBuffer as a strong reference or owner of a GtkEntryBuffer instance.

GtkEntryCompletion is an auxiliary object to provide completion functionality for GtkEntry.

It implements the [ifaceGtk.CellLayout] interface, to allow the user to add extra cells to the GtkTreeView with completion matches.

“Completion functionality” means that when the user modifies the text in the entry, GtkEntryCompletion checks which rows in the model match the current content of the entry, and displays a list of matches. By default, the matching is done by comparing the entry text case-insensitively against the text column of the model (see [methodGtk.EntryCompletion.set_text_column]), but this can be overridden with a custom match function (see [methodGtk.EntryCompletion.set_match_func]).

When the user selects a completion, the content of the entry is updated. By default, the content of the entry is replaced by the text column of the model, but this can be overridden by connecting to the [signalGtk.EntryCompletion::match-selected] signal and updating the entry in the signal handler. Note that you should return true from the signal handler to suppress the default behaviour.

To add completion functionality to an entry, use [methodGtk.Entry.set_completion].

GtkEntryCompletion uses a [classGtk.TreeModelFilter] model to represent the subset of the entire model that is currently matching. While the GtkEntryCompletion signals [signalGtk.EntryCompletion::match-selected] and [signalGtk.EntryCompletion::cursor-on-match] take the original model and an iter pointing to that model as arguments, other callbacks and signals (such as GtkCellLayoutDataFunc or [signalGtk.CellArea::apply-attributes)] will generally take the filter model as argument. As long as you are only calling [methodGtk.TreeModel.get], this will make no difference to you. If for some reason, you need the original model, use [methodGtk.TreeModelFilter.get_model]. Don’t forget to use [methodGtk.TreeModelFilter.convert_iter_to_child_iter] to obtain a matching iter.

The EntryCompletion type acts as a reference-counted owner of an underlying GtkEntryCompletion instance. It provides the methods that can operate on this data type through EntryCompletionProtocol conformance. Use EntryCompletion as a strong reference or owner of a GtkEntryCompletion instance.