The `AboutDialog` 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. `AboutDialog` 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 `AboutDialog::activate-link` signal. To specify a person with an email address, use a string like "Edgar Allan Poe ". To specify a website with a title, use a string like "GTK+ team http://www.gtk.org". To make constructing a `AboutDialog` 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 `AboutDialog`, as shown in the following example: ```C GdkTexture *example_logo = gdk_texture_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 `AboutDialog` like any other `Dialog`, e.g. using `Dialog::run`. In this case, you might need to know that the “Close” button returns the `ResponseType::Cancel` response id. # Implements [`AboutDialogExt`](trait.AboutDialogExt.html), [`DialogExt`](trait.DialogExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`RootExt`](trait.RootExt.html), [`DialogExtManual`](prelude/trait.DialogExtManual.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html) Trait containing all `AboutDialog` methods. # Implementors [`AboutDialog`](struct.AboutDialog.html) Creates a new `AboutDialog`. # Returns a newly created `AboutDialog` Creates a new section in the Credits page. ## `section_name` The name of the section ## `people` The people who belong to that section Returns the string which are displayed in the artists tab of the secondary credits dialog. # Returns A `None`-terminated string array containing the artists. The array is owned by the about dialog and must not be modified. Returns the string which are displayed in the authors tab of the secondary credits dialog. # Returns A `None`-terminated string array containing the authors. The array is owned by the about dialog and must not be modified. Returns the comments string. # Returns The comments. The string is owned by the about dialog and must not be modified. Returns the copyright string. # Returns The copyright string. The string is owned by the about dialog and must not be modified. Returns the string which are displayed in the documenters tab of the secondary credits dialog. # Returns A `None`-terminated string array containing the documenters. The array is owned by the about dialog and must not be modified. Returns the license information. # Returns The license information. The string is owned by the about dialog and must not be modified. Retrieves the license set using `AboutDialogExt::set_license_type` # Returns a `License` value Returns the paintable displayed as logo in the about dialog. # Returns the paintable displayed as logo. The paintable is owned by the about dialog. If you want to keep a reference to it, you have to call `gobject::ObjectExt::ref` on it. Returns the icon name displayed as logo in the about dialog. # Returns the icon name displayed as logo. The string is owned by the dialog. If you want to keep a reference to it, you have to call `g_strdup` on it. Returns the program name displayed in the about dialog. # Returns The program name. The string is owned by the about dialog and must not be modified. Returns the system information that is shown in the about dialog. # Returns the system information Returns the translator credits string which is displayed in the translators tab of the secondary credits dialog. # Returns The translator credits string. The string is owned by the about dialog and must not be modified. Returns the version string. # Returns The version string. The string is owned by the about dialog and must not be modified. Returns the website URL. # Returns The website URL. The string is owned by the about dialog and must not be modified. Returns the label used for the website link. # Returns The label used for the website link. The string is owned by the about dialog and must not be modified. Returns whether the license text in `self` is automatically wrapped. # Returns `true` if the license text is wrapped Sets the strings which are displayed in the artists tab of the secondary credits dialog. ## `artists` a `None`-terminated array of strings Sets the strings which are displayed in the authors tab of the secondary credits dialog. ## `authors` a `None`-terminated array of strings Sets the comments string to display in the about dialog. This should be a short string of one or two lines. ## `comments` a comments string Sets the copyright string to display in the about dialog. This should be a short string of one or two lines. ## `copyright` the copyright string Sets the strings which are displayed in the documenters tab of the credits dialog. ## `documenters` a `None`-terminated array of strings Sets the license information to be displayed in the secondary license dialog. If `license` is `None`, the license button is hidden. ## `license` the license information or `None` Sets the license of the application showing the `self` dialog from a list of known licenses. This function overrides the license set using `AboutDialogExt::set_license`. ## `license_type` the type of license Sets the surface to be displayed as logo in the about dialog. If it is `None`, the default window icon set with `gtk_window_set_default_icon` will be used. ## `logo` a `gdk::Paintable`, or `None` Sets the surface to be displayed as logo in the about dialog. If it is `None`, the default window icon set with `gtk_window_set_default_icon` will be used. ## `icon_name` an icon name, or `None` Sets the name to display in the about dialog. If this is not set, it defaults to `g_get_application_name`. ## `name` the program name Sets the system information to be displayed in the about dialog. If `system_information` is `None`, the system information tab is hidden. See ``GtkAboutdialog`:system-information`. ## `system_information` system information or `None` Sets the translator credits string which is displayed in the translators tab of the secondary credits dialog. The intended use for this string is to display the translator of the language which is currently used in the user interface. Using `gettext`, a simple way to achieve that is to mark the string for translation: ```C GtkWidget *about = gtk_about_dialog_new (); gtk_about_dialog_set_translator_credits (GTK_ABOUT_DIALOG (about), _("translator-credits")); ``` It is a good idea to use the customary msgid “translator-credits” for this purpose, since translators will already know the purpose of that msgid, and since `AboutDialog` will detect if “translator-credits” is untranslated and hide the tab. ## `translator_credits` the translator credits Sets the version string to display in the about dialog. ## `version` the version string Sets the URL to use for the website link. ## `website` a URL string starting with "http://" Sets the label to be used for the website link. ## `website_label` the label used for the website link Sets whether the license text in `self` is automatically wrapped. ## `wrap_license` whether to wrap the license The signal which gets emitted to activate a URI. Applications may connect to it to override the default behaviour, which is to call `gtk_show_uri_on_window`. ## `uri` the URI that is activated # Returns `true` if the link has been activated The people who contributed artwork to the program, as a `None`-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. The people who contributed artwork to the program, as a `None`-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. The authors of the program, as a `None`-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. The authors of the program, as a `None`-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. Comments about the program. This string is displayed in a label in the main dialog, thus it should be a short explanation of the main purpose of the program, not a detailed list of features. Comments about the program. This string is displayed in a label in the main dialog, thus it should be a short explanation of the main purpose of the program, not a detailed list of features. Copyright information for the program. Copyright information for the program. The people documenting the program, as a `None`-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. The people documenting the program, as a `None`-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. The license of the program. This string is displayed in a text view in a secondary dialog, therefore it is fine to use a long multi-paragraph text. Note that the text is only wrapped in the text view if the "wrap-license" property is set to `true`; otherwise the text itself must contain the intended linebreaks. When setting this property to a non-`None` value, the `AboutDialog:license-type` property is set to `License::Custom` as a side effect. The text may contain links in this format and email references in the form , and these will be converted into clickable links. The license of the program. This string is displayed in a text view in a secondary dialog, therefore it is fine to use a long multi-paragraph text. Note that the text is only wrapped in the text view if the "wrap-license" property is set to `true`; otherwise the text itself must contain the intended linebreaks. When setting this property to a non-`None` value, the `AboutDialog:license-type` property is set to `License::Custom` as a side effect. The text may contain links in this format and email references in the form , and these will be converted into clickable links. The license of the program, as a value of the `License` enumeration. The `AboutDialog` will automatically fill out a standard disclaimer and link the user to the appropriate online resource for the license text. If `License::Unknown` is used, the link used will be the same specified in the `AboutDialog:website` property. If `License::Custom` is used, the current contents of the `AboutDialog:license` property are used. For any other `License` value, the contents of the `AboutDialog:license` property are also set by this property as a side effect. The license of the program, as a value of the `License` enumeration. The `AboutDialog` will automatically fill out a standard disclaimer and link the user to the appropriate online resource for the license text. If `License::Unknown` is used, the link used will be the same specified in the `AboutDialog:website` property. If `License::Custom` is used, the current contents of the `AboutDialog:license` property are used. For any other `License` value, the contents of the `AboutDialog:license` property are also set by this property as a side effect. A logo for the about box. If it is `None`, the default window icon set with `gtk_window_set_default_icon` will be used. A logo for the about box. If it is `None`, the default window icon set with `gtk_window_set_default_icon` will be used. A named icon to use as the logo for the about box. This property overrides the `AboutDialog:logo` property. A named icon to use as the logo for the about box. This property overrides the `AboutDialog:logo` property. The name of the program. If this is not set, it defaults to `g_get_application_name`. The name of the program. If this is not set, it defaults to `g_get_application_name`. Information about the system on which the program is running. This is displayed in a separate tab, therefore it is fine to use a long multi-paragraph text. Note that the text should contain the intended linebreaks. The text may contain links in this format and email references in the form , and these will be converted into clickable links. Information about the system on which the program is running. This is displayed in a separate tab, therefore it is fine to use a long multi-paragraph text. Note that the text should contain the intended linebreaks. The text may contain links in this format and email references in the form , and these will be converted into clickable links. Credits to the translators. This string should be marked as translatable. The string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. Credits to the translators. This string should be marked as translatable. The string may contain email addresses and URLs, which will be displayed as links, see the introduction for more details. The version of the program. The version of the program. The URL for the link to the website of the program. This should be a string starting with "http://. The URL for the link to the website of the program. This should be a string starting with "http://. The label for the link to the website of the program. The label for the link to the website of the program. Whether to wrap the text in the license dialog. Whether to wrap the text in the license dialog. A `AccelGroup` represents a group of keyboard accelerators, typically attached to a toplevel `Window` (with `GtkWindowExt::add_accel_group`). 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 `Label::new_with_mnemonic`. Menu items can have both accelerators and mnemonics, of course. # Implements [`AccelGroupExt`](trait.AccelGroupExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `AccelGroup` methods. # Implementors [`AccelGroup`](struct.AccelGroup.html) Creates a new `AccelGroup`. # Returns a new `AccelGroup` object Finds the `AccelGroup` to which `closure` is connected; see `AccelGroupExt::connect`. ## `closure` a `gobject::Closure` # Returns the `AccelGroup` to which `closure` is connected, or `None` Finds the first accelerator in `self` that matches `accel_key` and `accel_mods`, and activates it. ## `accel_quark` the quark for the accelerator name ## `acceleratable` the `gobject::Object`, usually a `Window`, on which to activate the accelerator ## `accel_key` accelerator keyval from a key event ## `accel_mods` keyboard state mask from a key event # Returns `true` if an accelerator was activated and handled this keypress Installs an accelerator in this group. When `self` is being activated in response to a call to `gtk_accel_groups_activate`, `closure` will be invoked if the `accel_key` and `accel_mods` from `gtk_accel_groups_activate` match those of this connection. The signature used for the `closure` is that of ``GtkAccelGroupActivate``. Note that, due to implementation details, a single closure can only be connected to one accelerator group. ## `accel_key` key value of the accelerator ## `accel_mods` modifier combination of the accelerator ## `accel_flags` a flag mask to configure this accelerator ## `closure` closure to be executed upon accelerator activation Installs an accelerator in this group, using an accelerator path to look up the appropriate key and modifiers (see `AccelMap::add_entry`). When `self` is being activated in response to a call to `gtk_accel_groups_activate`, `closure` will be invoked if the `accel_key` and `accel_mods` from `gtk_accel_groups_activate` match the key and modifiers for the path. The signature used for the `closure` is that of ``GtkAccelGroupActivate``. Note that `accel_path` string will be stored in a `glib::Quark`. Therefore, if you pass a static string, you can save some memory by interning it first with `g_intern_static_string`. ## `accel_path` path used for determining key and modifiers ## `closure` closure to be executed upon accelerator activation Removes an accelerator previously installed through `AccelGroupExt::connect`. ## `closure` the closure to remove from this accelerator group, or `None` to remove all closures # Returns `true` if the closure was found and got disconnected Removes an accelerator previously installed through `AccelGroupExt::connect`. ## `accel_key` key value of the accelerator ## `accel_mods` modifier combination of the accelerator # Returns `true` if there was an accelerator which could be removed, `false` otherwise Finds the first entry in an accelerator group for which `find_func` returns `true` and returns its `AccelKey`. ## `find_func` a function to filter the entries of `self` with ## `data` data to pass to `find_func` # Returns the key of the first entry passing `find_func`. The key is owned by GTK+ and must not be freed. Locks are added and removed using `AccelGroupExt::lock` and `AccelGroupExt::unlock`. # Returns `true` if there are 1 or more locks on the `self`, `false` otherwise. Gets a `gdk::ModifierType` representing the mask for this `self`. For example, `gdk::ModifierType::ControlMask`, `gdk::ModifierType::ShiftMask`, etc. # Returns the modifier mask for this accel group. Locks the given accelerator group. Locking an acelerator group prevents the accelerators contained within it to be changed during runtime. Refer to `AccelMap::change_entry` about runtime accelerator changes. If called more than once, `self` remains locked until `AccelGroupExt::unlock` has been called an equivalent number of times. Queries an accelerator group for all entries matching `accel_key` and `accel_mods`. ## `accel_key` key value of the accelerator ## `accel_mods` modifier combination of the accelerator ## `n_entries` location to return the number of entries found, or `None` # Returns an array of `n_entries` `AccelGroupEntry` elements, or `None`. The array is owned by GTK+ and must not be freed. Undoes the last call to `AccelGroupExt::lock` on this `self`. The accel-activate signal is an implementation detail of `AccelGroup` and not meant to be used by applications. ## `acceleratable` the object on which the accelerator was activated ## `keyval` the accelerator keyval ## `modifier` the modifier combination of the accelerator # Returns `true` if the accelerator was activated The accel-changed signal is emitted when an entry is added to or removed from the accel group. Widgets like `AccelLabel` which display an associated accelerator should connect to this signal, and rebuild their visual representation if the `accel_closure` is theirs. ## `keyval` the accelerator keyval ## `modifier` the modifier combination of the accelerator ## `accel_closure` the `gobject::Closure` of the accelerator The `AccelLabel` is a widget that shows an accelerator next to a description of said accelerator, e.g. “Save Document 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 `AccelLabelExt::set_accel`). Instead, the `AccelLabel` displays the accelerators which have been added to a particular widget. This widget is set by calling `AccelLabelExt::set_accel_widget`. For example, a `MenuItem` widget may have an accelerator added to emit the “activate” signal when the “Ctrl+S” key combination is pressed. A `AccelLabel` is created and added to the `MenuItem`, and `AccelLabelExt::set_accel_widget` is called with the `MenuItem` as the second argument. The `AccelLabel` will now display “Ctrl+S” after its label. Note that creating a `MenuItem` with `MenuItem::new_with_label` (or one of the similar functions for `CheckMenuItem` and `RadioMenuItem`) automatically adds a `AccelLabel` to the `MenuItem` and calls `AccelLabelExt::set_accel_widget` to set it up for you. A `AccelLabel` will only display accelerators which have `AccelFlags::Visible` set (see `AccelFlags`). A `AccelLabel` 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 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_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 accellabel ╰── box ├── label ╰── accelerator ``` `AccelLabel` has a main CSS node with the name accellabel. It adds a subnode with name box, containing two child nodes with name label and accelerator. # Implements [`AccelLabelExt`](trait.AccelLabelExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html) Trait containing all `AccelLabel` methods. # Implementors [`AccelLabel`](struct.AccelLabel.html) Creates a new `AccelLabel`. ## `string` the label string. Must be non-`None`. # Returns a new `AccelLabel`. Gets the keyval and modifier mask set with `AccelLabelExt::set_accel`. ## `accelerator_key` return location for the keyval ## `accelerator_mods` return location for the modifier mask Fetches the widget monitored by this accelerator label. See `AccelLabelExt::set_accel_widget`. # Returns the object monitored by the accelerator label, or `None`. Returns the width needed to display the accelerator key(s). This is used by menus to align all of the `MenuItem` widgets, and shouldn't be needed by applications. # Returns the width needed to display the accelerator key(s). Returns the current label, set via `AccelLabelExt::set_label` # Returns `self`'s label Returns whether the accel label interprets underscores in it's label property as mnemonic indicators. See `AccelLabelExt::set_use_underline` and `LabelExt::set_use_underline`; # Returns whether the accel label uses mnemonic underlines Recreates the string representing the accelerator keys. This should not be needed since the string is automatically updated whenever accelerators are added or removed from the associated widget. # Returns always returns `false`. Manually sets a keyval and modifier mask as the accelerator rendered by `self`. If a keyval and modifier are explicitly set then these values are used regardless of any associated accel closure or widget. Providing an `accelerator_key` of 0 removes the manual setting. ## `accelerator_key` a keyval, or 0 ## `accelerator_mods` the modifier mask for the accel Sets the closure to be monitored by this accelerator label. The closure must be connected to an accelerator group; see `AccelGroupExt::connect`. Passing `None` for `accel_closure` will dissociate `self` from its current closure, if any. ## `accel_closure` the closure to monitor for accelerator changes, or `None` Sets the widget to be monitored by this accelerator label. Passing `None` for `accel_widget` will dissociate `self` from its current widget, if any. ## `accel_widget` the widget to be monitored, or `None` Sets the label part of the accel label. ## `text` The new label text Controls whether to interpret underscores in the text label of `self` as mnemonic indicators. See also `LabelExt::set_use_underline` ## `setting` Whether to use underlines in the label or not Accelerator maps are used to define runtime configurable accelerators. Functions for manipulating them are are usually used by higher level convenience mechanisms 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 “``/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: “``/File/Dialogs/Tool Options...”. All accelerators are stored inside one global `AccelMap` that can be obtained using `AccelMap::get`. See [Monitoring changes][monitoring-changes] for additional details. # Manipulating accelerators New accelerators can be added using `AccelMap::add_entry`. To search for specific accelerator, use `AccelMap::lookup_entry`. Modifications of existing accelerators should be done using `AccelMap::change_entry`. In order to avoid having some accelerators changed, they can be locked using `AccelMap::lock_path`. Unlocking is done using `AccelMap::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, `AccelMap::save` and `AccelMap::load` are provided. Saving and loading can also be done by providing file descriptor to `AccelMap::save_fd` and `AccelMap::load_fd`. # Monitoring changes `AccelMap` object is only useful for monitoring changes of accelerators. By connecting to `AccelMap::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 `AccelMap::changed` signal. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Registers a new accelerator with the global accelerator map. This function should only be called once per `accel_path` with the canonical `accel_key` and `accel_mods` for this path. To change the accelerator during runtime programatically, use `AccelMap::change_entry`. Set `accel_key` and `accel_mods` to 0 to request a removal of the accelerator. Note that `accel_path` string will be stored in a `glib::Quark`. Therefore, if you pass a static string, you can save some memory by interning it first with `g_intern_static_string`. ## `accel_path` valid accelerator path ## `accel_key` the accelerator key ## `accel_mods` the accelerator modifiers Adds a filter to the global list of accel path filters. Accel map entries whose accel path matches one of the filters are skipped by `AccelMap::foreach`. This function is intended for GTK+ modules that create their own menus, but don’t want them to be saved into the applications accelerator map dump. ## `filter_pattern` a pattern (see `glib::PatternSpec`) Changes the `accel_key` and `accel_mods` currently associated with `accel_path`. Due to conflicts with other accelerators, a change may not always be possible, `replace` indicates whether other accelerators may be deleted to resolve such conflicts. A change will only occur if all conflicts could be resolved (which might not be the case if conflicting accelerators are locked). Successful changes are indicated by a `true` return value. Note that `accel_path` string will be stored in a `glib::Quark`. Therefore, if you pass a static string, you can save some memory by interning it first with `g_intern_static_string`. ## `accel_path` a valid accelerator path ## `accel_key` the new accelerator key ## `accel_mods` the new accelerator modifiers ## `replace` `true` if other accelerators may be deleted upon conflicts # Returns `true` if the accelerator could be changed, `false` otherwise Loops over the entries in the accelerator map whose accel path doesn’t match any of the filters added with `AccelMap::add_filter`, and execute `foreach_func` on each. The signature of `foreach_func` is that of ``GtkAccelMapForeach``, the `changed` parameter indicates whether this accelerator was changed during runtime (thus, would need saving during an accelerator map dump). ## `data` data to be passed into `foreach_func` ## `foreach_func` function to be executed for each accel map entry which is not filtered out Loops over all entries in the accelerator map, and execute `foreach_func` on each. The signature of `foreach_func` is that of ``GtkAccelMapForeach``, the `changed` parameter indicates whether this accelerator was changed during runtime (thus, would need saving during an accelerator map dump). ## `data` data to be passed into `foreach_func` ## `foreach_func` function to be executed for each accel map entry Gets the singleton global `AccelMap` object. This object is useful only for notification of changes to the accelerator map via the ::changed signal; it isn’t a parameter to the other accelerator map functions. # Returns the global `AccelMap` object Parses a file previously saved with `AccelMap::save` for accelerator specifications, and propagates them accordingly. ## `file_name` a file containing accelerator specifications, in the GLib file name encoding Filedescriptor variant of `AccelMap::load`. Note that the file descriptor will not be closed by this function. ## `fd` a valid readable file descriptor `glib::Scanner` variant of `AccelMap::load`. ## `scanner` a `glib::Scanner` which has already been provided with an input file Locks the given accelerator path. If the accelerator map doesn’t yet contain an entry for `accel_path`, a new one is created. Locking an accelerator path prevents its accelerator from being changed during runtime. A locked accelerator path can be unlocked by `AccelMap::unlock_path`. Refer to `AccelMap::change_entry` for information about runtime accelerator changes. If called more than once, `accel_path` remains locked until `AccelMap::unlock_path` has been called an equivalent number of times. Note that locking of individual accelerator paths is independent from locking the `AccelGroup` containing them. For runtime accelerator changes to be possible, both the accelerator path and its `AccelGroup` have to be unlocked. ## `accel_path` a valid accelerator path Looks up the accelerator entry for `accel_path` and fills in `key`. ## `accel_path` a valid accelerator path ## `key` the accelerator key to be filled in (optional) # Returns `true` if `accel_path` is known, `false` otherwise Saves current accelerator specifications (accelerator path, key and modifiers) to `file_name`. The file is written in a format suitable to be read back in by `AccelMap::load`. ## `file_name` the name of the file to contain accelerator specifications, in the GLib file name encoding Filedescriptor variant of `AccelMap::save`. Note that the file descriptor will not be closed by this function. ## `fd` a valid writable file descriptor Undoes the last call to `AccelMap::lock_path` on this `accel_path`. Refer to `AccelMap::lock_path` for information about accelerator path locking. ## `accel_path` a valid accelerator path Notifies of a change in the global accelerator map. The path is also used as the detail for the signal, so it is possible to connect to changed::`accel_path`. ## `accel_path` the path of the accelerator that changed ## `accel_key` the key value for the new accelerator ## `accel_mods` the modifier mask for the new accelerator The `Accessible` class is the base class for accessible implementations for `Widget` subclasses. It is a thin wrapper around `atk::Object`, which adds facilities for associating a widget with its accessible object. An accessible implementation for a third-party widget should derive from `Accessible` and implement the suitable interfaces from ATK, such as `atk::Text` or `atk::Selection`. To establish the connection between the widget class and its corresponding acccessible implementation, override the get_accessible vfunc in `WidgetClass`. # Implements [`AccessibleExt`](trait.AccessibleExt.html), [`atk::ObjectExt`](../atk/trait.ObjectExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Accessible` methods. # Implementors [`Accessible`](struct.Accessible.html) Gets the `Widget` corresponding to the `Accessible`. The returned widget does not have a reference added, so you do not need to unref it. # Returns pointer to the `Widget` corresponding to the `Accessible`, or `None`. Sets the `Widget` corresponding to the `Accessible`. `self` will not hold a reference to `widget`. It is the caller’s responsibility to ensure that when `widget` is destroyed, the widget is unset by calling this function again with `widget` set to `None`. ## `widget` a `Widget` or `None` to unset `ActionBar` is designed to present contextual actions. It is expected to be displayed below the content and expand horizontally to fill the area. It allows placing children at the start or the end. In addition, it contains an internal centered box which is centered with respect to the full width of the box, even if the children at either side take up different amounts of space. # CSS nodes `ActionBar` has a single CSS node with name actionbar. # Implements [`ActionBarExt`](trait.ActionBarExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html) Trait containing all `ActionBar` methods. # Implementors [`ActionBar`](struct.ActionBar.html) Creates a new `ActionBar` widget. # Returns a new `ActionBar` Retrieves the center bar widget of the bar. # Returns the center `Widget` or `None`. Gets the value of the `ActionBar:revealed` property. # Returns the current value of the `ActionBar:revealed` property. Adds `child` to `self`, packed with reference to the end of the `self`. ## `child` the `Widget` to be added to `self` Adds `child` to `self`, packed with reference to the start of the `self`. ## `child` the `Widget` to be added to `self` Sets the center widget for the `ActionBar`. ## `center_widget` a widget to use for the center Sets the `ActionBar:revealed` property to `revealed`. Changing this will make `self` reveal (`true`) or conceal (`false`) itself via a sliding transition. Note: this does not show or hide `self` in the `Widget:visible` sense, so revealing has no effect if `Widget:visible` is `false`. ## `revealed` The new value of the property This interface provides a convenient way of associating widgets with actions on a `ApplicationWindow` or `Application`. It primarily consists of two properties: `Actionable:action-name` and `Actionable:action-target`. There are also some convenience APIs for setting these properties. The action will be looked up in action groups that are found among the widgets ancestors. Most commonly, these will be the actions with the “win.” or “app.” prefix that are associated with the `ApplicationWindow` or `Application`, but other action groups that are added with `WidgetExt::insert_action_group` will be consulted as well. # Implements [`ActionableExt`](trait.ActionableExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html) Trait containing all `Actionable` methods. # Implementors [`Actionable`](struct.Actionable.html), [`Button`](struct.Button.html), [`CheckButton`](struct.CheckButton.html), [`CheckMenuItem`](struct.CheckMenuItem.html), [`LinkButton`](struct.LinkButton.html), [`ListBoxRow`](struct.ListBoxRow.html), [`LockButton`](struct.LockButton.html), [`MenuButton`](struct.MenuButton.html), [`MenuItem`](struct.MenuItem.html), [`MenuToolButton`](struct.MenuToolButton.html), [`ModelButton`](struct.ModelButton.html), [`RadioButton`](struct.RadioButton.html), [`RadioMenuItem`](struct.RadioMenuItem.html), [`RadioToolButton`](struct.RadioToolButton.html), [`ScaleButton`](struct.ScaleButton.html), [`SeparatorMenuItem`](struct.SeparatorMenuItem.html), [`Switch`](struct.Switch.html), [`ToggleButton`](struct.ToggleButton.html), [`ToggleToolButton`](struct.ToggleToolButton.html), [`ToolButton`](struct.ToolButton.html), [`VolumeButton`](struct.VolumeButton.html) Gets the action name for `self`. See `Actionable::set_action_name` for more information. # Returns the action name, or `None` if none is set Gets the current target value of `self`. See `Actionable::set_action_target_value` for more information. # Returns the current target value Specifies the name of the action with which this widget should be associated. If `action_name` is `None` then the widget will be unassociated from any previous action. Usually this function is used when the widget is located (or will be located) within the hierarchy of a `ApplicationWindow`. Names are of the form “win.save” or “app.quit” for actions on the containing `ApplicationWindow` or its associated `Application`, respectively. This is the same form used for actions in the `gio::Menu` associated with the window. ## `action_name` an action name, or `None` Sets the target of an actionable widget. This is a convenience function that calls `glib::Variant::new` for `format_string` and uses the result to call `Actionable::set_action_target_value`. If you are setting a string-valued target and want to set the action name at the same time, you can use gtk_actionable_set_detailed_action_name (). ## `format_string` a GVariant format string Sets the target value of an actionable widget. If `target_value` is `None` then the target value is unset. The target value has two purposes. First, it is used as the parameter to activation of the action associated with the `Actionable` widget. Second, it is used to determine if the widget should be rendered as “active” — the widget is active if the state is equal to the given target. Consider the example of associating a set of buttons with a `gio::Action` with string state in a typical “radio button” situation. Each button will be associated with the same action, but with a different target value for that action. Clicking on a particular button will activate the action with the target of that button, which will typically cause the action’s state to change to that value. Since the action’s state is now equal to the target value of the button, the button will now be rendered as active (and the other buttons, with different targets, rendered inactive). ## `target_value` a `glib::Variant` to set as the target value, or `None` Sets the action-name and associated string target value of an actionable widget. `detailed_action_name` is a string in the format accepted by `gio::Action::parse_detailed_name`. (Note that prior to version 3.22.25, this function is only usable for actions with a simple "s" target, and `detailed_action_name` must be of the form `"action::target"` where `action` is the action name and `target` is the string to use as the target.) ## `detailed_action_name` the detailed action name The `Adjustment` 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 `SpinButton`, `Viewport`, and `Range` (which is a base class for `Scrollbar` and `Scale`). The `Adjustment` object does not update the value itself. Instead it is left up to the owner of the `Adjustment` to control the value. # Implements [`AdjustmentExt`](trait.AdjustmentExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Adjustment` methods. # Implementors [`Adjustment`](struct.Adjustment.html) Creates a new `Adjustment`. ## `value` the initial value ## `lower` the minimum value ## `upper` the maximum value ## `step_increment` the step increment ## `page_increment` the page increment ## `page_size` the page size # Returns a new `Adjustment` Updates the `Adjustment:value` property to ensure that the range between `lower` and `upper` is in the current page (i.e. between `Adjustment:value` and `Adjustment:value` + `Adjustment:page-size`). If the range is larger than the page size, then only the start of it will be in the current page. A `Adjustment::value-changed` signal will be emitted if the value is changed. ## `lower` the lower value ## `upper` the upper value Sets all properties of the adjustment at once. Use this function to avoid multiple emissions of the `Adjustment::changed` signal. See `AdjustmentExt::set_lower` for an alternative way of compressing multiple emissions of `Adjustment::changed` into one. ## `value` the new value ## `lower` the new minimum value ## `upper` the new maximum value ## `step_increment` the new step increment ## `page_increment` the new page increment ## `page_size` the new page size Retrieves the minimum value of the adjustment. # Returns The current minimum value of the adjustment Gets the smaller of step increment and page increment. # Returns the minimum increment of `self` Retrieves the page increment of the adjustment. # Returns The current page increment of the adjustment Retrieves the page size of the adjustment. # Returns The current page size of the adjustment Retrieves the step increment of the adjustment. # Returns The current step increment of the adjustment. Retrieves the maximum value of the adjustment. # Returns The current maximum value of the adjustment Gets the current value of the adjustment. See `AdjustmentExt::set_value`. # Returns The current value of the adjustment Sets the minimum value of the adjustment. When setting multiple adjustment properties via their individual setters, multiple `Adjustment::changed` signals will be emitted. However, since the emission of the `Adjustment::changed` signal is tied to the emission of the `gobject::Object::notify` signals of the changed properties, it’s possible to compress the `Adjustment::changed` signals into one by calling `gobject::ObjectExt::freeze_notify` and `gobject::ObjectExt::thaw_notify` around the calls to the individual setters. Alternatively, using a single `gobject::ObjectExt::set` for all the properties to change, or using `AdjustmentExt::configure` has the same effect of compressing `Adjustment::changed` emissions. ## `lower` the new minimum value Sets the page increment of the adjustment. See `AdjustmentExt::set_lower` about how to compress multiple emissions of the `Adjustment::changed` signal when setting multiple adjustment properties. ## `page_increment` the new page increment Sets the page size of the adjustment. See `AdjustmentExt::set_lower` about how to compress multiple emissions of the `Adjustment`::changed signal when setting multiple adjustment properties. ## `page_size` the new page size Sets the step increment of the adjustment. See `AdjustmentExt::set_lower` about how to compress multiple emissions of the `Adjustment::changed` signal when setting multiple adjustment properties. ## `step_increment` the new step increment Sets the maximum value of the adjustment. Note that values will be restricted by `upper - page-size` if the page-size property is nonzero. See `AdjustmentExt::set_lower` about how to compress multiple emissions of the `Adjustment::changed` signal when setting multiple adjustment properties. ## `upper` the new maximum value Sets the `Adjustment` value. The value is clamped to lie between `Adjustment:lower` and `Adjustment:upper`. Note that for adjustments which are used in a `Scrollbar`, the effective range of allowed values goes from `Adjustment:lower` to `Adjustment:upper` - `Adjustment:page-size`. ## `value` the new value Emitted when one or more of the `Adjustment` properties have been changed, other than the `Adjustment:value` property. Emitted when the `Adjustment:value` property has been changed. The minimum value of the adjustment. The minimum value of the adjustment. The page increment of the adjustment. The page increment of the adjustment. The page size of the adjustment. Note that the page-size is irrelevant and should be set to zero if the adjustment is used for a simple scalar value, e.g. in a `SpinButton`. The page size of the adjustment. Note that the page-size is irrelevant and should be set to zero if the adjustment is used for a simple scalar value, e.g. in a `SpinButton`. The step increment of the adjustment. The step increment of the adjustment. The maximum value of the adjustment. Note that values will be restricted by `upper - page-size` if the page-size property is nonzero. The maximum value of the adjustment. Note that values will be restricted by `upper - page-size` if the page-size property is nonzero. The value of the adjustment. The value of the adjustment. Controls how a widget deals with extra space in a single (x or y) dimension. Alignment only matters if the widget receives a “too large” allocation, for example if you packed the widget with the `Widget:expand` flag inside a `Box`, then the widget might get extra space. If you have for example a 16x16 icon inside a 32x32 space, the icon could be scaled and stretched, it could be centered, or it could be positioned to one side of the space. Note that in horizontal context `Align::Start` and `Align::End` are interpreted relative to text direction. GTK_ALIGN_BASELINE support for it is optional for containers and widgets, and it is only supported for vertical alignment. When its not supported by a child or a container it is treated as `Align::Fill`. stretch to fill all space if possible, center if no meaningful way to stretch snap to left or top side, leaving space on right or bottom snap to right or bottom side, leaving space on left or top center natural width of widget inside the allocation align the widget according to the baseline `AppChooser` 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 `AppChooserWidget`, `AppChooserDialog` and `AppChooserButton`. Applications are represented by GIO `gio::AppInfo` objects here. GIO has a concept of recommended and fallback applications for a given content type. Recommended applications are those that claim to handle the content type itself, while fallback also includes applications that handle a more generic content type. GIO also knows the default and last-used application for a given content type. The `AppChooserWidget` provides detailed control over whether the shown list of applications should include default, recommended or fallback applications. To obtain the application that has been selected in a `AppChooser`, use `AppChooser::get_app_info`. # Implements [`AppChooserExt`](trait.AppChooserExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html) Trait containing all `AppChooser` methods. # Implementors [`AppChooserButton`](struct.AppChooserButton.html), [`AppChooserDialog`](struct.AppChooserDialog.html), [`AppChooserWidget`](struct.AppChooserWidget.html), [`AppChooser`](struct.AppChooser.html) Returns the currently selected application. # Returns a `gio::AppInfo` for the currently selected application, or `None` if none is selected. Free with `gobject::ObjectExt::unref` Returns the current value of the `AppChooser:content-type` property. # Returns the content type of `self`. Free with `g_free` Reloads the list of applications. The content type of the `AppChooser` object. See [GContentType][gio-GContentType] for more information about content types. The content type of the `AppChooser` object. See [GContentType][gio-GContentType] for more information about content types. The `AppChooserButton` is a widget that lets the user select an application. It implements the `AppChooser` interface. Initially, a `AppChooserButton` selects the first application in its list, which will either be the most-recently used application or, if `AppChooserButton:show-default-item` is `true`, the default application. The list of applications shown in a `AppChooserButton` includes the recommended applications for the given content type. When `AppChooserButton:show-default-item` is set, the default application is also included. To let the user chooser other applications, you can set the `AppChooserButton:show-dialog-item` property, which allows to open a full `AppChooserDialog`. It is possible to add custom items to the list, using `AppChooserButtonExt::append_custom_item`. These items cause the `AppChooserButton::custom-item-activated` signal to be emitted when they are selected. To track changes in the selected application, use the ``GtkAppChooserbutton`::changed` signal. # Implements [`AppChooserButtonExt`](trait.AppChooserButtonExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`AppChooserExt`](trait.AppChooserExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html) Trait containing all `AppChooserButton` methods. # Implementors [`AppChooserButton`](struct.AppChooserButton.html) Creates a new `AppChooserButton` for applications that can handle content of the given type. ## `content_type` the content type to show applications for # Returns a newly created `AppChooserButton` Appends a custom item to the list of applications that is shown in the popup; the item name must be unique per-widget. Clients can use the provided name as a detail for the `AppChooserButton::custom-item-activated` signal, to add a callback for the activation of a particular custom item in the list. See also `AppChooserButtonExt::append_separator`. ## `name` the name of the custom item ## `label` the label for the custom item ## `icon` the icon for the custom item Appends a separator to the list of applications that is shown in the popup. Returns the text to display at the top of the dialog. # Returns the text to display at the top of the dialog, or `None`, in which case a default text is displayed Returns the current value of the `AppChooserButton:show-default-item` property. # Returns the value of `AppChooserButton:show-default-item` Returns the current value of the `AppChooserButton:show-dialog-item` property. # Returns the value of `AppChooserButton:show-dialog-item` Selects a custom item previously added with `AppChooserButtonExt::append_custom_item`. Use `AppChooser::refresh` to bring the selection to its initial state. ## `name` the name of the custom item Sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text. ## `heading` a string containing Pango markup Sets whether the dropdown menu of this button should show the default application for the given content type at top. ## `setting` the new value for `AppChooserButton:show-default-item` Sets whether the dropdown menu of this button should show an entry to trigger a `AppChooserDialog`. ## `setting` the new value for `AppChooserButton:show-dialog-item` Emitted when a custom item, previously added with `AppChooserButtonExt::append_custom_item`, is activated from the dropdown menu. ## `item_name` the name of the activated item The text to show at the top of the dialog that can be opened from the button. The string may contain Pango markup. The text to show at the top of the dialog that can be opened from the button. The string may contain Pango markup. The `AppChooserButton:show-default-item` property determines whether the dropdown menu should show the default application on top for the provided content type. The `AppChooserButton:show-default-item` property determines whether the dropdown menu should show the default application on top for the provided content type. The `AppChooserButton:show-dialog-item` property determines whether the dropdown menu should show an item that triggers a `AppChooserDialog` when clicked. The `AppChooserButton:show-dialog-item` property determines whether the dropdown menu should show an item that triggers a `AppChooserDialog` when clicked. `AppChooserDialog` shows a `AppChooserWidget` inside a `Dialog`. Note that `AppChooserDialog` does not have any interesting methods of its own. Instead, you should get the embedded `AppChooserWidget` using `AppChooserDialogExt::get_widget` and call its methods if the generic `AppChooser` interface is not sufficient for your needs. To set the heading that is shown above the `AppChooserWidget`, use `AppChooserDialogExt::set_heading`. # Implements [`AppChooserDialogExt`](trait.AppChooserDialogExt.html), [`DialogExt`](trait.DialogExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`RootExt`](trait.RootExt.html), [`AppChooserExt`](trait.AppChooserExt.html), [`DialogExtManual`](prelude/trait.DialogExtManual.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html) Trait containing all `AppChooserDialog` methods. # Implementors [`AppChooserDialog`](struct.AppChooserDialog.html) Creates a new `AppChooserDialog` for the provided `gio::File`, to allow the user to select an application for it. ## `parent` a `Window`, or `None` ## `flags` flags for this dialog ## `file` a `gio::File` # Returns a newly created `AppChooserDialog` Creates a new `AppChooserDialog` for the provided content type, to allow the user to select an application for it. ## `parent` a `Window`, or `None` ## `flags` flags for this dialog ## `content_type` a content type string # Returns a newly created `AppChooserDialog` Returns the text to display at the top of the dialog. # Returns the text to display at the top of the dialog, or `None`, in which case a default text is displayed Returns the `AppChooserWidget` of this dialog. # Returns the `AppChooserWidget` of `self` Sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text. ## `heading` a string containing Pango markup The GFile used by the `AppChooserDialog`. The dialog's `AppChooserWidget` content type will be guessed from the file, if present. The GFile used by the `AppChooserDialog`. The dialog's `AppChooserWidget` content type will be guessed from the file, if present. The text to show at the top of the dialog. The string may contain Pango markup. The text to show at the top of the dialog. The string may contain Pango markup. `AppChooserWidget` is a widget for selecting applications. It is the main building block for `AppChooserDialog`. Most applications only need to use the latter; but you can use this widget as part of a larger widget if you have special needs. `AppChooserWidget` offers detailed control over what applications are shown, using the `AppChooserWidget:show-default`, `AppChooserWidget:show-recommended`, `AppChooserWidget:show-fallback`, `AppChooserWidget:show-other` and `AppChooserWidget:show-all` properties. See the `AppChooser` documentation for more information about these groups of applications. To keep track of the selected application, use the `AppChooserWidget::application-selected` and `AppChooserWidget::application-activated` signals. # CSS nodes `AppChooserWidget` has a single CSS node with name appchooser. # Implements [`AppChooserWidgetExt`](trait.AppChooserWidgetExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`AppChooserExt`](trait.AppChooserExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html) Trait containing all `AppChooserWidget` methods. # Implementors [`AppChooserWidget`](struct.AppChooserWidget.html) Creates a new `AppChooserWidget` for applications that can handle content of the given type. ## `content_type` the content type to show applications for # Returns a newly created `AppChooserWidget` Returns the text that is shown if there are not applications that can handle the content type. # Returns the value of `AppChooserWidget:default-text` Returns the current value of the `AppChooserWidget:show-all` property. # Returns the value of `AppChooserWidget:show-all` Returns the current value of the `AppChooserWidget:show-default` property. # Returns the value of `AppChooserWidget:show-default` Returns the current value of the `AppChooserWidget:show-fallback` property. # Returns the value of `AppChooserWidget:show-fallback` Returns the current value of the `AppChooserWidget:show-other` property. # Returns the value of `AppChooserWidget:show-other` Returns the current value of the `AppChooserWidget:show-recommended` property. # Returns the value of `AppChooserWidget:show-recommended` Sets the text that is shown if there are not applications that can handle the content type. ## `text` the new value for `AppChooserWidget:default-text` Sets whether the app chooser should show all applications in a flat list. ## `setting` the new value for `AppChooserWidget:show-all` Sets whether the app chooser should show the default handler for the content type in a separate section. ## `setting` the new value for `AppChooserWidget:show-default` Sets whether the app chooser should show related applications for the content type in a separate section. ## `setting` the new value for `AppChooserWidget:show-fallback` Sets whether the app chooser should show applications which are unrelated to the content type. ## `setting` the new value for `AppChooserWidget:show-other` Sets whether the app chooser should show recommended applications for the content type in a separate section. ## `setting` the new value for `AppChooserWidget:show-recommended` Emitted when an application item is activated from the widget's list. This usually happens when the user double clicks an item, or an item is selected and the user presses one of the keys Space, Shift+Space, Return or Enter. ## `application` the activated `gio::AppInfo` Emitted when an application item is selected from the widget's list. ## `application` the selected `gio::AppInfo` Emitted when a context menu is about to popup over an application item. Clients can insert menu items into the provided `Menu` object in the callback of this signal; the context menu will be shown over the item if at least one item has been added to the menu. ## `menu` the `Menu` to populate ## `application` the current `gio::AppInfo` The `AppChooserWidget:default-text` property determines the text that appears in the widget when there are no applications for the given content type. See also `AppChooserWidgetExt::set_default_text`. The `AppChooserWidget:default-text` property determines the text that appears in the widget when there are no applications for the given content type. See also `AppChooserWidgetExt::set_default_text`. If the `AppChooserWidget:show-all` property is `true`, the app chooser presents all applications in a single list, without subsections for default, recommended or related applications. If the `AppChooserWidget:show-all` property is `true`, the app chooser presents all applications in a single list, without subsections for default, recommended or related applications. The ::show-default property determines whether the app chooser should show the default handler for the content type in a separate section. If `false`, the default handler is listed among the recommended applications. The ::show-default property determines whether the app chooser should show the default handler for the content type in a separate section. If `false`, the default handler is listed among the recommended applications. The `AppChooserWidget:show-fallback` property determines whether the app chooser should show a section for fallback applications. If `false`, the fallback applications are listed among the other applications. The `AppChooserWidget:show-fallback` property determines whether the app chooser should show a section for fallback applications. If `false`, the fallback applications are listed among the other applications. The `AppChooserWidget:show-other` property determines whether the app chooser should show a section for other applications. The `AppChooserWidget:show-other` property determines whether the app chooser should show a section for other applications. The `AppChooserWidget:show-recommended` property determines whether the app chooser should show a section for recommended applications. If `false`, the recommended applications are listed among the other applications. The `AppChooserWidget:show-recommended` property determines whether the app chooser should show a section for recommended applications. If `false`, the recommended applications are listed among the other applications. `Application` 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, `Application` handles GTK+ initialization, application uniqueness, session management, provides some basic scriptability and desktop shell integration by exporting actions and menus and manages a list of toplevel windows whose life-cycle is automatically tied to the life-cycle of your application. While `Application` works fine with plain ``GtkWindows``, it is recommended to use it together with `ApplicationWindow`. When GDK threads are enabled, `Application` will acquire the GDK lock when invoking actions that arrive from other processes. The GDK lock is not touched for local action invocations. In order to have actions invoked in a predictable context it is therefore recommended that the GDK lock be held while invoking actions locally with `gio::ActionGroup::activate_action`. The same applies to actions associated with `ApplicationWindow` and to the “activate” and “open” `gio::Application` methods. ## Automatic resources ## {`automatic`-resources} `Application` will automatically load menus from the `Builder` resource located at "gtk/menus.ui", relative to the application's resource base path (see `gio::ApplicationExt::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 `GtkApplicationExt::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 `GtkApplicationExt::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 `GtkApplicationExt::set_app_menu` and `GtkApplicationExt::set_menubar`. `Application` will also automatically setup an icon search path for the default icon theme by appending "icons" to the resource base path. This allows your application to easily store its icons as resources. See `IconThemeExt::add_resource_path` for more information. If there is a resource located at "gtk/help-overlay.ui" which defines a `ShortcutsWindow` with ID "help_overlay" then `Application` associates an instance of this shortcuts window with each `ApplicationWindow` and sets up keyboard accelerators (Control-F1 and Control-?) to open it. To create a menu item that displays the shortcuts window, associate the item with the action win.show-help-overlay. ## A simple application ## {`gtkapplication`} [A simple example](https://gitlab.gnome.org/GNOME/gtk/tree/master/examples/bp/bloatpad.c) `Application` optionally registers with a session manager of the users session (if you set the `Application:register-session` property) and offers various functionality related to the session life-cycle. An application can block various ways to end the session with the `GtkApplicationExt::inhibit` function. Typical use cases for this kind of inhibiting are long-running, uninterruptible operations, such as burning a CD or performing a disk backup. The session manager may not honor the inhibitor, but it can be expected to inform the user about the negative consequences of ending the session while inhibitors are present. ## See Also ## {`seealso`} [HowDoI: Using `Application`](https://wiki.gnome.org/HowDoI/`Application`), [Getting Started with GTK+: Basics](https://developer.gnome.org/gtk3/stable/gtk-getting-started.html`id`-1.2.3.3) # Implements [`GtkApplicationExt`](trait.GtkApplicationExt.html), [`gio::ApplicationExt`](../gio/trait.ApplicationExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`gio::ActionGroupExt`](../gio/trait.ActionGroupExt.html), [`gio::ActionMapExt`](../gio/trait.ActionMapExt.html) Trait containing all `Application` methods. # Implementors [`Application`](struct.Application.html) Creates a new `Application` instance. When using `Application`, it is not necessary to call `gtk_init` manually. It is called as soon as the application gets registered as the primary instance. Concretely, `gtk_init` is called in the default handler for the `gio::Application::startup` signal. Therefore, `Application` subclasses should chain up in their `gio::Application::startup` handler before using any GTK+ API. Note that commandline arguments are not passed to `gtk_init`. All GTK+ functionality that is available via commandline arguments can also be achieved by setting suitable environment variables such as `G_DEBUG`, so this should not be a big problem. If you absolutely must support GTK+ commandline arguments, you can explicitly call `gtk_init` before creating the application instance. If non-`None`, the application ID must be valid. See `gio::Application::id_is_valid`. If no application ID is given then some features (most notably application uniqueness) will be disabled. A null application ID is only allowed with GTK+ 3.6 or later. ## `application_id` The application ID. ## `flags` the application flags # Returns a new `Application` instance Adds a window to `self`. This call can only happen after the `self` has started; typically, you should add new application windows in response to the emission of the `gio::Application::activate` signal. This call is equivalent to setting the `Window:application` property of `window` to `self`. Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it with `GtkApplicationExt::remove_window`. GTK+ will keep the `self` running as long as it has any windows. ## `window` a `Window` Gets the accelerators that are currently associated with the given action. ## `detailed_action_name` a detailed action name, specifying an action and target to obtain accelerators for # Returns accelerators for `detailed_action_name`, as a `None`-terminated array. Free with `g_strfreev` when no longer needed Returns the list of actions (possibly empty) that `accel` maps to. Each item in the list is a detailed action name in the usual form. This might be useful to discover if an accel already exists in order to prevent installation of a conflicting accelerator (from an accelerator editor or a plugin system, for example). Note that having more than one action per accelerator may not be a bad thing and might make sense in cases where the actions never appear in the same context. In case there are no actions for a given accelerator, an empty array is returned. `None` is never returned. It is a programmer error to pass an invalid accelerator string. If you are unsure, check it with `gtk_accelerator_parse` first. ## `accel` an accelerator that can be parsed by `gtk_accelerator_parse` # Returns a `None`-terminated array of actions for `accel` Gets the “active” window for the application. The active window is the one that was most recently focused (within the application). This window may not have the focus at the moment if another application has it — this is just the most recently-focused window within this application. # Returns the active window, or `None` if there isn't one. Returns the menu model that has been set with `GtkApplicationExt::set_app_menu`. # Returns the application menu of `self` or `None` if no application menu has been set. Gets a menu from automatically loaded resources. See [Automatic resources][automatic-resources] for more information. ## `id` the id of the menu to look up # Returns Gets the menu with the given id from the automatically loaded resources Returns the menu model that has been set with `GtkApplicationExt::set_menubar`. # Returns the menubar for windows of `self` Returns the `ApplicationWindow` with the given ID. The ID of a `ApplicationWindow` can be retrieved with `ApplicationWindowExt::get_id`. ## `id` an identifier number # Returns the window with ID `id`, or `None` if there is no window with this ID Gets a list of the ``GtkWindows`` associated with `self`. The list is sorted by most recently focused window, such that the first element is the currently focused window. (Useful for choosing a parent for a transient window.) The list that is returned should not be modified in any way. It will only remain valid until the next focus change or window creation or deletion. # Returns a `glib::List` of `Window` Inform the session manager that certain types of actions should be inhibited. This is not guaranteed to work on all platforms and for all types of actions. Applications should invoke this method when they begin an operation that should not be interrupted, such as creating a CD or DVD. The types of actions that may be blocked are specified by the `flags` parameter. When the application completes the operation it should call `GtkApplicationExt::uninhibit` to remove the inhibitor. Note that an application can have multiple inhibitors, and all of them must be individually removed. Inhibitors are also cleared when the application exits. Applications should not expect that they will always be able to block the action. In most cases, users will be given the option to force the action to take place. Reasons should be short and to the point. If `window` is given, the session manager may point the user to this window to find out more about why the action is inhibited. ## `window` a `Window`, or `None` ## `flags` what types of actions should be inhibited ## `reason` a short, human-readable string that explains why these operations are inhibited # Returns A non-zero cookie that is used to uniquely identify this request. It should be used as an argument to `GtkApplicationExt::uninhibit` in order to remove the request. If the platform does not support inhibiting or the request failed for some reason, 0 is returned. Lists the detailed action names which have associated accelerators. See `GtkApplicationExt::set_accels_for_action`. # Returns a `None`-terminated array of strings, free with `g_strfreev` when done Determines if the desktop environment in which the application is running would prefer an application menu be shown. If this function returns `true` then the application should call `GtkApplicationExt::set_app_menu` with the contents of an application menu, which will be shown by the desktop environment. If it returns `false` then you should consider using an alternate approach, such as a menubar. The value returned by this function is purely advisory and you are free to ignore it. If you call `GtkApplicationExt::set_app_menu` even if the desktop environment doesn't support app menus, then a fallback will be provided. Applications are similarly free not to set an app menu even if the desktop environment wants to show one. In that case, a fallback will also be created by the desktop environment (GNOME, for example, uses a menu with only a "Quit" item in it). The value returned by this function never changes. Once it returns a particular value, it is guaranteed to always return the same value. You may only call this function after the application has been registered and after the base startup handler has run. You're most likely to want to use this from your own startup handler. It may also make sense to consult this function while constructing UI (in activate, open or an action activation handler) in order to determine if you should show a gear menu or not. This function will return `false` on Mac OS and a default app menu will be created automatically with the "usual" contents of that menu typical to most Mac OS applications. If you call `GtkApplicationExt::set_app_menu` anyway, then this menu will be replaced with your own. # Returns `true` if you should set an app menu Remove a window from `self`. If `window` belongs to `self` then this call is equivalent to setting the `Window:application` property of `window` to `None`. The application may stop running as a result of a call to this function. ## `window` a `Window` Sets zero or more keyboard accelerators that will trigger the given action. The first item in `accels` will be the primary accelerator, which may be displayed in the UI. To remove all accelerators for an action, use an empty, zero-terminated array for `accels`. For the `detailed_action_name`, see `gio::Action::parse_detailed_name` and `gio::Action::print_detailed_name`. ## `detailed_action_name` a detailed action name, specifying an action and target to associate accelerators with ## `accels` a list of accelerators in the format understood by `gtk_accelerator_parse` Sets or unsets the application menu for `self`. This can only be done in the primary instance of the application, after it has been registered. `gio::Application::startup` is a good place to call this. The application menu is a single menu containing items that typically impact the application as a whole, rather than acting on a specific window or document. For example, you would expect to see “Preferences” or “Quit” in an application menu, but not “Save” or “Print”. If supported, the application menu will be rendered by the desktop environment. Use the base `gio::ActionMap` interface to add actions, to respond to the user selecting these menu items. ## `app_menu` a `gio::MenuModel`, or `None` Sets or unsets the menubar for windows of `self`. This is a menubar in the traditional sense. This can only be done in the primary instance of the application, after it has been registered. `gio::Application::startup` is a good place to call this. Depending on the desktop environment, this may appear at the top of each window, or at the top of the screen. In some environments, if both the application menu and the menubar are set, the application menu will be presented as if it were the first item of the menubar. Other environments treat the two as completely separate — for example, the application menu may be rendered by the desktop shell while the menubar (if set) remains in each individual window. Use the base `gio::ActionMap` interface to add actions, to respond to the user selecting these menu items. ## `menubar` a `gio::MenuModel`, or `None` Removes an inhibitor that has been established with `GtkApplicationExt::inhibit`. Inhibitors are also cleared when the application exits. ## `cookie` a cookie that was returned by `GtkApplicationExt::inhibit` Emitted when the session manager is about to end the session, only if `Application::register-session` is `true`. Applications can connect to this signal and call `GtkApplicationExt::inhibit` with `ApplicationInhibitFlags::Logout` to delay the end of the session until state has been saved. Emitted when a `Window` is added to `application` through `GtkApplicationExt::add_window`. ## `window` the newly-added `Window` Emitted when a `Window` is removed from `application`, either as a side-effect of being destroyed or explicitly through `GtkApplicationExt::remove_window`. ## `window` the `Window` that is being removed Set this property to `true` to register with the session manager. This will make GTK+ track the session state (such as the `Application::screensaver-active` property). Set this property to `true` to register with the session manager. This will make GTK+ track the session state (such as the `Application::screensaver-active` property). This property is `true` if GTK+ believes that the screensaver is currently active. GTK+ only tracks session state (including this) when `Application::register-session` is set to `true`. Tracking the screensaver state is supported on Linux. `ApplicationWindow` is a `Window` subclass that offers some extra functionality for better integration with `Application` features. Notably, it can handle both the application menu as well as the menubar. See `GtkApplicationExt::set_app_menu` and `GtkApplicationExt::set_menubar`. This class implements the `gio::ActionGroup` and `gio::ActionMap` interfaces, to let you add window-specific actions that will be exported by the associated `Application`, together with its application-wide actions. Window-specific actions are prefixed with the “win.” prefix and application-wide actions are prefixed with the “app.” prefix. Actions must be addressed with the prefixed name when referring to them from a `gio::MenuModel`. Note that widgets that are placed inside a `ApplicationWindow` can also activate these actions, if they implement the `Actionable` interface. As with `Application`, 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 `Settings:gtk-shell-shows-app-menu` and `Settings:gtk-shell-shows-menubar` tell GTK+ whether the desktop environment is showing the application menu and menubar models outside the application as part of the desktop shell. For instance, on OS X, both menus will be displayed remotely; on Windows neither will be. 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 `ApplicationWindow` will automatically show a `MenuBar` for it. This behaviour can be overridden with the `ApplicationWindow:show-menubar` property. If the desktop environment does not display the application menu, then it will automatically be included in the menubar or in the windows client-side decorations. ## A `ApplicationWindow` with a menubar ```C GtkApplication *app = gtk_application_new ("org.gtk.test", 0); GtkBuilder *builder = gtk_builder_new_from_string ( "" " " " " " " " " " " " " "", -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](https://gitlab.gnome.org/GNOME/gtk/tree/master/examples/sunny.c) The XML format understood by `Builder` for `gio::MenuModel` consists of a toplevel `` element, which contains one or more `` elements. Each `` element contains `` and `` elements with a mandatory name attribute. `` elements have the same content model as ``. Instead of ``, you can use `` or `

` elements. Attribute values can be translated using gettext, like other `Builder` content. `` 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 `Builder` 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 `TextDirection` 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 # Implements [`ApplicationWindowExt`](trait.ApplicationWindowExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`RootExt`](trait.RootExt.html), [`gio::ActionGroupExt`](../gio/trait.ActionGroupExt.html), [`gio::ActionMapExt`](../gio/trait.ActionMapExt.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html) Trait containing all `ApplicationWindow` methods. # Implementors [`ApplicationWindow`](struct.ApplicationWindow.html) Creates a new `ApplicationWindow`. ## `application` a `Application` # Returns a newly created `ApplicationWindow` Gets the `ShortcutsWindow` that has been set up with a prior call to `ApplicationWindowExt::set_help_overlay`. # Returns the help overlay associated with `self`, or `None` Returns the unique ID of the window. If the window has not yet been added to a `Application`, returns `0`. # Returns the unique ID for `self`, or `0` if the window has not yet been added to a `Application` Returns whether the window will display a menubar for the app menu and menubar as needed. # Returns `true` if `self` will display a menubar when needed Associates a shortcuts window with the application window, and sets up an action with the name win.show-help-overlay to present it. `self` takes resposibility for destroying `help_overlay`. ## `help_overlay` a `ShortcutsWindow` Sets whether the window will display a menubar for the app menu and menubar as needed. ## `show_menubar` whether to show a menubar when needed If this property is `true`, the window will display a menubar that includes the app menu and menubar, unless these are shown by the desktop shell. See `GtkApplicationExt::set_app_menu` and `GtkApplicationExt::set_menubar`. If `false`, the window will not display a menubar, regardless of whether the desktop shell is showing the menus or not. If this property is `true`, the window will display a menubar that includes the app menu and menubar, unless these are shown by the desktop shell. See `GtkApplicationExt::set_app_menu` and `GtkApplicationExt::set_menubar`. If `false`, the window will not display a menubar, regardless of whether the desktop shell is showing the menus or not. Used to specify the placement of scroll arrows in scrolling menus. Place one arrow on each end of the menu. Place both arrows at the top of the menu. Place both arrows at the bottom of the menu. Used to indicate the direction in which an arrow should point. Represents an upward pointing arrow. Represents a downward pointing arrow. Represents a left pointing arrow. Represents a right pointing arrow. No arrow. The `AspectFrame` 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. `AspectFrame` derives from `Frame`, 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 `AspectFrame` uses a CSS node with name frame. # Implements [`AspectFrameExt`](trait.AspectFrameExt.html), [`FrameExt`](trait.FrameExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html) Trait containing all `AspectFrame` methods. # Implementors [`AspectFrame`](struct.AspectFrame.html) Create a new `AspectFrame`. ## `label` Label text. ## `xalign` Horizontal alignment of the child within the allocation of the `AspectFrame`. This ranges from 0.0 (left aligned) to 1.0 (right aligned) ## `yalign` Vertical alignment of the child within the allocation of the `AspectFrame`. This ranges from 0.0 (top aligned) to 1.0 (bottom aligned) ## `ratio` The desired aspect ratio. ## `obey_child` If `true`, `ratio` is ignored, and the aspect ratio is taken from the requistion of the child. # Returns the new `AspectFrame`. Set parameters for an existing `AspectFrame`. ## `xalign` Horizontal alignment of the child within the allocation of the `AspectFrame`. This ranges from 0.0 (left aligned) to 1.0 (right aligned) ## `yalign` Vertical alignment of the child within the allocation of the `AspectFrame`. This ranges from 0.0 (top aligned) to 1.0 (bottom aligned) ## `ratio` The desired aspect ratio. ## `obey_child` If `true`, `ratio` is ignored, and the aspect ratio is taken from the requistion of the child. A `Assistant` 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 `Assistant` is that it controls what buttons to show and to make sensitive, based on what it knows about the page sequence and the [type][`AssistantPageType`] of each page, in addition to state information like the page [completion][gtk-assistant-set-page-complete] and [committed][gtk-assistant-commit] status. If you have a case that doesn’t quite fit in ``GtkAssistants`` way of handling buttons, you can use the `AssistantPageType::Custom` page type and handle buttons yourself. `Assistant` maintains a `AssistantPage` object for each added child, which holds additional per-child properties. You obtain the `AssistantPage` for a child with `AssistantExt::get_page`. # `Assistant` as `Buildable` The `Assistant` implementation of the `Buildable` interface exposes the `action_area` as internal children with the name “action_area”. To add pages to an assistant in `Builder`, simply add it as a child to the `Assistant` object. If you need to set per-object properties, create a `AssistantPage` object explicitly, and set the child widget as a property on it. # CSS nodes `Assistant` has a single CSS node with the name assistant. # Implements [`AssistantExt`](trait.AssistantExt.html), [`GtkWindowExt`](trait.GtkWindowExt.html), [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`RootExt`](trait.RootExt.html), [`GtkWindowExtManual`](prelude/trait.GtkWindowExtManual.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html) Trait containing all `Assistant` methods. # Implementors [`Assistant`](struct.Assistant.html) Creates a new `Assistant`. # Returns a newly created `Assistant` Adds a widget to the action area of a `Assistant`. ## `child` a `Widget` Appends a page to the `self`. ## `page` a `Widget` # Returns the index (starting at 0) of the inserted page Erases the visited page history so the back button is not shown on the current page, and removes the cancel button from subsequent pages. Use this when the information provided up to the current page is hereafter deemed permanent and cannot be modified or undone. For example, showing a progress page to track a long-running, unreversible operation after the user has clicked apply on a confirmation page. Returns the page number of the current page. # Returns The index (starting from 0) of the current page in the `self`, or -1 if the `self` has no pages, or no current page. Returns the number of pages in the `self` # Returns the number of pages in the `self` Returns the child widget contained in page number `page_num`. ## `page_num` the index of a page in the `self`, or -1 to get the last page # Returns the child widget, or `None` if `page_num` is out of bounds Returns the `AssistantPage` object for `child`. ## `child` a child of `self` # Returns the `AssistantPage` for `child` Gets whether `page` is complete. ## `page` a page of `self` # Returns `true` if `page` is complete. Gets the title for `page`. ## `page` a page of `self` # Returns the title for `page` Gets the page type of `page`. ## `page` a page of `self` # Returns the page type of `page` Gets a list model of the assistant pages. # Returns A list model of the pages. Inserts a page in the `self` at a given position. ## `page` a `Widget` ## `position` the index (starting at 0) at which to insert the page, or -1 to append the page to the `self` # Returns the index (starting from 0) of the inserted page Navigate to the next page. It is a programming error to call this function when there is no next page. This function is for use when creating pages of the `AssistantPageType::Custom` type. Prepends a page to the `self`. ## `page` a `Widget` # Returns the index (starting at 0) of the inserted page Navigate to the previous visited page. It is a programming error to call this function when no previous page is available. This function is for use when creating pages of the `AssistantPageType::Custom` type. Removes a widget from the action area of a `Assistant`. ## `child` a `Widget` Removes the `page_num`’s page from `self`. ## `page_num` the index of a page in the `self`, or -1 to remove the last page Switches the page to `page_num`. Note that this will only be necessary in custom buttons, as the `self` flow can be set with `AssistantExt::set_forward_page_func`. ## `page_num` index of the page to switch to, starting from 0. If negative, the last page will be used. If greater than the number of pages in the `self`, nothing will be done. Sets the page forwarding function to be `page_func`. This function will be used to determine what will be the next page when the user presses the forward button. Setting `page_func` to `None` will make the assistant to use the default forward function, which just goes to the next visible page. ## `page_func` the ``GtkAssistantPageFunc``, or `None` to use the default one ## `data` user data for `page_func` ## `destroy` destroy notifier for `data` Sets whether `page` contents are complete. This will make `self` update the buttons state to be able to continue the task. ## `page` a page of `self` ## `complete` the completeness status of the page Sets a title for `page`. The title is displayed in the header area of the assistant when `page` is the current page. ## `page` a page of `self` ## `title` the new title for `page` Sets the page type for `page`. The page type determines the page behavior in the `self`. ## `page` a page of `self` ## `type_` the new type for `page` Forces `self` to recompute the buttons state. GTK+ automatically takes care of this in most situations, e.g. when the user goes to a different page, or when the visibility or completeness of a page changes. One situation where it can be necessary to call this function is when changing a value on the current page affects the future page flow of the assistant. The ::apply signal is emitted when the apply button is clicked. The default behavior of the `Assistant` is to switch to the page after the current page, unless the current page is the last one. A handler for the ::apply signal should carry out the actions for which the wizard has collected data. If the action takes a long time to complete, you might consider putting a page of type `AssistantPageType::Progress` after the confirmation page and handle this operation within the `Assistant::prepare` signal of the progress page. The ::cancel signal is emitted when then the cancel button is clicked. The ::close signal is emitted either when the close button of a summary page is clicked, or when the apply button in the last page in the flow (of type `AssistantPageType::Confirm`) is clicked. The ::prepare signal is emitted when a new page is set as the assistant's current page, before making the new page visible. A handler for this signal can do any preparations which are necessary before showing `page`. ## `page` the current page `true` if the assistant uses a `HeaderBar` for action buttons instead of the action-area. For technical reasons, this property is declared as an integer property, but you should only set it to `true` or `false`. `true` if the assistant uses a `HeaderBar` for action buttons instead of the action-area. For technical reasons, this property is declared as an integer property, but you should only set it to `true` or `false`. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Returns the child to which `self` belongs. # Returns the child to which `self` belongs Setting the "complete" property to `true` marks a page as complete (i.e.: all the required fields are filled out). GTK+ uses this information to control the sensitivity of the navigation buttons. Setting the "complete" property to `true` marks a page as complete (i.e.: all the required fields are filled out). GTK+ uses this information to control the sensitivity of the navigation buttons. The type of the assistant page. The type of the assistant page. The title of the page. The title of the page. An enum for determining the page role inside the `Assistant`. It's used to handle buttons sensitivity and visibility. Note that an assistant needs to end its page flow with a page of type `AssistantPageType::Confirm`, `AssistantPageType::Summary` or `AssistantPageType::Progress` to be correct. The Cancel button will only be shown if the page isn’t “committed”. See `AssistantExt::commit` for details. The page has regular contents. Both the Back and forward buttons will be shown. The page contains an introduction to the assistant task. Only the Forward button will be shown if there is a next page. The page lets the user confirm or deny the changes. The Back and Apply buttons will be shown. The page informs the user of the changes done. Only the Close button will be shown. Used for tasks that take a long time to complete, blocks the assistant until the page is marked as complete. Only the back button will be shown. Used for when other page types are not appropriate. No buttons will be shown, and the application must add its own buttons through `AssistantExt::add_action_widget`. Whenever a container has some form of natural row it may align children in that row along a common typographical baseline. If the amount of verical space in the row is taller than the total requested height of the baseline-aligned children then it can use a `BaselinePosition` to select where to put the baseline inside the extra availible space. Align the baseline at the top Center the baseline Align the baseline at the bottom The `Bin` 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 `Bin`, including `Window`, `Button`, `Frame` or `ScrolledWindow`. # Implements [`BinExt`](trait.BinExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html) Trait containing all `Bin` methods. # Implementors [`Bin`](struct.Bin.html), [`Button`](struct.Button.html), [`ComboBox`](struct.ComboBox.html), [`FlowBoxChild`](struct.FlowBoxChild.html), [`Frame`](struct.Frame.html), [`ListBoxRow`](struct.ListBoxRow.html), [`MenuItem`](struct.MenuItem.html), [`Overlay`](struct.Overlay.html), [`Popover`](struct.Popover.html), [`Revealer`](struct.Revealer.html), [`ScrolledWindow`](struct.ScrolledWindow.html), [`SearchBar`](struct.SearchBar.html), [`StackSidebar`](struct.StackSidebar.html), [`ToolItem`](struct.ToolItem.html), [`Viewport`](struct.Viewport.html), [`Window`](struct.Window.html) Gets the child of the `Bin`, or `None` if the bin contains no child widget. The returned widget does not have a reference added, so you do not need to unref it. # Returns the child of `self`, or `None` if it does not have a child. `BinLayout` is a `LayoutManager` subclass useful for create "bins" of widgets. `BinLayout` will stack each child of a widget on top of each other, using the `Widget:hexpand`, `Widget:vexpand`, `Widget:halign`, and `Widget:valign` properties of each child to determine where they should be positioned. # Implements [`LayoutManagerExt`](trait.LayoutManagerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `BinLayout` instance. # Returns the newly created `BinLayout` A struct that specifies a border around a rectangular area that can be of different width on each side. Allocates a new `Border`-struct and initializes its elements to zero. # Returns a newly allocated `Border`-struct. Free with `Border::free` Copies a `Border`-struct. # Returns a copy of `self`. Frees a `Border`-struct. Describes how the border of a UI element should be rendered. No visible border A single line segment Looks as if the content is sunken into the canvas Looks as if the content is coming out of the canvas Same as `BorderStyle::None` A series of round dots A series of square-ended dashes Two parallel lines with some space between them Looks as if it were carved in the canvas Looks as if it were coming out of the canvas The `Box` widget arranges child widgets into a single row or column, depending upon the value of its `Orientable:orientation` property. Within the other dimension, all children are allocated the same size. Of course, the `Widget:halign` and `Widget:valign` properties can be used on the children to influence their allocation. Use repeated calls to `ContainerExt::add` to pack widgets into a `Box` from start to end. Use `ContainerExt::remove` to remove widgets from the `Box`. `BoxExt::insert_child_after` can be used to add a child at a particular position. Use `BoxExt::set_homogeneous` to specify whether or not all children of the `Box` are forced to get the same amount of space. Use `BoxExt::set_spacing` to determine how much space will be minimally placed between all children in the `Box`. Note that spacing is added between the children. Use `BoxExt::reorder_child_after` to move a child to a different place in the box. # CSS nodes `Box` uses a single CSS node with name box. # Implements [`BoxExt`](trait.BoxExt.html), [`ContainerExt`](trait.ContainerExt.html), [`WidgetExt`](trait.WidgetExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`BuildableExt`](trait.BuildableExt.html), [`OrientableExt`](trait.OrientableExt.html), [`WidgetExtManual`](prelude/trait.WidgetExtManual.html) Trait containing all `Box` methods. # Implementors [`Box`](struct.Box.html), [`ColorChooserWidget`](struct.ColorChooserWidget.html), [`InfoBar`](struct.InfoBar.html), [`ShortcutLabel`](struct.ShortcutLabel.html), [`ShortcutsGroup`](struct.ShortcutsGroup.html), [`ShortcutsSection`](struct.ShortcutsSection.html), [`StackSwitcher`](struct.StackSwitcher.html) Creates a new `Box`. ## `orientation` the box’s orientation. ## `spacing` the number of pixels to place by default between children. # Returns a new `Box`. Gets the value set by `BoxExt::set_baseline_position`. # Returns the baseline position Returns whether the box is homogeneous (all children are the same size). See `BoxExt::set_homogeneous`. # Returns `true` if the box is homogeneous. Gets the value set by `BoxExt::set_spacing`. # Returns spacing between children Inserts `child` in the position after `sibling` in the list of `self` children. If `sibling` is `None`, insert `child` at the first position. ## `child` the `Widget` to insert ## `sibling` the sibling to move `child` after, or `None` Moves `child` to the position after `sibling` in the list of `self` children. If `sibling` is `None`, move `child` to the first position. ## `child` the `Widget` to move, must be a child of `self` ## `sibling` the sibling to move `child` after, or `None` Sets the baseline position of a box. This affects only horizontal boxes with at least one baseline aligned child. If there is more vertical space available than requested, and the baseline is not allocated by the parent then `position` is used to allocate the baseline wrt the extra space available. ## `position` a `BaselinePosition` Sets the `Box:homogeneous` property of `self`, controlling whether or not all children of `self` are given equal space in the box. ## `homogeneous` a boolean value, `true` to create equal allotments, `false` for variable allotments Sets the `Box:spacing` property of `self`, which is the number of pixels to place between children of `self`. ## `spacing` the number of pixels to put between children A `BoxLayout` is a layout manager that arranges the children of any widget using it into a single row or column, depending on the value of its `Orientable:orientation` property. Within the other dimension all children all allocated the same size. The `BoxLayout` will respect the `Widget:halign` and `Widget:valign` properties of each child widget. If you want all children to be assigned the same size, you can use the `BoxLayout:homogeneous` property. If you want to specify the amount of space placed between each child, you can use the `BoxLayout:spacing` property. # Implements [`BoxLayoutExt`](trait.BoxLayoutExt.html), [`LayoutManagerExt`](trait.LayoutManagerExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`OrientableExt`](trait.OrientableExt.html) Trait containing all `BoxLayout` methods. # Implementors [`BoxLayout`](struct.BoxLayout.html) Creates a new box layout. ## `orientation` the orientation for the new layout # Returns a new box layout Gets the value set by `BoxLayoutExt::set_baseline_position`. # Returns the baseline position Returns whether the layout is set to be homogeneous. # Returns `true` if the layout is homogeneous Returns the space that `self` puts between children. # Returns the spacing of the layout Sets the baseline position of a box layout. The baseline position affects only horizontal boxes with at least one baseline aligned child. If there is more vertical space available than requested, and the baseline is not allocated by the parent then the given `position` is used to allocate the baseline within the extra space available. ## `position` a `BaselinePosition` Sets whether the box layout will allocate the same size to all children. ## `homogeneous` `true` to set the box layout as homogeneous Sets how much spacing to put between children. ## `spacing` the spacing to apply between children The position of the allocated baseline within the extra space allocated to each child of the widget using a box layout manager. This property is only relevant for horizontal layouts containing at least one child with a baseline alignment. The position of the allocated baseline within the extra space allocated to each child of the widget using a box layout manager. This property is only relevant for horizontal layouts containing at least one child with a baseline alignment. Whether the box layout should distribute the available space homogeneously among the children of the widget using it as a layout manager. Whether the box layout should distribute the available space homogeneously among the children of the widget using it as a layout manager. The space between each child of the widget using the box layout as its layout manager. The space between each child of the widget using the box layout as its layout manager. `Buildable` allows objects to extend and customize their deserialization from [`Builder` UI descriptions][BUILDER-UI]. The interface includes methods for setting names and properties of objects, parsing custom tags and constructing child objects. The `Buildable` interface is implemented by all widgets and many of the non-widget objects that are provided by GTK+. The main user of this interface is `Builder`. There should be very little need for applications to call any of these functions directly. An object only needs to implement this interface if it needs to extend the `Builder` format or run any extra routines at deserialization time. # Implements [`BuildableExt`](trait.BuildableExt.html) Trait containing all `Buildable` methods. # Implementors [`AboutDialog`](struct.AboutDialog.html), [`AccelLabel`](struct.AccelLabel.html), [`ActionBar`](struct.ActionBar.html), [`AppChooserButton`](struct.AppChooserButton.html), [`AppChooserDialog`](struct.AppChooserDialog.html), [`AppChooserWidget`](struct.AppChooserWidget.html), [`ApplicationWindow`](struct.ApplicationWindow.html), [`AspectFrame`](struct.AspectFrame.html), [`Assistant`](struct.Assistant.html), [`Bin`](struct.Bin.html), [`Box`](struct.Box.html), [`Buildable`](struct.Buildable.html), [`Button`](struct.Button.html), [`Calendar`](struct.Calendar.html), [`CellAreaBox`](struct.CellAreaBox.html), [`CellArea`](struct.CellArea.html), [`CellView`](struct.CellView.html), [`CenterBox`](struct.CenterBox.html), [`CheckButton`](struct.CheckButton.html), [`CheckMenuItem`](struct.CheckMenuItem.html), [`ColorButton`](struct.ColorButton.html), [`ColorChooserDialog`](struct.ColorChooserDialog.html), [`ColorChooserWidget`](struct.ColorChooserWidget.html), [`ComboBoxText`](struct.ComboBoxText.html), [`ComboBox`](struct.ComboBox.html), [`Container`](struct.Container.html), [`Dialog`](struct.Dialog.html), [`DrawingArea`](struct.DrawingArea.html), [`EntryCompletion`](struct.EntryCompletion.html), [`Entry`](struct.Entry.html), [`Expander`](struct.Expander.html), [`FileChooserButton`](struct.FileChooserButton.html), [`FileChooserDialog`](struct.FileChooserDialog.html), [`FileChooserWidget`](struct.FileChooserWidget.html), [`FileFilter`](struct.FileFilter.html), [`Fixed`](struct.Fixed.html), [`FlowBoxChild`](struct.FlowBoxChild.html), [`FlowBox`](struct.FlowBox.html), [`FontButton`](struct.FontButton.html), [`FontChooserDialog`](struct.FontChooserDialog.html), [`FontChooserWidget`](struct.FontChooserWidget.html), [`Frame`](struct.Frame.html), [`GLArea`](struct.GLArea.html), [`Grid`](struct.Grid.html), [`HeaderBar`](struct.HeaderBar.html), [`IconView`](struct.IconView.html), [`Image`](struct.Image.html), [`InfoBar`](struct.InfoBar.html), [`Label`](struct.Label.html), [`LevelBar`](struct.LevelBar.html), [`LinkButton`](struct.LinkButton.html), [`ListBoxRow`](struct.ListBoxRow.html), [`ListBox`](struct.ListBox.html), [`ListStore`](struct.ListStore.html), [`LockButton`](struct.LockButton.html), [`MediaControls`](struct.MediaControls.html), [`MenuBar`](struct.MenuBar.html), [`MenuButton`](struct.MenuButton.html), [`MenuItem`](struct.MenuItem.html), [`MenuShell`](struct.MenuShell.html), [`MenuToolButton`](struct.MenuToolButton.html), [`Menu`](struct.Menu.html), [`MessageDialog`](struct.MessageDialog.html), [`ModelButton`](struct.ModelButton.html), [`Notebook`](struct.Notebook.html), [`Overlay`](struct.Overlay.html), [`Paned`](struct.Paned.html), [`PasswordEntry`](struct.PasswordEntry.html), [`Picture`](struct.Picture.html), [`PopoverMenu`](struct.PopoverMenu.html), [`Popover`](struct.Popover.html), [`ProgressBar`](struct.ProgressBar.html), [`RadioButton`](struct.RadioButton.html), [`RadioMenuItem`](struct.RadioMenuItem.html), [`RadioToolButton`](struct.RadioToolButton.html), [`Range`](struct.Range.html), [`Revealer`](struct.Revealer.html), [`ScaleButton`](struct.ScaleButton.html), [`Scale`](struct.Scale.html), [`Scrollbar`](struct.Scrollbar.html), [`ScrolledWindow`](struct.ScrolledWindow.html), [`SearchBar`](struct.SearchBar.html), [`SearchEntry`](struct.SearchEntry.html), [`SeparatorMenuItem`](struct.SeparatorMenuItem.html), [`SeparatorToolItem`](struct.SeparatorToolItem.html), [`Separator`](struct.Separator.html), [`ShortcutLabel`](struct.ShortcutLabel.html), [`ShortcutsGroup`](struct.ShortcutsGroup.html), [`ShortcutsSection`](struct.ShortcutsSection.html), [`ShortcutsShortcut`](struct.ShortcutsShortcut.html), [`ShortcutsWindow`](struct.ShortcutsWindow.html), [`SizeGroup`](struct.SizeGroup.html), [`SpinButton`](struct.SpinButton.html), [`Spinner`](struct.Spinner.html), [`StackSidebar`](struct.StackSidebar.html), [`StackSwitcher`](struct.StackSwitcher.html), [`Stack`](struct.Stack.html), [`Statusbar`](struct.Statusbar.html), [`Switch`](struct.Switch.html), [`TextTagTable`](struct.TextTagTable.html), [`TextView`](struct.TextView.html), [`Text`](struct.Text.html), [`ToggleButton`](struct.ToggleButton.html), [`ToggleToolButton`](struct.ToggleToolButton.html), [`ToolButton`](struct.ToolButton.html), [`ToolItem`](struct.ToolItem.html), [`Toolbar`](struct.Toolbar.html), [`TreeStore`](struct.TreeStore.html), [`TreeViewColumn`](struct.TreeViewColumn.html), [`TreeView`](struct.TreeView.html), [`Video`](struct.Video.html), [`Viewport`](struct.Viewport.html), [`VolumeButton`](struct.VolumeButton.html), [`Widget`](struct.Widget.html), [`Window`](struct.Window.html) Adds a child to `self`. `type_` is an optional string describing how the child should be added. ## `builder` a `Builder` ## `child` child to add ## `type_` kind of child or `None` Constructs a child of `self` with the name `name`. `Builder` calls this function if a “constructor” has been specified in the UI definition. ## `builder` `Builder` used to construct this object ## `name` name of child to construct # Returns the constructed child This is similar to `Buildable::parser_finished` but is called once for each custom tag handled by the `self`. ## `builder` a `Builder` ## `child` child object or `None` for non-child tags ## `tagname` the name of the tag ## `data` user data created in custom_tag_start This is called at the end of each custom element handled by the buildable. ## `builder` `Builder` used to construct this object ## `child` child object or `None` for non-child tags ## `tagname` name of tag ## `data` user data that will be passed in to parser functions This is called for each unknown element under ``. ## `builder` a `Builder` used to construct this object ## `child` child object or `None` for non-child tags ## `tagname` name of tag ## `parser` a `glib::MarkupParser` to fill in ## `data` return location for user data that will be passed in to parser functions # Returns `true` if a object has a custom implementation, `false` if it doesn't. Get the internal child called `childname` of the `self` object. ## `builder` a `Builder` ## `childname` name of child # Returns the internal child of the buildable object Gets the name of the `self` object. `Builder` sets the name based on the [`Builder` UI definition][BUILDER-UI] used to construct the `self`. # Returns the name set with `Buildable::set_name` Called when the builder finishes the parsing of a [`Builder` UI definition][BUILDER-UI]. Note that this will be called once for each time `Builder::add_from_file` or `BuilderExt::add_from_string` is called on a builder. ## `builder` a `Builder` Sets the property name `name` to `value` on the `self` object. ## `builder` a `Builder` ## `name` name of property ## `value` value of property Sets the name of the `self` object. ## `name` name to set A `Builder` is an auxiliary object that reads textual descriptions of a user interface and instantiates the described objects. To create a `Builder` from a user interface description, call `Builder::new_from_file`, `Builder::new_from_resource` or `Builder::new_from_string`. In the (unusual) case that you want to add user interface descriptions from multiple sources to the same `Builder` you can call `Builder::new` to get an empty builder and populate it by (multiple) calls to `Builder::add_from_file`, `BuilderExt::add_from_resource` or `BuilderExt::add_from_string`. A `Builder` holds a reference to all objects that it has constructed and drops these references when it is finalized. This finalization can cause the destruction of non-widget objects or widgets which are not contained in a toplevel window. For toplevel windows constructed by a builder, it is the responsibility of the user to call `WidgetExt::destroy` to get rid of them and all the widgets they contain. The functions `Builder::get_object` and `BuilderExt::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 `WidgetExt::destroy`. Other widgets will either be part of a larger hierarchy constructed by the builder (in which case you should not have to worry about their lifecycle), or without a parent, in which case they have to be added to some container to make use of them. Non-widget objects need to be reffed with `gobject::ObjectExt::ref` to keep them beyond the lifespan of the builder. The function `BuilderExt::connect_signals` and variants thereof can be used to connect handlers to the named signals in the description. # `Builder` UI Definitions # {`BUILDER`-UI} `Builder` 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 “`Builder` UI definitions” or just “UI definitions” if the context is clear. [RELAX NG Compact Syntax](https://gitlab.gnome.org/GNOME/gtk/tree/master/gtk/gtkbuilder.rnc) The toplevel element is ``. 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 `BuilderExt::set_translation_domain` on the builder. Objects are described by `