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

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

While GtkApplication works fine with plain GtkWindows, it is recommended to use it together with GtkApplicationWindow.

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

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

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

It is also possible to provide the menus manually using gtk_application_set_app_menu() and gtk_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 gtk_icon_theme_add_resource_path() for more information.

If there is a resource located at “gtk/help-overlay.ui” which defines a GtkShortcutsWindow with ID “help_overlay” then GtkApplication associates an instance of this shortcuts window with each GtkApplicationWindow and sets up keyboard accelerators (Control-F1 and Control-?) to open it. To create a menu item that displays the shortcuts window, associate the item with the action win.show-help-overlay.

A simple application ##

A simple example

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

An application can block various ways to end the session with the gtk_application_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.

Dialog boxes are a convenient way to prompt the user for a small amount of input, e.g. to display a message, ask a question, or anything else that does not require extensive effort on the user’s part.

GTK+ treats a dialog as a window split vertically. The top section is a GtkVBox, and is where widgets such as a GtkLabel or a GtkEntry should be packed. The bottom area is known as the “action area”. This is generally used for packing buttons into the dialog which may perform functions such as cancel, ok, or apply.

GtkDialog boxes are created with a call to gtk_dialog_new() or gtk_dialog_new_with_buttons(). gtk_dialog_new_with_buttons() is recommended; it allows you to set the dialog title, some convenient flags, and add simple buttons.

If “dialog” is a newly created dialog, the two primary areas of the window can be accessed through gtk_dialog_get_content_area() and gtk_dialog_get_action_area(), as can be seen from the example below.

A “modal” dialog (that is, one which freezes the rest of the application from user input), can be created by calling gtk_window_set_modal() on the dialog. Use the GTK_WINDOW() macro to cast the widget returned from gtk_dialog_new() into a GtkWindow. When using gtk_dialog_new_with_buttons() you can also pass the GTK_DIALOG_MODAL flag to make a dialog modal.

If you add buttons to GtkDialog using gtk_dialog_new_with_buttons(), gtk_dialog_add_button(), gtk_dialog_add_buttons(), or gtk_dialog_add_action_widget(), clicking the button will emit a signal called GtkDialog::response 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 GtkResponseType enumeration (these all have values less than zero). If a dialog receives a delete event, the GtkDialog::response signal will be emitted with a response ID of GTK_RESPONSE_DELETE_EVENT.

If you want to block waiting for a dialog to return before returning control flow to your code, you can call gtk_dialog_run(). This function enters a recursive main loop and waits for the user to respond to the dialog, returning the response ID corresponding to the button the user clicked.

For the simple dialog in the following example, in reality you’d probably use GtkMessageDialog to save yourself 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: (C Language Example):

// Function to open a dialog box with a message
void
quick_message (GtkWindow *parent, gchar *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_widget_destroy),
                           dialog);

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

 gtk_container_add (GTK_CONTAINER (content_area), label);
 gtk_widget_show_all (dialog);
}

GtkDialog as GtkBuildable

The GtkDialog implementation of the GtkBuildable interface exposes the vbox and action_area as internal children with the names “vbox” and “action_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">
      <property name="can-default">True</property>
    </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>

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 box suitable for use with “File/Open” or “File/Save as” commands. This widget works by putting a GtkFileChooserWidget inside a GtkDialog. It exposes the GtkFileChooser interface, so you can use all of the GtkFileChooser functions on the file chooser dialog as well as those for GtkDialog.

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

If you want to integrate well with the platform you should use the GtkFileChooserNative 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:

GtkWidget *dialog;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
gint res;

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

res = gtk_dialog_run (GTK_DIALOG (dialog));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;
    GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);
    filename = gtk_file_chooser_get_filename (chooser);
    open_file (filename);
    g_free (filename);
  }

gtk_widget_destroy (dialog);

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

GtkWidget *dialog;
GtkFileChooser *chooser;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
gint res;

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

gtk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE);

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

res = gtk_dialog_run (GTK_DIALOG (dialog));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;

    filename = gtk_file_chooser_get_filename (chooser);
    save_to_file (filename);
    g_free (filename);
  }

gtk_widget_destroy (dialog);

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

• To save a file under a different name. Use GTK_FILE_CHOOSER_ACTION_SAVE, and set the existing filename with gtk_file_chooser_set_filename().

• To choose a folder instead of a file. Use GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.

Note that old versions of the file chooser’s documentation suggested using gtk_file_chooser_set_current_folder() in various situations, with the intention of letting the application suggest a reasonable default folder. This is no longer considered to be a good policy, as now the file chooser is able to make good suggestions on its own. In general, you should only cause the file chooser to show a specific folder when it is appropriate to use gtk_file_chooser_set_filename(), i.e. when you are doing a Save As command and you already have a file saved somewhere.

Response Codes ##

GtkFileChooserDialog inherits from GtkDialog, 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 gtk_file_chooser_dialog_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 stock response identifiers from GtkResponseType. For most dialog boxes you can use your own custom response codes rather than the ones in GtkResponseType, 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 stock 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 box 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 certain 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 GtkNativeDialog functions.

Typical usage ##

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

GtkFileChooserNative *native;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
gint res;

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

res = gtk_native_dialog_run (GTK_NATIVE_DIALOG (native));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;
    GtkFileChooser *chooser = GTK_FILE_CHOOSER (native);
    filename = gtk_file_chooser_get_filename (chooser);
    open_file (filename);
    g_free (filename);
  }

g_object_unref (native);

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

GtkFileChooserNative *native;
GtkFileChooser *chooser;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
gint res;

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

gtk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE);

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

res = gtk_native_dialog_run (GTK_NATIVE_DIALOG (native));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;

    filename = gtk_file_chooser_get_filename (chooser);
    save_to_file (filename);
    g_free (filename);
  }

g_object_unref (native);

For more information on how to best set up a file dialog, see GtkFileChooserDialog.

Response Codes ##

GtkFileChooserNative inherits from GtkNativeDialog, 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 GtkFileChooser API that are not possible to use with GtkFileChooserNative, as such use would prohibit the use of a native dialog.

There is no support for the signals that are emitted when the user navigates in the dialog, including:

• GtkFileChooser::current-folder-changed
• GtkFileChooser::selection-changed
• GtkFileChooser::file-activated
• GtkFileChooser::confirm-overwrite

You can also not use the methods that directly control user navigation:

• gtk_file_chooser_unselect_filename()
• gtk_file_chooser_select_all()
• gtk_file_chooser_unselect_all()

If you need any of the above you will have to use GtkFileChooserDialog directly.

No operations that change the 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 GtkFileChooserDialog does, but there are some things it does not handle:

• Extra widgets added with gtk_file_chooser_set_extra_widget().

• Use of custom previews by connecting to GtkFileChooser::update-preview.

• Any GtkFileFilter added using a mimetype or custom filter.

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. In this situation, the following things are not supported and will be silently ignored:

• Extra widgets added with gtk_file_chooser_set_extra_widget().

• Use of custom previews by connecting to GtkFileChooser::update-preview.

• Any GtkFileFilter added with a custom filter.

macOS details ##

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

• Extra widgets added with gtk_file_chooser_set_extra_widget(), unless the widget is an instance of GtkLabel, in which case the label text will be used to set the NSSavePanel message instance property.

• Use of custom previews by connecting to GtkFileChooser::update-preview.

• Any GtkFileFilter added with a custom filter.

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

The GtkAboutDialog offers a simple way to display information about a program like its logo, name, copyright, website and license. It is also possible to give credits to the authors, documenters, translators and artists who have worked on the program. An about dialog is typically opened when the user selects the About option from the Help menu. All parts of the dialog are optional.

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

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

To make constructing a GtkAboutDialog as convenient as possible, you can use the function gtk_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: (C Language Example):

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

It is also possible to show a GtkAboutDialog like any other GtkDialog, e.g. using gtk_dialog_run(). In this case, you might need to know that the “Close” button returns the GTK_RESPONSE_CANCEL response id.

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.

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

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

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

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

The accelerator key to display is typically not set explicitly (although it can be, with gtk_accel_label_set_accel()). Instead, the GtkAccelLabel displays the accelerators which have been added to a particular widget. This widget is set by calling gtk_accel_label_set_accel_widget().

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

Note that creating a GtkMenuItem with gtk_menu_item_new_with_label() (or one of the similar functions for GtkCheckMenuItem and GtkRadioMenuItem) automatically adds a GtkAccelLabel to the GtkMenuItem and calls gtk_accel_label_set_accel_widget() to set it up for you.

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

Creating a simple menu item with an accelerator key.

(C Language Example):

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

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

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

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

CSS nodes

(plain Language Example):

label
╰── accelerator

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

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

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

An accelerator is uniquely defined by:

• accelerator path
• accelerator key
• accelerator modifiers

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

All accelerators are stored inside one global GtkAccelMap that can be obtained using gtk_accel_map_get(). See Monitoring changes for additional details.

Manipulating accelerators

New accelerators can be added using gtk_accel_map_add_entry(). To search for specific accelerator, use gtk_accel_map_lookup_entry(). Modifications of existing accelerators should be done using gtk_accel_map_change_entry().

In order to avoid having some accelerators changed, they can be locked using gtk_accel_map_lock_path(). Unlocking is done using gtk_accel_map_unlock_path().

Saving and loading accelerator maps

Accelerator maps can be saved to and loaded from some external resource. For simple saving and loading from file, gtk_accel_map_save() and gtk_accel_map_load() are provided. Saving and loading can also be done by providing file descriptor to gtk_accel_map_save_fd() and gtk_accel_map_load_fd().

Monitoring changes

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

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

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

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

The Accessible type acts as a reference-counted 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.

> In GTK+ 3.10, GtkAction has been deprecated. Use GAction > instead, and associate actions with GtkActionable widgets. Use > GMenuModel for creating menus with gtk_menu_new_from_model().

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

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

• a name (not translated, for path lookup)

• a label (translated, for display)

• an accelerator

• whether label indicates a stock id

• a tooltip (optional, translated)

• a toolbar label (optional, shorter than label)

The action will also have some state information:

• visible (shown/hidden)

• sensitive (enabled/disabled)

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

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

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

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

GtkActionBar has a single CSS node with name actionbar.

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.

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

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

Accelerators ##

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

GtkActionGroup as GtkBuildable #

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

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

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

A GtkDialog UI definition fragment.

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

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

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

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

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

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

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

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

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

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

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

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

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

It is possible to add custom items to the list, using gtk_app_chooser_button_append_custom_item(). These items cause the GtkAppChooserButton::custom-item-activated signal to be emitted when they are selected.

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

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 gtk_app_chooser_dialog_get_widget() and call its methods if the generic GtkAppChooser interface is not sufficient for your needs.

To set the heading that is shown above the GtkAppChooserWidget, use gtk_app_chooser_dialog_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 GtkAppChooserDialog. Most applications only need to use the latter; but you can use this widget as part of a larger widget if you have special needs.

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

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

CSS nodes

GtkAppChooserWidget has a single CSS node with name appchooser.

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 offers some extra functionality for better integration with GtkApplication features. Notably, it can handle both the application menu as well as the menubar. See gtk_application_set_app_menu() and gtk_application_set_menubar().

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

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

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

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

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

A GtkApplicationWindow with a menubar

(C Language Example):

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

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

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

// ...

GtkWidget *window = gtk_application_window_new (app);

Handling fallback yourself

A simple example

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

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

The following attributes are used when constructing menu items:

• “label”: a user-visible string to display
• “action”: the prefixed name of the action to trigger
• “target”: the parameter to use when activating the action
• “icon” and “verb-icon”: names of icons that may be displayed
• “submenu-action”: name of an action that may be used to determine if a submenu can be opened
• “hidden-when”: a string used to determine when the item will be hidden. Possible values include “action-disabled”, “action-missing”, “macos-menubar”.

The following attributes are used when constructing sections:

• “label”: a user-visible string to use as section heading
• “display-hint”: a string used to determine special formatting for the section. Possible values include “horizontal-buttons”.
• “text-direction”: a string used to determine the GtkTextDirection to use when “display-hint” is set to “horizontal-buttons”. Possible values include “rtl”, “ltr”, and “none”.

The following attributes are used when constructing submenus:

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

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.

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

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

Arrows are created with a call to gtk_arrow_new(). The direction or style of an arrow can be changed after creation by using gtk_arrow_set().

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

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

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

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

CSS nodes

GtkAspectFrame uses a CSS node with name frame.

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.

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

The design of GtkAssistant is that it controls what buttons to show and to make sensitive, based on what it knows about the page sequence and the type of each page, in addition to state information like the page completion and committed status.

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

GtkAssistant as GtkBuildable

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

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

CSS nodes

GtkAssistant has a single CSS node with the name assistant.

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

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

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

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

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

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

GtkActionEntry structs are used with gtk_action_group_add_actions() to construct actions.

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

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

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

The action will be looked up in action groups that are found among the widgets ancestors. Most commonly, these will be the actions with the “win.” or “app.” prefix that are associated with the GtkApplicationWindow or GtkApplication, but other action groups that are added with gtk_widget_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.

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

Implementing GtkActivatable

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

A class fragment implementing GtkActivatable

(C Language Example):

enum {
...

PROP_ACTIVATABLE_RELATED_ACTION,
PROP_ACTIVATABLE_USE_ACTION_APPEARANCE
}

struct _FooBarPrivate
{

  ...

  GtkAction      *action;
  gboolean        use_action_appearance;
};

...

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


static void
foo_bar_class_init (FooBarClass *klass)
{

  ...

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

  ...
}


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

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

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

  ...

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

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

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

  switch (prop_id)
    {

      ...

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

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

  switch (prop_id)
    {

      ...

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


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

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

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

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

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

  gtk_activatable_do_set_related_action (GTK_ACTIVATABLE (bar), action);

  priv->action = action;
}

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

  if (!action)
    return;

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

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

  ...

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

      ...

    }
}

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

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

  ...

  if (!priv->use_action_appearance)
    return;

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

  ...
}

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

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

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

To obtain the application that has been selected in a GtkAppChooser, use gtk_app_chooser_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 GtkBuilder UI descriptions. The interface includes methods for setting names and properties of objects, parsing custom tags and constructing child objects.

The GtkBuildable interface is implemented by all widgets and many of the non-widget objects that are provided by GTK+. The main user of this interface is GtkBuilder. There should be very little need for applications to call any of these functions directly.

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

The 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 GtkBindingArg holds the data associated with an argument for a key binding signal emission as stored in GtkBindingSignal.

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

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

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

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

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

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

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

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

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.

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

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

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

Use repeated calls to gtk_box_pack_start() to pack widgets into a GtkBox from start to end. Use gtk_box_pack_end() to add widgets from end to start. You may intersperse these calls and add widgets from both ends of the same GtkBox.

Because GtkBox is a GtkContainer, you may also use gtk_container_add() to insert widgets into the box, and they will be packed with the default values for expand and fill child properties. Use gtk_container_remove() to remove widgets from the GtkBox.

Use gtk_box_set_homogeneous() to specify whether or not all children of the GtkBox are forced to get the same amount of space.

Use gtk_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, while padding added by gtk_box_pack_start() or gtk_box_pack_end() is added on either side of the widget it belongs to.

Use gtk_box_reorder_child() to move a GtkBox child to a different place in the box.

Use gtk_box_set_child_packing() to reset the expand, fill and padding child properties. Use gtk_box_query_child_packing() to query these fields.

CSS nodes

GtkBox uses a single CSS node with name box.

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

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.

A GtkBuilder is an auxiliary object that reads textual descriptions of a user interface and instantiates the described objects. To create a GtkBuilder from a user interface description, call gtk_builder_new_from_file(), gtk_builder_new_from_resource() or gtk_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 gtk_builder_new() to get an empty builder and populate it by (multiple) calls to gtk_builder_add_from_file(), gtk_builder_add_from_resource() or gtk_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 gtk_widget_destroy() to get rid of them and all the widgets they contain.

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

The function gtk_builder_connect_signals() and variants thereof can be used to connect handlers to the named signals in the description.

GtkBuilder UI Definitions #

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

RELAX NG Compact Syntax

The toplevel element is <interface>. It optionally takes a “domain” attribute, which will make the builder look for translated strings using dgettext() in the domain specified. This can also be done by calling gtk_builder_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>”. The builder will error out if the version requirements are not met.

Typically, the specific kind of object represented by an <object> element is specified by the “class” attribute. If the type has not been loaded yet, GTK+ tries to find the get_type() function from the class name by applying heuristics. This works in most cases, but if necessary, it is possible to specify the name of the get_type() function explictly with the “type-func” attribute. As a special case, GtkBuilder allows to use an object that has been constructed by a GtkUIManager in another part of the UI definition by specifying the id of the GtkUIManager in the “constructor” attribute and the name of the object in the “id” attribute.

Objects may be given a name with the “id” attribute, which allows the application to retrieve them from the builder with gtk_builder_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 ___ (3 underscores) for its own purposes.

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

GtkBuilder can parse textual representations for the most common property types: characters, strings, integers, floating-point numbers, booleans (strings like “TRUE”, “t”, “yes”, “y”, “1” are interpreted as true, strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted as false), enumerations (can be specified by their name, nick or integer value), flags (can be specified by their name, nick, integer value, optionally combined with “|”, e.g. “GTK_VISIBLE|GTK_REALIZED”) and colors (in a format understood by gdk_rgba_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 gtk_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, “bind-property” to specify the source property and optionally “bind-flags” to specify the binding flags. Internally builder implements this using GBinding objects. For more information see g_object_bind_property()

Signal handlers are set up with the <signal> element. The “name” attribute specifies the name of the signal, and the “handler” attribute specifies the function to connect to the signal. By default, GTK+ tries to find the handler using g_module_symbol(), but this can be changed by passing a custom GtkBuilderConnectFunc to gtk_builder_connect_signals_full(). 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.

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

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

A GtkBuilder UI Definition

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

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

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

Additionally, since 3.10 a special <template> tag has been added to the format allowing one to define a widget class’s components. See the GtkWidget documentation 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.

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

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

CSS nodes

GtkButton has a single CSS node with name button. The node will get the style classes .image-button or .text-button, if the content is just an image or label, respectively. It may also receive the .flat style class.

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

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

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.

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

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

GtkCalendar is a widget that displays a Gregorian calendar, one month at a time. It can be created with gtk_calendar_new().

The month and year currently displayed can be altered with gtk_calendar_select_month(). The exact day can be selected from the displayed month using gtk_calendar_select_day().

To place a visual marker on a particular day, use gtk_calendar_mark_day() and to remove the marker, gtk_calendar_unmark_day(). Alternative, all marks can be cleared with gtk_calendar_clear_marks().

The way in which the calendar itself is displayed can be altered using gtk_calendar_set_display_options().

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

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.

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

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;
gint        minimum_width;
gint        natural_width;

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

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

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

This can be useful since GtkCellLayout widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The GtkCellLayout widget in that case would calculate the required width of the rows in an idle or timeout source (see g_timeout_add()) and when the widget is requested its actual width in GtkWidgetClass.get_preferred_width() it can simply consult the width accumulated so far in the GtkCellAreaContext object.

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

(C Language Example):

static void
foo_get_preferred_width (GtkWidget       *widget,
                         gint            *minimum_size,
                         gint            *natural_size)
{
  Foo        *foo  = FOO (widget);
  FooPrivate *priv = foo->priv;

  foo_ensure_at_least_one_handfull_of_rows_have_been_requested (foo);

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

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

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

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

(C Language Example):

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

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

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

    full_minimum_height += minimum_height;
    full_natural_height += natural_height;

    valid = gtk_tree_model_iter_next (model, &iter);
  }

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

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

Rendering Areas

Once area sizes have been aquired at least for the rows in the visible area of the layouting widget they can be rendered at GtkWidgetClass.draw() time.

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

(C Language Example):

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

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

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

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

    cell_area.y += cell_area.height;

    valid = gtk_tree_model_iter_next (model, &iter);
  }

Note that the cached height in this example really depends on how the layouting widget works. The layouting widget might decide to give every row its minimum or natural height or, if the model content is expected to fit inside the layouting widget without scrolling, it would make sense to calculate the allocation for each row at GtkWidget::size-allocate time using gtk_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 GtkCellArea::focus-changed signal to fire; as well as GtkCellArea::add-editable in the case that an editable cell was clicked and needs to start editing. You can call gtk_cell_area_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 GtkWidgetClass.focus() virtual method. The layouting widget is always responsible for knowing where GtkTreeModel rows are rendered inside the widget, so at GtkWidgetClass.focus() time the layouting widget should use the GtkCellArea methods to navigate focus inside the area and then observe the GtkDirectionType to pass the focus to adjacent rows and areas.

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

(C Language Example):

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

  focus_row = priv->focus_row;

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

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

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

Note that the layouting widget is responsible for matching the GtkDirectionType values to the way it lays out its cells.

Cell Properties

The GtkCellArea introduces cell properties for GtkCellRenderers in very much the same way that GtkContainer introduces child properties for GtkWidgets. This provides some general interfaces for defining the relationship cell areas have with their cells. For instance in a GtkCellAreaBox a cell might “expand” and receive extra space when the area is allocated more than its full natural request, or a cell might be configured to “align” with adjacent rows which were requested and rendered with the same GtkCellAreaContext.

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

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.

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.

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

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

Beyond merely rendering a cell, cell renderers can optionally provide active user interface elements. A cell renderer can be “activatable” like GtkCellRendererToggle, which toggles when it gets activated by a mouse click, or it can be “editable” like GtkCellRendererText, which allows the user to edit the text using a widget implementing the GtkCellEditable interface, e.g. GtkEntry. To make a cell renderer activatable or editable, you have to implement the GtkCellRendererClass.activate or GtkCellRendererClass.start_editing virtual functions, respectively.

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

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.

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

The GtkCellRendererAccel cell renderer was added in GTK+ 2.10.

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.

GtkCellRendererCombo renders text in a cell like GtkCellRendererText from which it is derived. But while GtkCellRendererText offers a simple entry to edit the text, GtkCellRendererCombo offers a GtkComboBox widget to edit the text. The values to display in the combo box are taken from the tree model specified in the GtkCellRendererCombo:model property.

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

The GtkCellRendererCombo cell renderer was added in GTK+ 2.6.

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.

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.

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

The GtkCellRendererProgress cell renderer was added in GTK+ 2.6.

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.

GtkCellRendererSpin renders text in a cell like GtkCellRendererText from which it is derived. But while GtkCellRendererText offers a simple entry to edit the text, GtkCellRendererSpin offers a GtkSpinButton widget. Of course, that means that the text has to be parseable as a floating point number.

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

The GtkCellRendererSpin cell renderer was added in GTK+ 2.10.

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.

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.

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.

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

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 GtkCellView displays a single row of a GtkTreeModel using a GtkCellArea and GtkCellAreaContext. A GtkCellAreaContext can be provided to the GtkCellView at construction time in order to keep the cellview in context of a group of cell views, this ensures that the renderers displayed will be properly aligned with eachother (like the aligned cells in the menus of GtkComboBox).

GtkCellView is GtkOrientable in order to decide in which orientation the underlying GtkCellAreaContext should be allocated. Taking the GtkComboBox menu as an example, cellviews should be oriented horizontally if the menus are listed top-to-bottom and thus all share the same width but may have separate individual heights (left-to-right menus should be allocated vertically since they all share the same height but may have variable widths).

CSS nodes

GtkCellView has a single CSS node with name cellview.

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.

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

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

CSS nodes

(plain Language Example):

checkbutton
├── check
╰── <child>

A GtkCheckButton with indicator (see gtk_toggle_button_set_mode()) has a main CSS node with name checkbutton and a subnode with name check.

(plain Language Example):

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

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

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.

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

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

CSS nodes

(plain Language Example):

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

GtkCheckMenuItem has a main CSS node with name menuitem, and a subnode with name check, which gets the .left or .right style class.

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

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

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

The GtkColorButton is a button which displays the currently selected color and allows to open a color selection dialog to change the color. It is suitable widget for selecting a color in a preference dialog.

CSS nodes

GtkColorButton has a single CSS node with name button. 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.

The GtkColorChooserDialog widget is a dialog for choosing a color. It implements the GtkColorChooser interface.

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 change the initially selected color, use gtk_color_chooser_set_rgba(). To get the selected color use gtk_color_chooser_get_rgba().

The GtkColorChooserWidget is used in the GtkColorChooserDialog 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.

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

The ColorSelectionDialog type acts as a reference-counted owner of an underlying GtkColorSelectionDialog instance. It provides the methods that can operate on this data type through ColorSelectionDialogProtocol conformance. Use ColorSelectionDialog as a strong reference or owner of a GtkColorSelectionDialog 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 style in which the selected value is displayed, and the style of the popup is determined by the current theme. It may be similar to a Windows-style combo box.

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 GtkCellLayout 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 “has-entry” property allows the GtkComboBox to contain a GtkEntry. This entry can be accessed by calling gtk_bin_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, GtkComboBoxText offers a simple alternative. Both GtkComboBox and GtkComboBoxText can contain an entry.

CSS nodes

(plain Language Example):

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.

(plain Language Example):

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.

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.

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

A GtkComboBoxText is a simple variant of GtkComboBox that hides the model-view complexity for simple text-only use cases.

To create a GtkComboBoxText, use gtk_combo_box_text_new() or gtk_combo_box_text_new_with_entry().

You can add items to a GtkComboBoxText with gtk_combo_box_text_append_text(), gtk_combo_box_text_insert_text() or gtk_combo_box_text_prepend_text() and remove options with gtk_combo_box_text_remove().

If the GtkComboBoxText contains an entry (via the “has-entry” property), its contents can be retrieved using gtk_combo_box_text_get_active_text(). The entry itself can be accessed by calling gtk_bin_get_child() on the combo box.

You should not call gtk_combo_box_set_model() or attempt to pack more cells into this combo box via its GtkCellLayout 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

(plain Language Example):

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 GTK+ user interface is constructed by nesting widgets inside widgets. Container widgets are the inner nodes in the resulting tree of widgets: they contain other widgets. So, for example, you might have a GtkWindow containing a GtkFrame containing a GtkLabel. If you wanted an image instead of a textual label inside the frame, you might replace the GtkLabel widget with a GtkImage widget.

There are two major kinds of container widgets in GTK+. Both are subclasses of the abstract GtkContainer base class.

The first type of container widget has a single child widget and derives from GtkBin. These containers are decorators, which add some kind of functionality to the child. For example, a GtkButton makes its child into a clickable button; a GtkFrame draws a frame around its child and a GtkWindow places its child widget inside a top-level window.

The second type of container can have more than one child; its purpose is to manage layout. This means that these containers assign sizes and positions to their children. For example, a GtkHBox arranges its children in a horizontal row, and a GtkGrid arranges the widgets it contains in a two-dimensional grid.

For implementations of GtkContainer the virtual method GtkContainerClass.forall() is always required, since it’s used for drawing and other internal operations on the children. If the GtkContainer implementation expect to have non internal children it’s needed to implement both GtkContainerClass.add() and GtkContainerClass.remove(). If the GtkContainer implementation has internal children, they should be added with gtk_widget_set_parent() on init() and removed with gtk_widget_unparent() in the GtkWidgetClass.destroy() implementation. See more about implementing custom widgets at https://wiki.gnome.org/HowDoI/CustomWidgets

Height for width geometry management

GTK+ uses a height-for-width (and width-for-height) geometry management system. Height-for-width means that a widget can change how much vertical space it needs, depending on the amount of horizontal space that it is given (and similar for width-for-height).

There are some things to keep in mind when implementing container widgets that make use of GTK+’s height for width geometry management system. First, it’s important to note that a container must prioritize one of its dimensions, that is to say that a widget or container can only have a GtkSizeRequestMode that is GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT. However, every widget and container must be able to respond to the APIs for both dimensions, i.e. even if a widget has a request mode that is height-for-width, it is possible that its parent will request its sizes using the width-for-height APIs.

To ensure that everything works properly, here are some guidelines to follow when implementing height-for-width (or width-for-height) containers.

Each request mode involves 2 virtual methods. Height-for-width apis run through gtk_widget_get_preferred_width() and then through gtk_widget_get_preferred_height_for_width(). When handling requests in the opposite GtkSizeRequestMode it is important that every widget request at least enough space to display all of its content at all times.

When gtk_widget_get_preferred_height() is called on a container that is height-for-width, the container must return the height for its minimum width. This is easily achieved by simply calling the reverse apis implemented for itself as follows:

(C Language Example):

static void
foo_container_get_preferred_height (GtkWidget *widget,
                                    gint *min_height,
                                    gint *nat_height)
{
   if (i_am_in_height_for_width_mode)
     {
       gint min_width;

       GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
                                                           &min_width,
                                                           NULL);
       GTK_WIDGET_GET_CLASS (widget)->get_preferred_height_for_width
                                                          (widget,
                                                           min_width,
                                                           min_height,
                                                           nat_height);
     }
   else
     {
       ... many containers support both request modes, execute the
       real width-for-height request here by returning the
       collective heights of all widgets that are stacked
       vertically (or whatever is appropriate for this container)
       ...
     }
}

Similarly, when gtk_widget_get_preferred_width_for_height() is called for a container or widget that is height-for-width, it then only needs to return the base minimum width like so:

(C Language Example):

static void
foo_container_get_preferred_width_for_height (GtkWidget *widget,
                                              gint for_height,
                                              gint *min_width,
                                              gint *nat_width)
{
   if (i_am_in_height_for_width_mode)
     {
       GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
                                                           min_width,
                                                           nat_width);
     }
   else
     {
       ... execute the real width-for-height request here based on
       the required width of the children collectively if the
       container were to be allocated the said height ...
     }
}

Height for width requests are generally implemented in terms of a virtual allocation of widgets in the input orientation. Assuming an height-for-width request mode, a container would implement the get_preferred_height_for_width() virtual function by first calling gtk_widget_get_preferred_width() for each of its children.

For each potential group of children that are lined up horizontally, the values returned by gtk_widget_get_preferred_width() should be collected in an array of GtkRequestedSize structures. Any child spacing should be removed from the input for_width and then the collective size should be allocated using the gtk_distribute_natural_allocation() convenience function.

The container will then move on to request the preferred height for each child by using gtk_widget_get_preferred_height_for_width() and using the sizes stored in the GtkRequestedSize array.

To allocate a height-for-width container, it’s again important to consider that a container must prioritize one dimension over the other. So if a container is a height-for-width container it must first allocate all widgets horizontally using a GtkRequestedSize array and gtk_distribute_natural_allocation() and then add any extra space (if and where appropriate) for the widget to expand.

After adding all the expand space, the container assumes it was allocated sufficient height to fit all of its content. At this time, the container must use the total horizontal sizes of each widget to request the height-for-width of each of its children and store the requests in a GtkRequestedSize array for any widgets that stack vertically (for tabular containers this can be generalized into the heights and widths of rows and columns). The vertical space must then again be distributed using gtk_distribute_natural_allocation() while this time considering the allocated height of the widget minus any vertical spacing that the container adds. Then vertical expand space should be added where appropriate and available and the container should go on to actually allocating the child widgets.

See GtkWidget’s geometry management section to learn more about implementing height-for-width geometry management for widgets.

Child properties

GtkContainer introduces child properties. These are object properties that are not specific to either the container or the contained widget, but rather to their relation. Typical examples of child properties are the position or pack-type of a widget which is contained in a GtkBox.

Use gtk_container_class_install_child_property() to install child properties for a container class and gtk_container_class_find_child_property() or gtk_container_class_list_child_properties() to get information about existing child properties.

To set the value of a child property, use gtk_container_child_set_property(), gtk_container_child_set() or gtk_container_child_set_valist(). To obtain the value of a child property, use gtk_container_child_get_property(), gtk_container_child_get() or gtk_container_child_get_valist(). To emit notification about child property changes, use gtk_widget_child_notify().

GtkContainer as GtkBuildable

The GtkContainer implementation of the GtkBuildable interface supports a <packing> element for children, which can contain multiple <property> elements that specify child properties for the child.

Since 2.16, child properties can also be marked as translatable using the same “translatable”, “comments” and “context” attributes that are used for regular properties.

Since 3.16, containers can have a <focus-chain> element containing multiple <widget> elements, one for each child that should be added to the focus chain. The ”name” attribute gives the id of the widget.

An example of these properties in UI definitions:

<object class="GtkBox">
  <child>
    <object class="GtkEntry" id="entry1"/>
    <packing>
      <property name="pack-type">start</property>
    </packing>
  </child>
  <child>
    <object class="GtkEntry" id="entry2"/>
  </child>
  <focus-chain>
    <widget name="entry1"/>
    <widget name="entry2"/>
  </focus-chain>
</object>

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

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

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

GtkCssProvider is an object implementing the GtkStyleProvider interface. It is able to parse CSS-like input in order to style widgets.

An application can make GTK+ parse a specific CSS style sheet by calling gtk_css_provider_load_from_file() or gtk_css_provider_load_from_resource() and adding the provider with gtk_style_context_add_provider() or gtk_style_context_add_provider_for_screen().

In addition, certain files will be read when GTK+ is initialized. First, the file $XDG_CONFIG_HOME/gtk-3.0/gtk.css is loaded if it exists. Then, GTK+ loads the first existing file among XDG_DATA_HOME/themes/THEME/gtk-VERSION/gtk.css, $HOME/.themes/THEME/gtk-VERSION/gtk.css, $XDG_DATA_DIRS/themes/THEME/gtk-VERSION/gtk.css and DATADIR/share/themes/THEME/gtk-VERSION/gtk.css, where THEME is the name of the current theme (see the GtkSettings:gtk-theme-name 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 3.0.

In the same way, GTK+ tries to load a gtk-keys.css file for the current key theme, as defined by GtkSettings:gtk-key-theme-name.

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.

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.

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

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.

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 GtkColorChooserWidget, GtkColorChooserDialog and GtkColorButton.

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 GtkEditable interface is an interface which should be implemented by text editing widgets, such as GtkEntry and GtkSpinButton. 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 to modify the behavior of a widget.

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

Forcing entry to uppercase.

(C Language Example):

#include <ctype.h>;

void
insert_text_handler (GtkEditable *editable,
                     const gchar *text,
                     gint         length,
                     gint        *position,
                     gpointer     data)
{
  gchar *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);
}

The Editable type acts as an 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.

The GtkDrawingArea widget is used for creating custom user interface elements. It’s essentially a blank widget; you can draw on it. After creating a drawing area, the application may want to connect to:

• Mouse and button press signals to respond to input from the user. (Use gtk_widget_add_events() to enable events you wish to receive.)

• The GtkWidget::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 GtkWidget::size-allocate signal to take any necessary actions when the widget changes size.

• The GtkWidget::draw signal 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.

Note that GDK automatically clears the exposed area before sending the expose event, and that drawing is implicitly clipped to the exposed area. If you want to have a theme-provided background, you need to call gtk_render_background() in your draw method.

Simple GtkDrawingArea usage

(C Language Example):

gboolean
draw_callback (GtkWidget *widget, cairo_t *cr, gpointer data)
{
  guint width, height;
  GdkRGBA color;
  GtkStyleContext *context;

  context = gtk_widget_get_style_context (widget);

  width = gtk_widget_get_allocated_width (widget);
  height = gtk_widget_get_allocated_height (widget);

  gtk_render_background (context, cr, 0, 0, width, height);

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

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

  cairo_fill (cr);

 return FALSE;
}
[...]
  GtkWidget *drawing_area = gtk_drawing_area_new ();
  gtk_widget_set_size_request (drawing_area, 100, 100);
  g_signal_connect (G_OBJECT (drawing_area), "draw",
                    G_CALLBACK (draw_callback), NULL);

Draw signals are normally delivered when a drawing area first comes onscreen, or when it’s covered by another window and then uncovered. You can also force an expose event by adding to the “damage region” of the drawing area’s window; gtk_widget_queue_draw_area() and gdk_window_invalidate_rect() are equally good ways to do this. You’ll then get a draw signal for the invalid region.

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 enable them with gtk_widget_add_events(). 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. Use gtk_widget_has_focus() in your expose event handler to decide whether to draw the focus indicator. See gtk_render_focus() for one way to draw focus.

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.

The GtkEntry widget 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 gtk_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 gtk_entry_set_invisible_char(). Since 2.16, GTK+ displays a warning when Caps Lock or input methods might interfere with entering text in a password entry. The warning can be turned off with the GtkEntry:caps-lock-warning property.

Since 2.16, GtkEntry has the ability to display progress or activity information behind the text. To make an entry display such information, use gtk_entry_set_progress_fraction() or gtk_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 gtk_entry_set_icon_from_gicon() or one of the various other functions that set an icon from a stock id, an icon name or a pixbuf. To trigger an action when the user clicks an icon, connect to the GtkEntry::icon-press signal. To allow DND operations from an icon, use gtk_entry_set_icon_drag_source(). To set a tooltip on an icon, use gtk_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

(plain Language Example):

entry[.read-only][.flat][.warning][.error]
├── image.left
├── image.right
├── undershoot.left
├── undershoot.right
├── [selection]
├── [progress[.pulse]]
╰── [window.popup]

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 has a selection, it adds a subnode with the name selection.

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.

The CSS node for a context menu is added as a subnode below entry as well.

The undershoot nodes are used to draw the underflow indication when content is scrolled out of view. These nodes get the .left and .right style classes added depending on where the indication is drawn.

When touch is used and touch selection handles are shown, they are using CSS nodes with name cursor-handle. They get the .top or .bottom style class depending on where they are shown in relation to the selection. If there is just a single handle for the text cursor, it gets the style class .insertion-cursor.

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.

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

The GtkEntryBuffer class contains the actual text displayed in a GtkEntry widget.

A single GtkEntryBuffer object can be shared by multiple GtkEntry 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 be used in conjunction with GtkEntry to provide the completion functionality. It implements the GtkCellLayout 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 gtk_entry_completion_set_text_column()), but this can be overridden with a custom match function (see gtk_entry_completion_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 GtkEntryCompletion::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 gtk_entry_set_completion().

In addition to regular completion matches, which will be inserted into the entry when they are selected, GtkEntryCompletion also allows to display “actions” in the popup window. Their appearance is similar to menuitems, to differentiate them clearly from completion strings. When an action is selected, the GtkEntryCompletion::action-activated signal is emitted.

GtkEntryCompletion uses a GtkTreeModelFilter model to represent the subset of the entire model that is currently matching. While the GtkEntryCompletion signals GtkEntryCompletion::match-selected and GtkEntryCompletion::cursor-on-match take the original model and an iter pointing to that model as arguments, other callbacks and signals (such as GtkCellLayoutDataFuncs or GtkCellArea::apply-attributes) will generally take the filter model as argument. As long as you are only calling gtk_tree_model_get(), this will make no difference to you. If for some reason, you need the original model, use gtk_tree_model_filter_get_model(). Don’t forget to use gtk_tree_model_filter_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.

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

The GtkEventBox widget is a subclass of GtkBin which also has its own window. It is useful since it allows you to catch events for widgets which do not have their own window.

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

GtkEventController is a base, low-level implementation for event controllers. Those react to a series of GdkEvents, and possibly trigger actions as a consequence of those.

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

GtkEventControllerKey is an event controller meant for situations where you need access to key events.

This object was added in 3.24.

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

GtkEventControllerMotion is an event controller meant for situations where you need to track the position of the pointer.

This object was added in 3.24.

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

GtkEventControllerScroll is an event controller meant to handle scroll events from mice and touchpads. It is capable of handling both discrete and continuous scroll events, abstracting them both on the GtkEventControllerScroll::scroll signal (deltas in the discrete case are multiples of 1).

In the case of continuous scroll events, GtkEventControllerScroll encloses all GtkEventControllerScroll::scroll events between two GtkEventControllerScroll::scroll-begin and GtkEventControllerScroll::scroll-end signals.

The behavior of the event controller can be modified by the flags given at creation time, or modified at a later point through gtk_event_controller_scroll_set_flags() (e.g. because the scrolling conditions of the widget changed).

The controller can be set up to emit motion for either/both vertical and horizontal scroll events through GTK_EVENT_CONTROLLER_SCROLL_VERTICAL, GTK_EVENT_CONTROLLER_SCROLL_HORIZONTAL and GTK_EVENT_CONTROLLER_SCROLL_BOTH. If any axis is disabled, the respective GtkEventControllerScroll::scroll delta will be 0. Vertical scroll events will be translated to horizontal motion for the devices incapable of horizontal scrolling.

The event controller can also be forced to emit discrete events on all devices through GTK_EVENT_CONTROLLER_SCROLL_DISCRETE. This can be used to implement discrete actions triggered through scroll events (e.g. switching across combobox options).

The GTK_EVENT_CONTROLLER_SCROLL_KINETIC flag toggles the emission of the GtkEventControllerScroll::decelerate signal, emitted at the end of scrolling with two X/Y velocity arguments that are consistent with the motion that was received.

This object was added in 3.24.

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

A GtkExpander allows the user to hide or show its child by clicking on an expander triangle similar to the triangles used in a GtkTreeView.

Normally you use an expander as you would use any other descendant of GtkBin; you create the child widget and use gtk_container_add() to add it to the expander. When the expander is toggled, it will take care of showing and hiding the child automatically.

Special Usage

There are situations in which you may prefer to show and hide the expanded widget yourself, such as when you want to actually create the widget at expansion time. In this case, create a GtkExpander but do not add a child to it. The expander widget has an GtkExpander:expanded property which can be used to monitor its expansion state. You should watch this property with a signal connection as follows:

(C Language Example):

static void
expander_callback (GObject    *object,
                   GParamSpec *param_spec,
                   gpointer    user_data)
{
  GtkExpander *expander;

  expander = GTK_EXPANDER (object);

  if (gtk_expander_get_expanded (expander))
    {
      // Show or create widgets
    }
  else
    {
      // Hide or destroy widgets
    }
}

static void
create_expander (void)
{
  GtkWidget *expander = gtk_expander_new_with_mnemonic ("_More Options");
  g_signal_connect (expander, "notify::expanded",
                    G_CALLBACK (expander_callback), NULL);

  // ...
}

GtkExpander as GtkBuildable

The GtkExpander implementation of the GtkBuildable interface supports placing a child in the label position by specifying “label” as the “type” attribute of a <child> element. A normal content child can be specified without specifying a <child> type attribute.

An example of a UI definition fragment with GtkExpander:

<object class="GtkExpander">
  <child type="label">
    <object class="GtkLabel" id="expander-label"/>
  </child>
  <child>
    <object class="GtkEntry" id="expander-content"/>
  </child>
</object>

CSS nodes

(plain Language Example):

expander
├── title
│   ├── arrow
│   ╰── <label widget>
╰── <child>

GtkExpander has three CSS nodes, the main node with the name expander, a subnode with name title and node below it with name arrow. The arrow of an expander that is showing its child gets the :checked pseudoclass added to it.

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

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

The GtkFileChooserButton is a widget that lets the user select a file. It implements the GtkFileChooser interface. Visually, it is a file name with a button to bring up a GtkFileChooserDialog. The user can then use that dialog to change the file associated with that button. This widget does not support setting the GtkFileChooser:select-multiple property to true.

Create a button to let the user select a file in /etc

(C Language Example):

{
  GtkWidget *button;

  button = gtk_file_chooser_button_new (_("Select a file"),
                                        GTK_FILE_CHOOSER_ACTION_OPEN);
  gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (button),
                                       "/etc");
}

The GtkFileChooserButton supports the GtkFileChooserActions GTK_FILE_CHOOSER_ACTION_OPEN and GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER.

> The GtkFileChooserButton will ellipsize the label, and will thus > request little horizontal space. To give the button more space, > you should call gtk_widget_get_preferred_size(), > gtk_file_chooser_button_set_width_chars(), or pack the button in > such a way that other interface elements give space to the > widget.

CSS nodes

GtkFileChooserButton has a CSS node with name “filechooserbutton”, containing a subnode for the internal button with name “button” and style class “.file”.

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

GtkFileChooser is an interface that can be implemented by file selection widgets. In GTK+, the main objects that implement this interface are GtkFileChooserWidget, GtkFileChooserDialog, and GtkFileChooserButton. You do not need to write an object that implements the GtkFileChooser interface unless you are trying to adapt an existing file selector to expose a standard programming interface.

GtkFileChooser allows for shortcuts to various places in the filesystem. In the default implementation these are displayed in the left pane. It may be a bit confusing at first that these shortcuts come from various sources and in various flavours, so lets explain the terminology here:

• Bookmarks: are created by the user, by dragging folders from the right pane to the left pane, or by using the “Add”. Bookmarks can be renamed and deleted by the user.

• Shortcuts: can be provided by the application. For example, a Paint program may want to add a shortcut for a Clipart folder. Shortcuts cannot be modified by the user.

• Volumes: are provided by the underlying filesystem abstraction. They are the “roots” of the filesystem.

File Names and Encodings

When the user is finished selecting files in a GtkFileChooser, your program can get the selected names either as filenames or as URIs. For URIs, the normal escaping rules are applied if the URI contains non-ASCII characters. However, filenames are always returned in the character set specified by the G_FILENAME_ENCODING environment variable. Please see the GLib documentation for more details about this variable.

This means that while you can pass the result of gtk_file_chooser_get_filename() to g_open() or g_fopen(), you may not be able to directly set it as the text of a GtkLabel widget unless you convert it first to UTF-8, which all GTK+ widgets expect. You should use g_filename_to_utf8() to convert filenames into strings that can be passed to GTK+ widgets.

Adding a Preview Widget

You can add a custom preview widget to a file chooser and then get notification about when the preview needs to be updated. To install a preview widget, use gtk_file_chooser_set_preview_widget(). Then, connect to the GtkFileChooser::update-preview signal to get notified when you need to update the contents of the preview.

Your callback should use gtk_file_chooser_get_preview_filename() to see what needs previewing. Once you have generated the preview for the corresponding file, you must call gtk_file_chooser_set_preview_widget_active() with a boolean flag that indicates whether your callback could successfully generate a preview.

Example: Using a Preview Widget ##

(C Language Example):

{
  GtkImage *preview;

  ...

  preview = gtk_image_new ();

  gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
  g_signal_connect (my_file_chooser, "update-preview",
            G_CALLBACK (update_preview_cb), preview);
}

static void
update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
{
  GtkWidget *preview;
  char *filename;
  GdkPixbuf *pixbuf;
  gboolean have_preview;

  preview = GTK_WIDGET (data);
  filename = gtk_file_chooser_get_preview_filename (file_chooser);

  pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);
  have_preview = (pixbuf != NULL);
  g_free (filename);

  gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
  if (pixbuf)
    g_object_unref (pixbuf);

  gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
}

Adding Extra Widgets

You can add extra widgets to a file chooser to provide options that are not present in the default design. For example, you can add a toggle button to give the user the option to open a file in read-only mode. You can use gtk_file_chooser_set_extra_widget() to insert additional widgets in a file chooser.

An example for adding extra widgets: (C Language Example):

  GtkWidget *toggle;

  ...

  toggle = gtk_check_button_new_with_label ("Open file read-only");
  gtk_widget_show (toggle);
  gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
}

If you want to set more than one extra widget in the file chooser, you can a container such as a GtkBox or a GtkGrid and include your widgets in it. Then, set the container as the whole extra widget.

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

GtkFontChooser is an interface that can be implemented by widgets displaying the list of fonts. In GTK+, the main objects that implement this interface are GtkFontChooserWidget, GtkFontChooserDialog and GtkFontButton. The GtkFontChooser interface has been introducted in GTK+ 3.2.

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

The GtkOrientable interface is implemented by all widgets that can be oriented horizontally or vertically. Historically, such widgets have been realized as subclasses of a common base class (e.g GtkBox/GtkHBox/GtkVBox or GtkScale/GtkHScale/GtkVScale). GtkOrientable is more flexible in that it allows the orientation to be changed at runtime, allowing the widgets to “flip”.

GtkOrientable was introduced in GTK+ 2.16.

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

GtkFileChooserWidget is a widget for choosing files. It exposes the GtkFileChooser interface, and you should use the methods of this interface to interact with the widget.

CSS nodes

GtkFileChooserWidget has a single CSS node with name filechooser.

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

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

A GtkFileFilter can be used to restrict the files being shown in a GtkFileChooser. Files can be filtered based on their name (with gtk_file_filter_add_pattern()), on their mime type (with gtk_file_filter_add_mime_type()), or by a custom filter function (with gtk_file_filter_add_custom()).

Filtering by mime types handles aliasing and subclassing of mime types; e.g. a filter for text/plain also matches a file with mime type application/rtf, since application/rtf is a subclass of text/plain. Note that GtkFileFilter allows wildcards for the subtype of a mime type, so you can e.g. filter for image/*.

Normally, filters are used by adding them to a GtkFileChooser, see gtk_file_chooser_add_filter(), but it is also possible to manually use a filter on a file with gtk_file_filter_filter().

GtkFileFilter as GtkBuildable

The GtkFileFilter implementation of the GtkBuildable interface supports adding rules using the <mime-types>, <patterns> and <applications> elements and listing the rules within. Specifying a <mime-type> or <pattern> has the same effect as as calling gtk_file_filter_add_mime_type() or gtk_file_filter_add_pattern().

An example of a UI definition fragment specifying GtkFileFilter rules:

<object class="GtkFileFilter">
  <mime-types>
    <mime-type>text/plain</mime-type>
    <mime-type>image/ *</mime-type>
  </mime-types>
  <patterns>
    <pattern>*.txt</pattern>
    <pattern>*.png</pattern>
  </patterns>
</object>

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

The GtkFixed widget is a container which can place child widgets at fixed positions and with fixed sizes, given in pixels. GtkFixed performs no automatic layout management.

For most applications, you should not use this container! It keeps you from having to learn about the other GTK+ containers, but it results in broken applications. With GtkFixed, the following things will result in truncated text, overlapping widgets, and other display bugs:

• Themes, which may change widget sizes.

• Fonts other than the one you used to write the app will of course change the size of widgets containing text; keep in mind that users may use a larger font because of difficulty reading the default, or they may be using a different OS that provides different fonts.

• Translation of text into other languages changes its size. Also, display of non-English text will use a different font in many cases.

In addition, GtkFixed does not pay attention to text direction and thus may produce unwanted results if your app is run under right-to-left languages such as Hebrew or Arabic. That is: normally GTK+ will order containers appropriately for the text direction, e.g. to put labels to the right of the thing they label when using an RTL language, but it can’t do that with GtkFixed. So if you need to reorder widgets depending on the text direction, you would need to manually detect it and adjust child positions accordingly.

Finally, fixed positioning makes it kind of annoying to add/remove GUI elements, since you have to reposition all the other elements. This is a long-term maintenance problem for your application.

If you know none of these things are an issue for your application, and prefer the simplicity of GtkFixed, by all means use the widget. But you should be aware of the tradeoffs.

See also GtkLayout, which shares the ability to perform fixed positioning of child widgets and additionally adds custom drawing and scrollability.

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

A GtkFlowBox positions child widgets in sequence according to its orientation.

For instance, with the horizontal orientation, the widgets will be arranged from left to right, starting a new row under the previous row when necessary. Reducing the width in this case will require more rows, so a larger height will be requested.

Likewise, with the vertical orientation, the widgets will be arranged from top to bottom, starting a new column to the right when necessary. Reducing the height will require more columns, so a larger width will be requested.

The size request of a GtkFlowBox alone may not be what you expect; if you need to be able to shrink it along both axes and dynamically reflow its children, you may have to wrap it in a GtkScrolledWindow to enable that.

The children of a GtkFlowBox can be dynamically sorted and filtered.

Although a GtkFlowBox must have only GtkFlowBoxChild children, you can add any kind of widget to it via gtk_container_add(), and a GtkFlowBoxChild widget will automatically be inserted between the box and the widget.

Also see GtkListBox.

GtkFlowBox was added in GTK+ 3.12.

CSS nodes

(plain Language Example):

flowbox
├── flowboxchild
│   ╰── <child>
├── flowboxchild
│   ╰── <child>
┊
╰── [rubberband]

GtkFlowBox uses a single CSS node with name flowbox. GtkFlowBoxChild uses a single CSS node with name flowboxchild. For rubberband selection, a subnode with name rubberband is used.

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

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

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

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

The GtkFontButton is a button which displays the currently selected font an allows to open a font chooser dialog to change the font. It is suitable widget for selecting a font in a preference dialog.

CSS nodes

GtkFontButton has a single CSS node with name button and style class .font.

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

The GtkFontChooserDialog widget is a dialog for selecting a font. It implements the GtkFontChooser interface.

GtkFontChooserDialog as GtkBuildable

The GtkFontChooserDialog implementation of the GtkBuildable interface exposes the buttons with the names “select_button” and “cancel_button”.

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

The GtkFontChooserWidget widget lists the available fonts, styles and sizes, allowing the user to select a font. It is used in the GtkFontChooserDialog widget to provide a dialog box for selecting fonts.

To set the font which is initially selected, use gtk_font_chooser_set_font() or gtk_font_chooser_set_font_desc().

To get the selected font use gtk_font_chooser_get_font() or gtk_font_chooser_get_font_desc().

To change the text which is shown in the preview area, use gtk_font_chooser_set_preview_text().

CSS nodes

GtkFontChooserWidget has a single CSS node with name fontchooser.

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

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

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

The frame widget is a bin that surrounds its child with a decorative frame and an optional label. If present, the label is drawn in a gap in the top side of the frame. The position of the label can be controlled with gtk_frame_set_label_align().

GtkFrame as GtkBuildable

The GtkFrame implementation of the GtkBuildable interface supports placing a child in the label position by specifying “label” as the “type” attribute of a <child> element. A normal content child can be specified without specifying a <child> type attribute.

An example of a UI definition fragment with GtkFrame:

<object class="GtkFrame">
  <child type="label">
    <object class="GtkLabel" id="frame-label"/>
  </child>
  <child>
    <object class="GtkEntry" id="frame-content"/>
  </child>
</object>

CSS nodes

(plain Language Example):

frame
├── border[.flat]
├── <label widget>
╰── <child>

GtkFrame has a main CSS node named “frame” and a subnode named “border”. The “border” node is used to draw the visible border. You can set the appearance of the border using CSS properties like “border-style” on the “border” node.

The border node can be given the style class “.flat”, which is used by themes to disable drawing of the border. To do this from code, call gtk_frame_set_shadow_type() with GTK_SHADOW_NONE to add the “.flat” class or any other shadow type to remove it.

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

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

GtkGLArea is a widget that allows drawing with OpenGL.

GtkGLArea sets up its own GdkGLContext for the window it creates, and creates a custom GL framebuffer that the widget will do GL rendering onto. It also ensures that this framebuffer is the default GL rendering target when rendering.

In order to draw, you have to connect to the GtkGLArea::render signal, or subclass GtkGLArea and override the GtkGLAreaClass.render() virtual function.

The GtkGLArea widget ensures that the GdkGLContext is associated with the widget’s drawing area, and it is kept updated when the size and position of the drawing area changes.

Drawing with GtkGLArea

The simplest way to draw using OpenGL commands in a GtkGLArea is to create a widget instance and connect to the GtkGLArea::render signal:

(C Language Example):

  // create a GtkGLArea instance
  GtkWidget *gl_area = gtk_gl_area_new ();

  // connect to the "render" signal
  g_signal_connect (gl_area, "render", G_CALLBACK (render), NULL);

The render() function will be called when the GtkGLArea is ready for you to draw its content:

(C Language Example):

  static gboolean
  render (GtkGLArea *area, GdkGLContext *context)
  {
    // inside this function it's safe to use GL; the given
    // #GdkGLContext has been made current to the drawable
    // surface used by the #GtkGLArea and the viewport has
    // already been set to be the size of the allocation

    // we can start by clearing the buffer
    glClearColor (0, 0, 0, 0);
    glClear (GL_COLOR_BUFFER_BIT);

    // draw your object
    draw_an_object ();

    // we completed our drawing; the draw commands will be
    // flushed at the end of the signal emission chain, and
    // the buffers will be drawn on the window
    return TRUE;
  }

If you need to initialize OpenGL state, e.g. buffer objects or shaders, you should use the GtkWidget::realize signal; you can use the GtkWidget::unrealize signal to clean up. Since the GdkGLContext creation and initialization may fail, you will need to check for errors, using gtk_gl_area_get_error(). An example of how to safely initialize the GL state is:

(C Language Example):

  static void
  on_realize (GtkGLarea *area)
  {
    // We need to make the context current if we want to
    // call GL API
    gtk_gl_area_make_current (area);

    // If there were errors during the initialization or
    // when trying to make the context current, this
    // function will return a #GError for you to catch
    if (gtk_gl_area_get_error (area) != NULL)
      return;

    // You can also use gtk_gl_area_set_error() in order
    // to show eventual initialization errors on the
    // GtkGLArea widget itself
    GError *internal_error = NULL;
    init_buffer_objects (&error);
    if (error != NULL)
      {
        gtk_gl_area_set_error (area, error);
        g_error_free (error);
        return;
      }

    init_shaders (&error);
    if (error != NULL)
      {
        gtk_gl_area_set_error (area, error);
        g_error_free (error);
        return;
      }
  }

If you need to change the options for creating the GdkGLContext you should use the GtkGLArea::create-context signal.

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

A GtkFileFilterInfo-struct is used to pass information about the tested file to gtk_file_filter_filter().

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

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

GtkGesture is the base object for gesture recognition, although this object is quite generalized to serve as a base for multi-touch gestures, it is suitable to implement single-touch and pointer-based gestures (using the special nil GdkEventSequence value for these).

The number of touches that a GtkGesture need to be recognized is controlled by the GtkGesture:n-points property, if a gesture is keeping track of less or more than that number of sequences, it won’t check wether the gesture is recognized.

As soon as the gesture has the expected number of touches, the gesture will run the GtkGesture::check signal regularly on input events until the gesture is recognized, the criteria to consider a gesture as “recognized” is left to GtkGesture subclasses.

A recognized gesture will then emit the following signals:

• GtkGesture::begin when the gesture is recognized.
• A number of GtkGesture::update, whenever an input event is processed.
• GtkGesture::end when the gesture is no longer recognized.

Event propagation

In order to receive events, a gesture needs to either set a propagation phase through gtk_event_controller_set_propagation_phase(), or feed those manually through gtk_event_controller_handle_event().

In the capture phase, events are propagated from the toplevel down to the target widget, and gestures that are attached to containers above the widget get a chance to interact with the event before it reaches the target.

After the capture phase, GTK+ emits the traditional GtkWidget::button-press-event, GtkWidget::button-release-event, GtkWidget::touch-event, etc signals. Gestures with the GTK_PHASE_TARGET phase are fed events from the default GtkWidget::event handlers.

In the bubble phase, events are propagated up from the target widget to the toplevel, and gestures that are attached to containers above the widget get a chance to interact with events that have not been handled yet.

States of a sequence #

Whenever input interaction happens, a single event may trigger a cascade of GtkGestures, both across the parents of the widget receiving the event and in parallel within an individual widget. It is a responsibility of the widgets using those gestures to set the state of touch sequences accordingly in order to enable cooperation of gestures around the GdkEventSequences triggering those.

Within a widget, gestures can be grouped through gtk_gesture_group(), grouped gestures synchronize the state of sequences, so calling gtk_gesture_set_sequence_state() on one will effectively propagate the state throughout the group.

By default, all sequences start out in the GTK_EVENT_SEQUENCE_NONE state, sequences in this state trigger the gesture event handler, but event propagation will continue unstopped by gestures.

If a sequence enters into the GTK_EVENT_SEQUENCE_DENIED state, the gesture group will effectively ignore the sequence, letting events go unstopped through the gesture, but the “slot” will still remain occupied while the touch is active.

If a sequence enters in the GTK_EVENT_SEQUENCE_CLAIMED state, the gesture group will grab all interaction on the sequence, by:

• Setting the same sequence to GTK_EVENT_SEQUENCE_DENIED on every other gesture group within the widget, and every gesture on parent widgets in the propagation chain.
• calling GtkGesture::cancel on every gesture in widgets underneath in the propagation chain.
• Stopping event propagation after the gesture group handles the event.

Note: if a sequence is set early to GTK_EVENT_SEQUENCE_CLAIMED on GDK_TOUCH_BEGIN/GDK_BUTTON_PRESS (so those events are captured before reaching the event widget, this implies GTK_PHASE_CAPTURE), one similar event will emulated if the sequence changes to GTK_EVENT_SEQUENCE_DENIED. This way event coherence is preserved before event propagation is unstopped again.

Sequence states can’t be changed freely, see gtk_gesture_set_sequence_state() to know about the possible lifetimes of a GdkEventSequence.

Touchpad gestures

On the platforms that support it, GtkGesture will handle transparently touchpad gesture events. The only precautions users of GtkGesture should do to enable this support are:

• Enabling GDK_TOUCHPAD_GESTURE_MASK on their GdkWindows
• If the gesture has GTK_PHASE_NONE, ensuring events of type GDK_TOUCHPAD_SWIPE and GDK_TOUCHPAD_PINCH are handled by the GtkGesture

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

GtkGestureDrag is a GtkGesture implementation that recognizes drag operations. The drag operation itself can be tracked throught the GtkGestureDrag::drag-begin, GtkGestureDrag::drag-update and GtkGestureDrag::drag-end signals, or the relevant coordinates be extracted through gtk_gesture_drag_get_offset() and gtk_gesture_drag_get_start_point().

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