The rectangle representing the area allocated for a widget by its parent. An attribute for the background color, expressed as an RGB value encoded in a string using the format: `{r8},{g8},{b8}`. An attribute for the font family name. An attribute for the foreground color, expressed as an RGB value encoded in a string using the format: `{r8},{g8},{b8}`. An attribute for the overline style. Possible values are: - [const@Gtk.ACCESSIBLE_ATTRIBUTE_OVERLINE_NONE] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_OVERLINE_SINGLE] The "none" overline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_OVERLINE]. The "single" overline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_OVERLINE]. An attribute for the font size, expressed in points. An attribute for the font stretch type. Possible values are: - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH_ULTRA_CONDENSED] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH_EXTRA_CONDENSED] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH_CONDENSED] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH_SEMI_CONDENSED] The "condensed" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "expanded" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "extra condensed" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "extra expanded" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "normal" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "semi condensed" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "semi expanded" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "ultra condensed" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. The "ultra expanded" stretch value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STRETCH]. An attribute for strikethrough text. Possible values are `true` or `false`. An attribute for the font style. Possible values are: - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE_NORMAL] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE_OBLIQUE] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE_ITALIC] The "italic" style value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE]. The "normal" style value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE]. The "oblique" style value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_STYLE]. An attribute for the underline style. Possible values are: - [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE_NONE] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE_SINGLE] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE_DOUBLE] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE_ERROR] The "double" underline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE]. The "error" underline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE]. The "none" underline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE]. The "single" underline value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_UNDERLINE]. An attribute for the font variant. Possible values are: - [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_SMALL_CAPS] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_ALL_SMALL_CAPS] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_PETITE_CAPS] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_ALL_PETITE_CAPS] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_UNICASE] - [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT_TITLE_CAPS] The "all petite caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. The "all small caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. The "petite caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. The "small caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. The "title caps" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. The "unicase" variant value for [const@Gtk.ACCESSIBLE_ATTRIBUTE_VARIANT]. An attribute for the font weight. An undefined value. The accessible attribute is either unset, or its value is undefined. `GtkATContext` is an abstract class provided by GTK to communicate to platform-specific assistive technologies API. Each platform supported by GTK implements a `GtkATContext` subclass, and is responsible for updating the accessible state in response to state changes in `GtkAccessible`. Creates a new `GtkATContext` instance for the given accessible role, accessible instance, and display connection. The `GtkATContext` implementation being instantiated will depend on the platform. the `GtkATContext` the accessible role used by the `GtkATContext` the `GtkAccessible` implementation using the `GtkATContext` the `GdkDisplay` used by the `GtkATContext` Retrieves the `GtkAccessible` using this context. a `GtkAccessible` a `GtkATContext` Retrieves the accessible role of this context. a `GtkAccessibleRole` a `GtkATContext` The `GtkAccessible` that created the `GtkATContext` instance. The accessible role used by the AT context. Depending on the given role, different states and properties can be set or retrieved. The `GdkDisplay` for the `GtkATContext`. Emitted when the attributes of the accessible for the `GtkATContext` instance change. The `GtkAboutDialog` offers a simple way to display information about a program. The shown information includes the programs' logo, name, copyright, website and license. It is also possible to give credits to the authors, documenters, translators and artists who have worked on the program. An about dialog is typically opened when the user selects the `About` option from the `Help` menu. All parts of the dialog are optional.  About dialogs often contain links and email addresses. `GtkAboutDialog` displays these as clickable links. By default, it calls [method@Gtk.FileLauncher.launch] when a user clicks one. The behaviour can be overridden with the [signal@Gtk.AboutDialog::activate-link] signal. To specify a person with an email address, use a string like `Edgar Allan Poe <edgar@poe.com>`. To specify a website with a title, use a string like `GTK team https://www.gtk.org`. To make constructing a `GtkAboutDialog` as convenient as possible, you can use the function [func@Gtk.show_about_dialog] which constructs and shows a dialog and keeps it around so that it can be shown again. Note that GTK sets a default title of `_("About %s")` on the dialog window (where `%s` is replaced by the name of the application, but in order to ensure proper translation of the title, applications should set the title property explicitly when constructing a `GtkAboutDialog`, as shown in the following example: ```c GFile *logo_file = g_file_new_for_path ("./logo.png"); GdkTexture *example_logo = gdk_texture_new_from_file (logo_file, NULL); g_object_unref (logo_file); gtk_show_about_dialog (NULL, "program-name", "ExampleCode", "logo", example_logo, "title", _("About ExampleCode"), NULL); ``` ## Shortcuts and Gestures `GtkAboutDialog` supports the following keyboard shortcuts: - <kbd>Escape</kbd> closes the window. ## CSS nodes `GtkAboutDialog` has a single CSS node with the name `window` and style class `.aboutdialog`. Creates a new `GtkAboutDialog`. a newly created `GtkAboutDialog` Creates a new section in the "Credits" page. A `GtkAboutDialog` The name of the section The people who belong to that section Returns the names of the artists which are displayed in the credits page. A `NULL`-terminated string array containing the artists a `GtkAboutDialog` Returns the names of the authors which are displayed in the credits page. A `NULL`-terminated string array containing the authors a `GtkAboutDialog` Returns the comments string. The comments a `GtkAboutDialog` Returns the copyright string. The copyright string a `GtkAboutDialog` Returns the name of the documenters which are displayed in the credits page. A `NULL`-terminated string array containing the documenters a `GtkAboutDialog` Returns the license information. The license information a `GtkAboutDialog` Retrieves the license type. a [enum@Gtk.License] value a `GtkAboutDialog` Returns the paintable displayed as logo in the about dialog. the paintable displayed as logo or `NULL` if the logo is unset or has been set via [method@Gtk.AboutDialog.set_logo_icon_name] a `GtkAboutDialog` Returns the icon name displayed as logo in the about dialog. the icon name displayed as logo, or `NULL` if the logo has been set via [method@Gtk.AboutDialog.set_logo] a `GtkAboutDialog` Returns the program name displayed in the about dialog. The program name a `GtkAboutDialog` Returns the system information that is shown in the about dialog. the system information a `GtkAboutDialog` Returns the translator credits string which is displayed in the credits page. The translator credits string a `GtkAboutDialog` Returns the version string. The version string a `GtkAboutDialog` Returns the website URL. The website URL a `GtkAboutDialog` Returns the label used for the website link. The label used for the website link a `GtkAboutDialog` Returns whether the license text in the about dialog is automatically wrapped. `TRUE` if the license text is wrapped a `GtkAboutDialog` Sets the names of the artists to be displayed in the "Credits" page. a `GtkAboutDialog` the authors of the artwork of the application Sets the names of the authors which are displayed in the "Credits" page of the about dialog. a `GtkAboutDialog` the authors of the application Sets the comments string to display in the about dialog. This should be a short string of one or two lines. a `GtkAboutDialog` a comments string Sets the copyright string to display in the about dialog. This should be a short string of one or two lines. a `GtkAboutDialog` the copyright string Sets the names of the documenters which are displayed in the "Credits" page. a `GtkAboutDialog` the authors of the documentation of the application Sets the license information to be displayed in the about dialog. If `license` is `NULL`, the license page is hidden. a `GtkAboutDialog` the license information Sets the license of the application showing the about dialog from a list of known licenses. This function overrides the license set using [method@Gtk.AboutDialog.set_license]. a `GtkAboutDialog` the type of license Sets the logo in the about dialog. a `GtkAboutDialog` a `GdkPaintable` Sets the icon name to be displayed as logo in the about dialog. a `GtkAboutDialog` an icon name Sets the name to display in the about dialog. If `name` is not set, the string returned by `g_get_application_name()` is used. a `GtkAboutDialog` the program name Sets the system information to be displayed in the about dialog. If `system_information` is `NULL`, the system information page is hidden. See [property@Gtk.AboutDialog:system-information]. a `GtkAboutDialog` system information Sets the translator credits string which is displayed in the credits page. 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 `GtkAboutDialog` will detect if “translator-credits” is untranslated and omit translator credits. a `GtkAboutDialog` the translator credits Sets the version string to display in the about dialog. a `GtkAboutDialog` the version string Sets the URL to use for the website link. a `GtkAboutDialog` a URL string starting with `http://` Sets the label to be used for the website link. a `GtkAboutDialog` the label used for the website link Sets whether the license text in the about dialog should be automatically wrapped. a `GtkAboutDialog` whether to wrap the license The people who contributed artwork to the program, as a `NULL`-terminated array of strings. Each string may contain email addresses and URLs, which will be displayed as links. The authors of the program, as a `NULL`-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. Copyright information for the program. The people documenting the program, as a `NULL`-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, as free-form text. 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-`NULL` value, the [property@Gtk.AboutDialog:license-type] property is set to `GTK_LICENSE_CUSTOM` as a side effect. The text may contain links in this format `<http://www.some.place/>` and email references in the form `<mail-to@some.body>`, and these will be converted into clickable links. The license of the program. The `GtkAboutDialog` will automatically fill out a standard disclaimer and link the user to the appropriate online resource for the license text. If `GTK_LICENSE_UNKNOWN` is used, the link used will be the same specified in the [property@Gtk.AboutDialog:website] property. If `GTK_LICENSE_CUSTOM` is used, the current contents of the [property@Gtk.AboutDialog:license] property are used. For any other [enum@Gtk.License] value, the contents of the [property@Gtk.AboutDialog:license] property are also set by this property as a side effect. A logo for the about box. If it is `NULL`, the default window icon set with [func@Gtk.Window.set_default_icon_name] will be used. A named icon to use as the logo for the about box. This property overrides the [property@Gtk.AboutDialog:logo] property. The name of the program. If this is not set, it defaults to the value returned by `g_get_application_name()`. Information about the system on which the program is running. This information is displayed in a separate page, 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 `<http://www.some.place/>` and email references in the form `<mail-to@some.body>`, 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. The version of the program. The URL for the link to the website of the program. This should be a string starting with `http://` or `https://`. The label for the link to the website of the program. Whether to wrap the text in the license dialog. Emitted every time a URL is activated. Applications may connect to it to override the default behaviour, which is to call [method@Gtk.FileLauncher.launch]. `TRUE` if the link has been activated the URI that is activated `GtkAccessible` is an interface for describing UI elements for Assistive Technologies. Every accessible implementation has: - a “role”, represented by a value of the [enum@Gtk.AccessibleRole] enumeration - an “attribute”, represented by a set of [enum@Gtk.AccessibleState], [enum@Gtk.AccessibleProperty] and [enum@Gtk.AccessibleRelation] values The role cannot be changed after instantiating a `GtkAccessible` implementation. The attributes are updated every time a UI element's state changes in a way that should be reflected by assistive technologies. For instance, if a `GtkWidget` visibility changes, the %GTK_ACCESSIBLE_STATE_HIDDEN state will also change to reflect the [property@Gtk.Widget:visible] property. Every accessible implementation is part of a tree of accessible objects. Normally, this tree corresponds to the widget tree, but can be customized by reimplementing the [vfunc@Gtk.Accessible.get_accessible_parent], [vfunc@Gtk.Accessible.get_first_accessible_child] and [vfunc@Gtk.Accessible.get_next_accessible_sibling] virtual functions. Note that you can not create a top-level accessible object as of now, which means that you must always have a parent accessible object. Also note that when an accessible object does not correspond to a widget, and it has children, whose implementation you don't control, it is necessary to ensure the correct shape of the a11y tree by calling [method@Gtk.Accessible.set_accessible_parent] and updating the sibling by [method@Gtk.Accessible.update_next_accessible_sibling]. Retrieves the accessible parent for an accessible object. This function returns `NULL` for top level widgets. the accessible parent a `GtkAccessible` Retrieves the accessible implementation for the given `GtkAccessible`. the accessible implementation object a `GtkAccessible` Queries the coordinates and dimensions of this accessible This functionality can be overridden by `GtkAccessible` implementations, e.g. to get the bounds from an ignored child widget. true if the bounds are valid, and false otherwise a `GtkAccessible` the x coordinate of the top left corner of the accessible the y coordinate of the top left corner of the widget the width of the accessible object the height of the accessible object Retrieves the first accessible child of an accessible object. the first accessible child an accessible object Retrieves the next accessible sibling of an accessible object the next accessible sibling an accessible object Query a platform state, such as focus. See gtk_accessible_platform_changed(). This functionality can be overridden by `GtkAccessible` implementations, e.g. to get platform state from an ignored child widget, as is the case for `GtkText` wrappers. the value of @state for the accessible a `GtkAccessible` platform state to query Requests the user's screen reader to announce the given message. This kind of notification is useful for messages that either have only a visual representation or that are not exposed visually at all, e.g. a notification about a successful operation. Also, by using this API, you can ensure that the message does not interrupts the user's current screen reader output. a `GtkAccessible` the string to announce the priority of the announcement Retrieves the accessible parent for an accessible object. This function returns `NULL` for top level widgets. the accessible parent a `GtkAccessible` Retrieves the accessible role of an accessible object. the accessible role an accessible object Retrieves the accessible implementation for the given `GtkAccessible`. the accessible implementation object a `GtkAccessible` Queries the coordinates and dimensions of this accessible This functionality can be overridden by `GtkAccessible` implementations, e.g. to get the bounds from an ignored child widget. true if the bounds are valid, and false otherwise a `GtkAccessible` the x coordinate of the top left corner of the accessible the y coordinate of the top left corner of the widget the width of the accessible object the height of the accessible object Retrieves the first accessible child of an accessible object. the first accessible child an accessible object Retrieves the next accessible sibling of an accessible object the next accessible sibling an accessible object Query a platform state, such as focus. See gtk_accessible_platform_changed(). This functionality can be overridden by `GtkAccessible` implementations, e.g. to get platform state from an ignored child widget, as is the case for `GtkText` wrappers. the value of @state for the accessible a `GtkAccessible` platform state to query Resets the accessible @property to its default value. a `GtkAccessible` a `GtkAccessibleProperty` Resets the accessible @relation to its default value. a `GtkAccessible` a `GtkAccessibleRelation` Resets the accessible @state to its default value. a `GtkAccessible` a `GtkAccessibleState` Sets the parent and sibling of an accessible object. This function is meant to be used by accessible implementations that are not part of the widget hierarchy, and but act as a logical bridge between widgets. For instance, if a widget creates an object that holds metadata for each child, and you want that object to implement the `GtkAccessible` interface, you will use this function to ensure that the parent of each child widget is the metadata object, and the parent of each metadata object is the container widget. an accessible object the parent accessible object the sibling accessible object Updates the next accessible sibling of @self. That might be useful when a new child of a custom `GtkAccessible` is created, and it needs to be linked to a previous child. a `GtkAccessible` the new next accessible sibling to set Updates a list of accessible properties. See the [enum@Gtk.AccessibleProperty] documentation for the value types of accessible properties. This function should be called by `GtkWidget` types whenever an accessible property change must be communicated to assistive technologies. Example: ```c value = gtk_adjustment_get_value (adjustment); gtk_accessible_update_property (GTK_ACCESSIBLE (spin_button), GTK_ACCESSIBLE_PROPERTY_VALUE_NOW, value, -1); ``` a `GtkAccessible` the first `GtkAccessibleProperty` a list of property and value pairs, terminated by -1 Updates an array of accessible properties. This function should be called by `GtkWidget` types whenever an accessible property change must be communicated to assistive technologies. This function is meant to be used by language bindings. a `GtkAccessible` the number of accessible properties to set an array of `GtkAccessibleProperty` an array of `GValues`, one for each property Updates a list of accessible relations. This function should be called by `GtkWidget` types whenever an accessible relation change must be communicated to assistive technologies. If the [enum@Gtk.AccessibleRelation] requires a list of references, you should pass each reference individually, followed by %NULL, e.g. ```c gtk_accessible_update_relation (accessible, GTK_ACCESSIBLE_RELATION_CONTROLS, ref1, NULL, GTK_ACCESSIBLE_RELATION_LABELLED_BY, ref1, ref2, ref3, NULL, -1); ``` a `GtkAccessible` the first `GtkAccessibleRelation` a list of relation and value pairs, terminated by -1 Updates an array of accessible relations. This function should be called by `GtkWidget` types whenever an accessible relation change must be communicated to assistive technologies. This function is meant to be used by language bindings. a `GtkAccessible` the number of accessible relations to set an array of `GtkAccessibleRelation` an array of `GValues`, one for each relation Updates a list of accessible states. See the [enum@Gtk.AccessibleState] documentation for the value types of accessible states. This function should be called by `GtkWidget` types whenever an accessible state change must be communicated to assistive technologies. Example: ```c value = GTK_ACCESSIBLE_TRISTATE_MIXED; gtk_accessible_update_state (GTK_ACCESSIBLE (check_button), GTK_ACCESSIBLE_STATE_CHECKED, value, -1); ``` a `GtkAccessible` the first `GtkAccessibleState` a list of state and value pairs, terminated by -1 Updates an array of accessible states. This function should be called by `GtkWidget` types whenever an accessible state change must be communicated to assistive technologies. This function is meant to be used by language bindings. a `GtkAccessible` the number of accessible states to set an array of `GtkAccessibleState` an array of `GValues`, one for each state The accessible role of the given `GtkAccessible` implementation. The accessible role cannot be changed once set. The priority of an accessibility announcement. The announcement is low priority, and might be read only on the user's request. The announcement is of medium priority, and is usually spoken at the next opportunity, such as at the end of speaking the current sentence or when the user pauses typing. The announcement is of high priority, and is usually spoken immediately. Because an interruption might disorient users or cause them to not complete their current task, authors SHOULD NOT use high priority announcements unless the interruption is imperative. An example would be a notification about a critical battery power level. The possible values for the %GTK_ACCESSIBLE_PROPERTY_AUTOCOMPLETE accessible property. Automatic suggestions are not displayed. When a user is providing input, text suggesting one way to complete the provided input may be dynamically inserted after the caret. When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. When a user is providing input, an element containing a collection of values that could complete the provided input may be displayed. If displayed, one value in the collection is automatically selected, and the text needed to complete the automatically selected value appears after the caret in the input. The common interface for accessible objects. retrieve the platform-specific accessibility context for the accessible implementation the accessible implementation object a `GtkAccessible` retrieve the accessible state the value of @state for the accessible a `GtkAccessible` platform state to query the accessible parent a `GtkAccessible` the first accessible child an accessible object the next accessible sibling an accessible object true if the bounds are valid, and false otherwise a `GtkAccessible` the x coordinate of the top left corner of the accessible the y coordinate of the top left corner of the widget the width of the accessible object the height of the accessible object The possible values for the %GTK_ACCESSIBLE_STATE_INVALID accessible state. Note that the %GTK_ACCESSIBLE_INVALID_FALSE and %GTK_ACCESSIBLE_INVALID_TRUE have the same values as %FALSE and %TRUE. There are no detected errors in the value The value entered by the user has failed validation A grammatical error was detected A spelling error was detected A boxed type which wraps a list of references to GtkAccessible objects. Allocates a new list of accessible instances. the newly created list of accessible instances array of GtkAccessible length of @accessibles array Allocates a new `GtkAccessibleList`, doing a shallow copy of the passed list of `GtkAccessible` instances. the list of accessible instances a reference to a `GList` containing a list of accessible values Gets the list of objects this boxed type holds a shallow copy of the objects The various platform states which can be queried using [method@Gtk.Accessible.get_platform_state]. whether the accessible can be focused whether the accessible has focus whether the accessible is active The possible accessible properties of a [iface@Accessible]. Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for a combobox, searchbox, or textbox and specifies how predictions would be presented if they were made. Value type: [enum@AccessibleAutocomplete] Defines a string value that describes or annotates the current element. Value type: string Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element. Indicates keyboard shortcuts that an author has implemented to activate or give focus to an element. Value type: string Defines a string value that labels the current element. Value type: string Defines the hierarchical level of an element within a structure. Value type: integer Indicates whether an element is modal when displayed. Value type: boolean Indicates whether a text box accepts multiple lines of input or only a single line. Value type: boolean Indicates that the user may select more than one item from the current selectable descendants. Value type: boolean Indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous. Value type: [enum@Orientation] Defines a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value. A hint could be a sample value or a brief description of the expected format. Value type: string Indicates that the element is not editable, but is otherwise operable. Value type: boolean Indicates that user input is required on the element before a form may be submitted. Value type: boolean Defines a human-readable, author-localized description for the role of an element. Value type: string Indicates if items in a table or grid are sorted in ascending or descending order. Value type: [enum@AccessibleSort] Defines the maximum allowed value for a range widget. Value type: double Defines the minimum allowed value for a range widget. Value type: double Defines the current value for a range widget. Value type: double Defines the human readable text alternative of aria-valuenow for a range widget. Value type: string Defines a string value that provides a description of non-standard keyboard interactions of the current element. Value type: string Initializes @value with the appropriate type for the @property. This function is mostly meant for language bindings, in conjunction with gtk_accessible_update_property_value(). a `GtkAccessibleProperty` an uninitialized `GValue` This interface describes ranged controls, e.g. controls which have a single value within an allowed range and that can optionally be changed by the user. This interface is expected to be implemented by controls using the following roles: - `GTK_ACCESSIBLE_ROLE_METER` - `GTK_ACCESSIBLE_ROLE_PROGRESS_BAR` - `GTK_ACCESSIBLE_ROLE_SCROLLBAR` - `GTK_ACCESSIBLE_ROLE_SLIDER` - `GTK_ACCESSIBLE_ROLE_SPIN_BUTTON` If that is not the case, a warning will be issued at run time. In addition to this interface, its implementers are expected to provide the correct values for the following properties: - `GTK_ACCESSIBLE_PROPERTY_VALUE_MAX` - `GTK_ACCESSIBLE_PROPERTY_VALUE_MIN` - `GTK_ACCESSIBLE_PROPERTY_VALUE_NOW` - `GTK_ACCESSIBLE_PROPERTY_VALUE_TEXT` Sets the current value of the accessible range. This operation should behave similarly as if the user performed the action. true if the operation was performed, false otherwise a `GtkAccessibleRange` the value to set true if the operation was performed, false otherwise a `GtkAccessibleRange` the value to set The possible accessible relations of a [iface@Accessible]. Accessible relations can be references to other widgets, integers or strings. Identifies the currently active element when focus is on a composite widget, combobox, textbox, group, or application. Value type: reference Defines the total number of columns in a table, grid, or treegrid. Value type: integer Defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid. Value type: integer Defines a human readable text alternative of %GTK_ACCESSIBLE_RELATION_COL_INDEX. Value type: string Defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid. Value type: integer Identifies the element (or elements) whose contents or presence are controlled by the current element. Value type: reference Identifies the element (or elements) that describes the object. Value type: reference Identifies the element (or elements) that provide additional information related to the object. Value type: reference Identifies the element that provides an error message for an object. Value type: reference Identifies the next element (or elements) in an alternate reading order of content which, at the user's discretion, allows assistive technology to override the general default of reading in document source order. Value type: reference Identifies the element (or elements) that labels the current element. Value type: reference Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between elements where the widget hierarchy cannot be used to represent the relationship. Value type: reference Defines an element's number or position in the current set of listitems or treeitems. Value type: integer Defines the total number of rows in a table, grid, or treegrid. Value type: integer Defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid. Value type: integer Defines a human readable text alternative of aria-rowindex. Value type: string Defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid. Value type: integer Defines the number of items in the current set of listitems or treeitems. Value type: integer Initializes @value with the appropriate type for the @relation. This function is mostly meant for language bindings, in conjunction with gtk_accessible_update_relation_value(). a `GtkAccessibleRelation` an uninitialized `GValue` The accessible role for a [iface@Accessible] implementation. Abstract roles are only used as part of the ontology; application developers must not use abstract roles in their code. An element with important, and usually time-sensitive, information A type of dialog that contains an alert message Unused An input element that allows for user-triggered actions when clicked or pressed Unused Unused A checkable input element that has three possible values: `true`, `false`, or `mixed` A header in a columned list. An input that controls another element, such as a list or a grid, that can dynamically pop up to help the user set the value of the input Abstract role. Abstract role. A dialog is a window that is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response. Content that assistive technology users may want to browse in a reading mode. Unused Unused A nameless container that has no semantic meaning of its own. This is the role that GTK uses by default for widgets. A grid of items. An item in a grid or tree grid. An element that groups multiple related widgets. GTK uses this role for various containers, like [class@Gtk.HeaderBar] or [class@Gtk.Notebook]. Unused An image. Abstract role. A visible name or caption for a user interface component. Abstract role. Unused A clickable link. A list of items. Unused. An item in a list. Unused Unused Unused Unused An element that represents a value within a known range. A menu. A menubar. An item in a menu. A check item in a menu. A radio item in a menu. Unused An element that is not represented to accessibility technologies. This role is synonymous to @GTK_ACCESSIBLE_ROLE_PRESENTATION. Unused Unused An element that is not represented to accessibility technologies. This role is synonymous to @GTK_ACCESSIBLE_ROLE_NONE. An element that displays the progress status for tasks that take a long time. A checkable input in a group of radio roles, only one of which can be checked at a time. Unused Abstract role. Unused A row in a columned list. Unused Unused A graphical object that controls the scrolling of content within a viewing area, regardless of whether the content is fully displayed within the viewing area. Unused A type of textbox intended for specifying search criteria. Abstract role. Abstract role. Abstract role. A divider that separates and distinguishes sections of content or groups of menuitems. A user input where the user selects a value from within a given range. A form of range that expects the user to select from among discrete choices. Unused Abstract role. A type of checkbox that represents on/off values, as opposed to checked/unchecked values. An item in a list of tab used for switching pages. Unused A list of tabs for switching pages. A page in a notebook or stack. A type of input that allows free-form text as its value. Unused Unused Unused Unused Unused A treeview-like, columned list. Unused Abstract role for interactive components of a graphical user interface Abstract role for windows. A type of push button which stays pressed until depressed by a second activation. A toplevel element of a graphical user interface. This is the role that GTK uses by default for windows. A paragraph of content. A section of content that is quoted from another source. A section of a page that consists of a composition that forms an independent part of a document, page, or site. A comment contains content expressing reaction to other content. A virtual terminal. The possible values for the %GTK_ACCESSIBLE_PROPERTY_SORT accessible property. There is no defined sort applied to the column. Items are sorted in ascending order by this column. Items are sorted in descending order by this column. A sort algorithm other than ascending or descending has been applied. The possible accessible states of a [iface@Accessible]. A “busy” state. This state has boolean values A “checked” state; indicates the current state of a [class@CheckButton]. Value type: [enum@AccessibleTristate] A “disabled” state; corresponds to the [property@Widget:sensitive] property. It indicates a UI element that is perceivable, but not editable or operable. Value type: boolean An “expanded” state; corresponds to the [property@Expander:expanded] property. Value type: boolean or undefined A “hidden” state; corresponds to the [property@Widget:visible] property. You can use this state explicitly on UI elements that should not be exposed to an assistive technology. Value type: boolean See also: %GTK_ACCESSIBLE_STATE_DISABLED An “invalid” state; set when a widget is showing an error. Value type: [enum@AccessibleInvalidState] A “pressed” state; indicates the current state of a [class@ToggleButton]. Value type: [enum@AccessibleTristate] enumeration A “selected” state; set when a widget is selected. Value type: boolean or undefined Indicates that a widget with the GTK_ACCESSIBLE_ROLE_LINK has been visited. Value type: boolean. Initializes @value with the appropriate type for the @state. This function is mostly meant for language bindings, in conjunction with gtk_accessible_update_relation_state(). a `GtkAccessibleState` an uninitialized `GValue` An interface for accessible objects containing formatted text. The `GtkAccessibleText` interfaces is meant to be implemented by accessible objects that have text formatted with attributes, or non-trivial text contents. You should use the [enum@Gtk.AccessibleProperty.LABEL] or the [enum@Gtk.AccessibleProperty.DESCRIPTION] properties for accessible objects containing simple, unformatted text. Retrieves the text attributes inside the accessible object. Each attribute is composed by: - a range - a name - a value It is left to the implementation to determine the serialization format of the value to a string. GTK provides support for various text attribute names and values, but implementations of this interface are free to add their own attributes. If this function returns true, `n_ranges` will be set to a value greater than or equal to one, @ranges will be set to a newly allocated array of [struct#Gtk.AccessibleTextRange]. true if the accessible object has at least an attribute, and false otherwise the accessible object the offset, in characters the number of attributes the ranges of the attributes inside the accessible object the names of the attributes inside the accessible object the values of the attributes inside the accessible object Retrieves the position of the caret inside the accessible object. the position of the caret, in characters the accessible object Retrieve the current contents of the accessible object within the given range. If @end is `G_MAXUINT`, the end of the range is the full content of the accessible object. the requested slice of the contents of the accessible object, as UTF-8. Note that the slice does not have to be NUL-terminated the accessible object the beginning of the range, in characters the end of the range, in characters Retrieve the current contents of the accessible object starting from the given offset, and using the given granularity. The @start and @end values contain the boundaries of the text. the requested slice of the contents of the accessible object, as UTF-8. Note that the slice does not have to be NUL-terminated the accessible object the offset, in characters the granularity of the query the start of the range, in characters the end of the range, in characters Retrieves the default text attributes inside the accessible object. Each attribute is composed by: - a name - a value It is left to the implementation to determine the serialization format of the value to a string. GTK provides support for various text attribute names and values, but implementations of this interface are free to add their own attributes. the accessible object the names of the default attributes inside the accessible object the values of the default attributes inside the accessible object Obtains the extents of a range of text, in widget coordinates. true if the extents were filled in, false otherwise the accessible object the start offset, in characters the end offset, in characters, @extents (out caller-allocates): return location for the extents Gets the text offset at a given point. true if the offset was set, false otherwise the accessible object a point in widget coordinates of @self return location for the text offset at @point Retrieves the selection ranges in the accessible object. If this function returns true, `n_ranges` will be set to a value greater than or equal to one, and @ranges will be set to a newly allocated array of [struct#Gtk.AccessibleTextRange]. true if there is at least a selection inside the accessible object, and false otherwise the accessible object the number of selection ranges the selection ranges Updates the position of the caret. Implementations of the `GtkAccessibleText` interface should call this function every time the caret has moved, in order to notify assistive technologies. the accessible object Notifies assistive technologies of a change in contents. Implementations of the `GtkAccessibleText` interface should call this function every time their contents change as the result of an operation, like an insertion or a removal. Note: If the change is a deletion, this function must be called *before* removing the contents, if it is an insertion, it must be called *after* inserting the new contents. the accessible object the type of change in the contents the starting offset of the change, in characters the end offset of the change, in characters Updates the boundary of the selection. Implementations of the `GtkAccessibleText` interface should call this function every time the selection has moved, in order to notify assistive technologies. the accessible object The type of contents change operation. contents change as the result of an insert operation contents change as the result of a remove operation The granularity for queries about the text contents of a [iface@Gtk.AccessibleText] implementation. Use the boundary between characters (including non-printing characters) Use the boundary between words, starting from the beginning of the current word and ending at the beginning of the next word Use the boundary between sentences, starting from the beginning of the current sentence and ending at the beginning of the next sentence Use the boundary between lines, starting from the beginning of the current line and ending at the beginning of the next line Use the boundary between paragraphs, starting from the beginning of the current paragraph and ending at the beginning of the next paragraph The interface vtable for accessible objects containing text. the requested slice of the contents of the accessible object, as UTF-8. Note that the slice does not have to be NUL-terminated the accessible object the beginning of the range, in characters the end of the range, in characters the requested slice of the contents of the accessible object, as UTF-8. Note that the slice does not have to be NUL-terminated the accessible object the offset, in characters the granularity of the query the start of the range, in characters the end of the range, in characters the position of the caret, in characters the accessible object true if there is at least a selection inside the accessible object, and false otherwise the accessible object the number of selection ranges the selection ranges true if the accessible object has at least an attribute, and false otherwise the accessible object the offset, in characters the number of attributes the ranges of the attributes inside the accessible object the names of the attributes inside the accessible object the values of the attributes inside the accessible object the accessible object the names of the default attributes inside the accessible object the values of the default attributes inside the accessible object true if the extents were filled in, false otherwise the accessible object the start offset, in characters the end offset, in characters, @extents (out caller-allocates): return location for the extents true if the offset was set, false otherwise the accessible object a point in widget coordinates of @self return location for the text offset at @point A range inside the text of an accessible object. the start of the range, in characters the length of the range, in characters The possible values for the %GTK_ACCESSIBLE_STATE_PRESSED accessible state. Note that the %GTK_ACCESSIBLE_TRISTATE_FALSE and %GTK_ACCESSIBLE_TRISTATE_TRUE have the same values as %FALSE and %TRUE. The state is `false` The state is `true` The state is `mixed` `GtkActionBar` is designed to present contextual actions.  It is expected to be displayed below the content and expand horizontally to fill the area. It allows placing children at the start or the end. In addition, it contains an internal centered box which is centered with respect to the full width of the box, even if the children at either side take up different amounts of space. # GtkActionBar as GtkBuildable The `GtkActionBar` implementation of the `GtkBuildable` interface supports adding children at the start or end sides by specifying “start” or “end” as the “type” attribute of a `<child>` element, or setting the center widget by specifying “center” value. # CSS nodes ``` actionbar ╰── revealer ╰── box ├── box.start │ ╰── [start children] ├── [center widget] ╰── box.end ╰── [end children] ``` A `GtkActionBar`'s CSS node is called `actionbar`. It contains a `revealer` subnode, which contains a `box` subnode, which contains two `box` subnodes at the start and end of the action bar, with `start` and `end style classes respectively, as well as a center node that represents the center child. Each of the boxes contains children packed for that side. Creates a new `GtkActionBar` widget. a new `GtkActionBar` Retrieves the center bar widget of the bar. the center `GtkWidget` a `GtkActionBar` Gets whether the contents of the action bar are revealed. the current value of the [property@Gtk.ActionBar:revealed] property a `GtkActionBar` Adds @child to @action_bar, packed with reference to the end of the @action_bar. A `GtkActionBar` the `GtkWidget` to be added to @action_bar Adds @child to @action_bar, packed with reference to the start of the @action_bar. A `GtkActionBar` the `GtkWidget` to be added to @action_bar Removes a child from @action_bar. a `GtkActionBar` the `GtkWidget` to be removed Sets the center widget for the `GtkActionBar`. a `GtkActionBar` a widget to use for the center Reveals or conceals the content of the action bar. Note: this does not show or hide @action_bar in the [property@Gtk.Widget:visible] sense, so revealing has no effect if the action bar is hidden. a `GtkActionBar` The new value of the property Controls whether the action bar shows its contents. The `GtkActionable` interface provides a convenient way of associating widgets with actions. It primarily consists of two properties: [property@Gtk.Actionable:action-name] and [property@Gtk.Actionable:action-target]. There are also some convenience APIs for setting these properties. The action will be looked up in action groups that are found among the widgets ancestors. Most commonly, these will be the actions with the “win.” or “app.” prefix that are associated with the `GtkApplicationWindow` or `GtkApplication`, but other action groups that are added with [method@Gtk.Widget.insert_action_group] will be consulted as well. Gets the action name for @actionable. the action name a `GtkActionable` widget Gets the current target value of @actionable. the current target value a `GtkActionable` widget Specifies the name of the action with which this widget should be associated. If @action_name is %NULL 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 `GtkApplicationWindow`. Names are of the form “win.save” or “app.quit” for actions on the containing [class@ApplicationWindow] or its associated [class@Application], respectively. This is the same form used for actions in the [class@Gio.Menu] associated with the window. a `GtkActionable` widget an action name Sets the target value of an actionable widget. If @target_value is %NULL 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 `GtkActionable` 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 [iface@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). a `GtkActionable` widget a [struct@GLib.Variant] to set as the target value Gets the action name for @actionable. the action name a `GtkActionable` widget Gets the current target value of @actionable. the current target value a `GtkActionable` widget Specifies the name of the action with which this widget should be associated. If @action_name is %NULL 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 `GtkApplicationWindow`. Names are of the form “win.save” or “app.quit” for actions on the containing [class@ApplicationWindow] or its associated [class@Application], respectively. This is the same form used for actions in the [class@Gio.Menu] associated with the window. a `GtkActionable` widget an action name Sets the target of an actionable widget. This is a convenience function that calls [ctor@GLib.Variant.new] for @format_string and uses the result to call [method@Gtk.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 [method@Gtk.Actionable.set_detailed_action_name]. a `GtkActionable` widget a [struct@GLib.Variant] format string arguments appropriate for @format_string Sets the target value of an actionable widget. If @target_value is %NULL 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 `GtkActionable` 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 [iface@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). a `GtkActionable` widget a [struct@GLib.Variant] to set as the target value Sets the action-name and associated string target value of an actionable widget. @detailed_action_name is a string in the format accepted by [func@Gio.Action.parse_detailed_name]. a `GtkActionable` widget the detailed action name The name of the action with which this widget should be associated. The target value of the actionable widget's action. The interface vtable for `GtkActionable`. virtual function for [method@Actionable.get_action_name] the action name a `GtkActionable` widget virtual function for [method@Actionable.set_action_name] a `GtkActionable` widget an action name virtual function for [method@Actionable.get_action_target_value] the current target value a `GtkActionable` widget virtual function for [method@Actionable.set_action_target_value] a `GtkActionable` widget a [struct@GLib.Variant] to set as the target value A `GtkShortcutAction` that calls gtk_widget_activate(). Gets the activate action. This is an action that calls gtk_widget_activate() on the given widget upon activation. The activate action `GtkAdjustment` is a model for a numeric value. The `GtkAdjustment` has an associated lower and upper bound. It also contains step and page increments, and a page size. Adjustments are used within several GTK widgets, including [class@Gtk.SpinButton], [class@Gtk.Viewport], [class@Gtk.Scrollbar] and [class@Gtk.Scale]. The `GtkAdjustment` object does not update the value itself. Instead it is left up to the owner of the `GtkAdjustment` to control the value. Creates a new `GtkAdjustment`. a new `GtkAdjustment` the initial value the minimum value the maximum value the step increment the page increment the page size Updates the value property to ensure that the range between @lower and @upper is in the current page. The current page goes from `value` to `value` + `page-size`. If the range is larger than the page size, then only the start of it will be in the current page. A [signal@Gtk.Adjustment::value-changed] signal will be emitted if the value is changed. a `GtkAdjustment` the lower value the upper value Sets all properties of the adjustment at once. Use this function to avoid multiple emissions of the [signal@Gtk.Adjustment::changed] signal. See [method@Gtk.Adjustment.set_lower] for an alternative way of compressing multiple emissions of [signal@Gtk.Adjustment::changed] into one. a `GtkAdjustment` the new value the new minimum value the new maximum value the new step increment the new page increment the new page size Retrieves the minimum value of the adjustment. The current minimum value of the adjustment a `GtkAdjustment` Gets the smaller of step increment and page increment. the minimum increment of @adjustment a `GtkAdjustment` Retrieves the page increment of the adjustment. The current page increment of the adjustment a `GtkAdjustment` Retrieves the page size of the adjustment. The current page size of the adjustment a `GtkAdjustment` Retrieves the step increment of the adjustment. The current step increment of the adjustment. a `GtkAdjustment` Retrieves the maximum value of the adjustment. The current maximum value of the adjustment a `GtkAdjustment` Gets the current value of the adjustment. The current value of the adjustment a `GtkAdjustment` Sets the minimum value of the adjustment. When setting multiple adjustment properties via their individual setters, multiple [signal@Gtk.Adjustment::changed] signals will be emitted. However, since the emission of the [signal@Gtk.Adjustment::changed] signal is tied to the emission of the ::notify signals of the changed properties, it’s possible to compress the [signal@Gtk.Adjustment::changed] signals into one by calling g_object_freeze_notify() and g_object_thaw_notify() around the calls to the individual setters. Alternatively, using a single g_object_set() for all the properties to change, or using [method@Gtk.Adjustment.configure] has the same effect. a `GtkAdjustment` the new minimum value Sets the page increment of the adjustment. See [method@Gtk.Adjustment.set_lower] about how to compress multiple emissions of the [signal@Gtk.Adjustment::changed] signal when setting multiple adjustment properties. a `GtkAdjustment` the new page increment Sets the page size of the adjustment. See [method@Gtk.Adjustment.set_lower] about how to compress multiple emissions of the [signal@Gtk.Adjustment::changed] signal when setting multiple adjustment properties. a `GtkAdjustment` the new page size Sets the step increment of the adjustment. See [method@Gtk.Adjustment.set_lower] about how to compress multiple emissions of the [signal@Gtk.Adjustment::changed] signal when setting multiple adjustment properties. a `GtkAdjustment` 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 [method@Gtk.Adjustment.set_lower] about how to compress multiple emissions of the [signal@Gtk.Adjustment::changed] signal when setting multiple adjustment properties. a `GtkAdjustment` the new maximum value Sets the `GtkAdjustment` value. The value is clamped to lie between [property@Gtk.Adjustment:lower] and [property@Gtk.Adjustment:upper]. Note that for adjustments which are used in a `GtkScrollbar`, the effective range of allowed values goes from [property@Gtk.Adjustment:lower] to [property@Gtk.Adjustment:upper] - [property@Gtk.Adjustment:page-size]. a `GtkAdjustment` the new value The minimum value 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 `GtkSpinButton`. 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 value of the adjustment. Emitted when one or more of the `GtkAdjustment` properties have been changed. Note that the [property@Gtk.Adjustment:value] property is covered by the [signal@Gtk.Adjustment::value-changed] signal. Emitted when the value has been changed. A `GtkAlertDialog` object collects the arguments that are needed to present a message to the user. The message is shown with the [method@Gtk.AlertDialog.choose] function. If you don't need to wait for a button to be clicked, you can use [method@Gtk.AlertDialog.show]. Creates a new `GtkAlertDialog` object. The message will be set to the formatted string resulting from the arguments. the new `GtkAlertDialog` printf()-style format string arguments for @format This function shows the alert to the user. It is ok to pass `NULL` for the callback if the alert does not have more than one button. A simpler API for this case is [method@Gtk.AlertDialog.show]. a `GtkAlertDialog` the parent `GtkWindow` a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.AlertDialog.choose] call and returns the index of the button that was clicked. the index of the button that was clicked, or -1 if the dialog was cancelled and [property@Gtk.AlertDialog:cancel-button] is not set a `GtkAlertDialog` a `GAsyncResult` Returns the button labels for the alert. the button labels a `GtkAlertDialog` Returns the index of the cancel button. the index of the cancel button, or -1 a `GtkAlertDialog` Returns the index of the default button. the index of the default button, or -1 a `GtkAlertDialog` Returns the detail text that will be shown in the alert. the detail text a `GtkAlertDialog` Returns the message that will be shown in the alert. the message a `GtkAlertDialog` Returns whether the alert blocks interaction with the parent window while it is presented. `TRUE` if the alert is modal a `GtkAlertDialog` Sets the button labels for the alert. a `GtkAlertDialog` the new button labels Sets the index of the cancel button. See [property@Gtk.AlertDialog:cancel-button] for details of how this value is used. a `GtkAlertDialog` the new cancel button Sets the index of the default button. See [property@Gtk.AlertDialog:default-button] for details of how this value is used. a `GtkAlertDialog` the new default button Sets the detail text that will be shown in the alert. a `GtkAlertDialog` the new detail text Sets the message that will be shown in the alert. a `GtkAlertDialog` the new message Sets whether the alert blocks interaction with the parent window while it is presented. a `GtkAlertDialog` the new value Show the alert to the user. This function is a simple version of [method@Gtk.AlertDialog.choose] intended for dialogs with a single button. If you want to cancel the dialog or if the alert has more than one button, you should use that function instead and provide it with a #GCancellable or callback respectively. a `GtkAlertDialog` the parent `GtkWindow` Labels for buttons to show in the alert. The labels should be translated and may contain a _ to indicate the mnemonic character. If this property is not set, then a 'Close' button is automatically created. This property determines what happens when the Escape key is pressed while the alert is shown. If this property holds the index of a button in [property@Gtk.AlertDialog:buttons], then pressing Escape is treated as if that button was pressed. If it is -1 or not a valid index for the `buttons` array, then an error is returned. If `buttons` is `NULL`, then the automatically created 'Close' button is treated as both cancel and default button, so 0 is returned. This property determines what happens when the Return key is pressed while the alert is shown. If this property holds the index of a button in [property@Gtk.AlertDialog:buttons], then pressing Return is treated as if that button was pressed. If it is -1 or not a valid index for the `buttons` array, then nothing happens. If `buttons` is `NULL`, then the automatically created 'Close' button is treated as both cancel and default button, so 0 is returned. The detail text for the alert. The message for the alert. Whether the alert is modal. Controls how a widget deals with extra space in a single dimension. Alignment only matters if the widget receives a “too large” allocation, for example if you packed the widget with the [property@Gtk.Widget:hexpand] property inside a [class@Box], then the widget might get extra space. If you have for example a 16x16 icon inside a 32x32 space, the icon could be scaled and stretched, it could be centered, or it could be positioned to one side of the space. Note that in horizontal context `GTK_ALIGN_START` and `GTK_ALIGN_END` are interpreted relative to text direction. Baseline support is optional for containers and widgets, and is only available for vertical alignment. `GTK_ALIGN_BASELINE_CENTER and `GTK_ALIGN_BASELINE_FILL` are treated similar to `GTK_ALIGN_CENTER` and `GTK_ALIGN_FILL`, except that it positions the widget to line up the baselines, where that is supported. 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 a different name for `GTK_ALIGN_BASELINE`. align the widget according to the baseline. Use `GTK_ALIGN_BASELINE_FILL` instead stretch to fill all space, but align the baseline. A `GtkShortcutTrigger` that combines two triggers. The `GtkAlternativeTrigger` triggers when either of two trigger. This can be cascaded to combine more than two triggers. Creates a `GtkShortcutTrigger` that will trigger whenever either of the two given triggers gets triggered. Note that nesting is allowed, so if you want more than two alternative, create a new alternative trigger for each option. a new `GtkShortcutTrigger` The first trigger that may trigger The second trigger that may trigger Gets the first of the two alternative triggers that may trigger @self. [method@Gtk.AlternativeTrigger.get_second] will return the other one. the first alternative trigger an alternative `GtkShortcutTrigger` Gets the second of the two alternative triggers that may trigger @self. [method@Gtk.AlternativeTrigger.get_first] will return the other one. the second alternative trigger an alternative `GtkShortcutTrigger` The first `GtkShortcutTrigger` to check. The second `GtkShortcutTrigger` to check. `GtkAnyFilter` matches an item when at least one of its filters matches. To add filters to a `GtkAnyFilter`, use [method@Gtk.MultiFilter.append]. Creates a new empty "any" filter. Use [method@Gtk.MultiFilter.append] to add filters to it. This filter matches an item if any of the filters added to it matches the item. In particular, this means that if no filter has been added to it, the filter matches no item. a new `GtkAnyFilter` `GtkAppChooser` is an interface for widgets which allow the user to choose an application. The main objects that implement this interface are [class@Gtk.AppChooserWidget], [class@Gtk.AppChooserDialog] and [class@Gtk.AppChooserButton]. Applications are represented by GIO `GAppInfo` objects here. GIO has a concept of recommended and fallback applications for a given content type. Recommended applications are those that claim to handle the content type itself, while fallback also includes applications that handle a more generic content type. GIO also knows the default and last-used application for a given content type. The `GtkAppChooserWidget` provides detailed control over whether the shown list of applications should include default, recommended or fallback applications. To obtain the application that has been selected in a `GtkAppChooser`, use [method@Gtk.AppChooser.get_app_info]. The application selection widgets should be implemented according to the design of each platform and/or application requiring them. Returns the currently selected application. This widget will be removed in GTK 5 a `GAppInfo` for the currently selected application a `GtkAppChooser` Returns the content type for which the `GtkAppChooser` shows applications. This widget will be removed in GTK 5 the content type of @self. Free with g_free() a `GtkAppChooser` Reloads the list of applications. This widget will be removed in GTK 5 a `GtkAppChooser` The content type of the `GtkAppChooser` object. See `GContentType` for more information about content types. The `GtkAppChooserButton` lets the user select an application.  Initially, a `GtkAppChooserButton` selects the first application in its list, which will either be the most-recently used application or, if [property@Gtk.AppChooserButton:show-default-item] is %TRUE, the default application. The list of applications shown in a `GtkAppChooserButton` includes the recommended applications for the given content type. When [property@Gtk.AppChooserButton:show-default-item] is set, the default application is also included. To let the user chooser other applications, you can set the [property@Gtk.AppChooserButton:show-dialog-item] property, which allows to open a full [class@Gtk.AppChooserDialog]. It is possible to add custom items to the list, using [method@Gtk.AppChooserButton.append_custom_item]. These items cause the [signal@Gtk.AppChooserButton::custom-item-activated] signal to be emitted when they are selected. To track changes in the selected application, use the [signal@Gtk.AppChooserButton::changed] signal. ## CSS nodes `GtkAppChooserButton` has a single CSS node with the name “appchooserbutton”. The application selection widgets should be implemented according to the design of each platform and/or application requiring them. Creates a new `GtkAppChooserButton` for applications that can handle content of the given type. This widget will be removed in GTK 5 a newly created `GtkAppChooserButton` the content type to show applications for 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 [signal@Gtk.AppChooserButton::custom-item-activated] signal, to add a callback for the activation of a particular custom item in the list. See also [method@Gtk.AppChooserButton.append_separator]. This widget will be removed in GTK 5 a `GtkAppChooserButton` the name of the custom item the label for the custom item the icon for the custom item Appends a separator to the list of applications that is shown in the popup. This widget will be removed in GTK 5 a `GtkAppChooserButton` Returns the text to display at the top of the dialog. This widget will be removed in GTK 5 the text to display at the top of the dialog, or %NULL, in which case a default text is displayed a `GtkAppChooserButton` Gets whether the dialog is modal. This widget will be removed in GTK 5 %TRUE if the dialog is modal a `GtkAppChooserButton` Returns whether the dropdown menu should show the default application at the top. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserButton:show-default-item] a `GtkAppChooserButton` Returns whether the dropdown menu shows an item for a `GtkAppChooserDialog`. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserButton:show-dialog-item] a `GtkAppChooserButton` Selects a custom item. See [method@Gtk.AppChooserButton.append_custom_item]. Use [method@Gtk.AppChooser.refresh] to bring the selection to its initial state. This widget will be removed in GTK 5 a `GtkAppChooserButton` 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. This widget will be removed in GTK 5 a `GtkAppChooserButton` a string containing Pango markup Sets whether the dialog should be modal. This widget will be removed in GTK 5 a `GtkAppChooserButton` %TRUE to make the dialog modal Sets whether the dropdown menu of this button should show the default application for the given content type at top. This widget will be removed in GTK 5 a `GtkAppChooserButton` the new value for [property@Gtk.AppChooserButton:show-default-item] Sets whether the dropdown menu of this button should show an entry to trigger a `GtkAppChooserDialog`. This widget will be removed in GTK 5 a `GtkAppChooserButton` the new value for [property@Gtk.AppChooserButton:show-dialog-item] The text to show at the top of the dialog that can be opened from the button. The string may contain Pango markup. Whether the app chooser dialog should be modal. Determines whether the dropdown menu shows the default application on top for the provided content type. Determines whether the dropdown menu shows an item to open a `GtkAppChooserDialog`. Emitted to when the button is activated. The `::activate` signal on `GtkAppChooserButton` is an action signal and emitting it causes the button to pop up its dialog. Emitted when the active application changes. Emitted when a custom item is activated. Use [method@Gtk.AppChooserButton.append_custom_item], to add custom items. the name of the activated item `GtkAppChooserDialog` shows a `GtkAppChooserWidget` inside a `GtkDialog`.  Note that `GtkAppChooserDialog` does not have any interesting methods of its own. Instead, you should get the embedded `GtkAppChooserWidget` using [method@Gtk.AppChooserDialog.get_widget] and call its methods if the generic [iface@Gtk.AppChooser] interface is not sufficient for your needs. To set the heading that is shown above the `GtkAppChooserWidget`, use [method@Gtk.AppChooserDialog.set_heading]. ## CSS nodes `GtkAppChooserDialog` has a single CSS node with the name `window` and style class `.appchooser`. The application selection widgets should be implemented according to the design of each platform and/or application requiring them. Creates a new `GtkAppChooserDialog` for the provided `GFile`. The dialog will show applications that can open the file. This widget will be removed in GTK 5 a newly created `GtkAppChooserDialog` a `GtkWindow` flags for this dialog a `GFile` Creates a new `GtkAppChooserDialog` for the provided content type. The dialog will show applications that can open the content type. This widget will be removed in GTK 5 a newly created `GtkAppChooserDialog` a `GtkWindow` flags for this dialog a content type string Returns the text to display at the top of the dialog. This widget will be removed in GTK 5 the text to display at the top of the dialog, or %NULL, in which case a default text is displayed a `GtkAppChooserDialog` Returns the `GtkAppChooserWidget` of this dialog. This widget will be removed in GTK 5 the `GtkAppChooserWidget` of @self a `GtkAppChooserDialog` Sets the text to display at the top of the dialog. If the heading is not set, the dialog displays a default text. This widget will be removed in GTK 5 a `GtkAppChooserDialog` a string containing Pango markup The GFile used by the `GtkAppChooserDialog`. The dialog's `GtkAppChooserWidget` 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. `GtkAppChooserWidget` is a widget for selecting applications. It is the main building block for [class@Gtk.AppChooserDialog]. Most applications only need to use the latter; but you can use this widget as part of a larger widget if you have special needs. `GtkAppChooserWidget` offers detailed control over what applications are shown, using the [property@Gtk.AppChooserWidget:show-default], [property@Gtk.AppChooserWidget:show-recommended], [property@Gtk.AppChooserWidget:show-fallback], [property@Gtk.AppChooserWidget:show-other] and [property@Gtk.AppChooserWidget:show-all] properties. See the [iface@Gtk.AppChooser] documentation for more information about these groups of applications. To keep track of the selected application, use the [signal@Gtk.AppChooserWidget::application-selected] and [signal@Gtk.AppChooserWidget::application-activated] signals. ## CSS nodes `GtkAppChooserWidget` has a single CSS node with name appchooser. The application selection widgets should be implemented according to the design of each platform and/or application requiring them. Creates a new `GtkAppChooserWidget` for applications that can handle content of the given type. This widget will be removed in GTK 5 a newly created `GtkAppChooserWidget` the content type to show applications for Returns the text that is shown if there are not applications that can handle the content type. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserWidget:default-text] a `GtkAppChooserWidget` Gets whether the app chooser should show all applications in a flat list. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserWidget:show-all] a `GtkAppChooserWidget` Gets whether the app chooser should show the default handler for the content type in a separate section. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserWidget:show-default] a `GtkAppChooserWidget` Gets whether the app chooser should show related applications for the content type in a separate section. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserWidget:show-fallback] a `GtkAppChooserWidget` Gets whether the app chooser should show applications which are unrelated to the content type. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserWidget:show-other] a `GtkAppChooserWidget` Gets whether the app chooser should show recommended applications for the content type in a separate section. This widget will be removed in GTK 5 the value of [property@Gtk.AppChooserWidget:show-recommended] a `GtkAppChooserWidget` Sets the text that is shown if there are not applications that can handle the content type. This widget will be removed in GTK 5 a `GtkAppChooserWidget` the new value for [property@Gtk.AppChooserWidget:default-text] Sets whether the app chooser should show all applications in a flat list. This widget will be removed in GTK 5 a `GtkAppChooserWidget` the new value for [property@Gtk.AppChooserWidget:show-all] Sets whether the app chooser should show the default handler for the content type in a separate section. This widget will be removed in GTK 5 a `GtkAppChooserWidget` the new value for [property@Gtk.AppChooserWidget:show-default] Sets whether the app chooser should show related applications for the content type in a separate section. This widget will be removed in GTK 5 a `GtkAppChooserWidget` the new value for [property@Gtk.AppChooserWidget:show-fallback] Sets whether the app chooser should show applications which are unrelated to the content type. This widget will be removed in GTK 5 a `GtkAppChooserWidget` the new value for [property@Gtk.AppChooserWidget:show-other] Sets whether the app chooser should show recommended applications for the content type in a separate section. This widget will be removed in GTK 5 a `GtkAppChooserWidget` the new value for [property@Gtk.AppChooserWidget:show-recommended] The text that appears in the widget when there are no applications for the given content type. If %TRUE, the app chooser presents all applications in a single list, without subsections for default, recommended or related applications. 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. Determines whether the app chooser should show a section for fallback applications. If %FALSE, the fallback applications are listed among the other applications. Determines whether the app chooser should show a section for other applications. Determines whether the app chooser should show a section for recommended applications. If %FALSE, the recommended applications are listed among the other applications. 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. the activated `GAppInfo` Emitted when an application item is selected from the widget's list. the selected `GAppInfo` `GtkApplication` is a high-level API for writing applications. It supports many aspects of writing a GTK application in a convenient fashion, without enforcing a one-size-fits-all model. Currently, `GtkApplication` handles GTK initialization, application uniqueness, session management, provides some basic scriptability and desktop shell integration by exporting actions and menus and manages a list of toplevel windows whose life-cycle is automatically tied to the life-cycle of your application. While `GtkApplication` works fine with plain [class@Gtk.Window]s, it is recommended to use it together with [class@Gtk.ApplicationWindow]. ## Automatic resources `GtkApplication` will automatically load menus from the `GtkBuilder` resource located at "gtk/menus.ui", relative to the application's resource base path (see [method@Gio.Application.set_resource_base_path]). The menu with the ID "menubar" is taken as the application's menubar. Additional menus (most interesting submenus) can be named and accessed via [method@Gtk.Application.get_menu_by_id] which allows for dynamic population of a part of the menu structure. Note that automatic resource loading uses the resource base path that is set at construction time and will not work if the resource base path is changed at a later time. It is also possible to provide the menubar manually using [method@Gtk.Application.set_menubar]. `GtkApplication` will also automatically setup an icon search path for the default icon theme by appending "icons" to the resource base path. This allows your application to easily store its icons as resources. See [method@Gtk.IconTheme.add_resource_path] for more information. If there is a resource located at `gtk/help-overlay.ui` which defines a [class@Gtk.ShortcutsWindow] with ID `help_overlay` then `GtkApplication` associates an instance of this shortcuts window with each [class@Gtk.ApplicationWindow] and sets up the keyboard accelerator <kbd>Control</kbd>+<kbd>?</kbd> to open it. To create a menu item that displays the shortcuts window, associate the item with the action `win.show-help-overlay`. ## A simple application [A simple example](https://gitlab.gnome.org/GNOME/gtk/tree/main/examples/bp/bloatpad.c) is available in the GTK source code repository `GtkApplication` optionally registers with a session manager of the users session (if you set the [property@Gtk.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 [method@Gtk.Application.inhibit] function. Typical use cases for this kind of inhibiting are long-running, uninterruptible operations, such as burning a CD or performing a disk backup. The session manager may not honor the inhibitor, but it can be expected to inform the user about the negative consequences of ending the session while inhibitors are present. ## See Also - [Using GtkApplication](https://developer.gnome.org/documentation/tutorials/application.html) - [Getting Started with GTK: Basics](getting_started.html#basics) Creates a new `GtkApplication` instance. When using `GtkApplication`, it is not necessary to call [func@Gtk.init] manually. It is called as soon as the application gets registered as the primary instance. Concretely, [func@Gtk.init] is called in the default handler for the `GApplication::startup` signal. Therefore, `GtkApplication` subclasses should always chain up in their `GApplication::startup` handler before using any GTK API. Note that commandline arguments are not passed to [func@Gtk.init]. If `application_id` is not %NULL, then it must be valid. See `g_application_id_is_valid()`. If no application ID is given then some features (most notably application uniqueness) will be disabled. a new `GtkApplication` instance The application ID the application flags Signal emitted when a `GtkWindow` is added to application through gtk_application_add_window(). Signal emitted when a `GtkWindow` is removed from application, either as a side-effect of being destroyed or explicitly through gtk_application_remove_window(). Adds a window to `application`. This call can only happen after the `application` has started; typically, you should add new application windows in response to the emission of the `GApplication::activate` signal. This call is equivalent to setting the [property@Gtk.Window:application] property of `window` to `application`. Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it with [method@Gtk.Application.remove_window]. GTK will keep the `application` running as long as it has any windows. a `GtkApplication` a `GtkWindow` Gets the accelerators that are currently associated with the given action. accelerators for `detailed_action_name` a `GtkApplication` a detailed action name, specifying an action and target to obtain accelerators for 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. `NULL` is never returned. It is a programmer error to pass an invalid accelerator string. If you are unsure, check it with [func@Gtk.accelerator_parse] first. a %NULL-terminated array of actions for `accel` a `GtkApplication` an accelerator that can be parsed by [func@Gtk.accelerator_parse] 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. the active window a `GtkApplication` Gets a menu from automatically loaded resources. See [the section on Automatic resources](class.Application.html#automatic-resources) for more information. Gets the menu with the given id from the automatically loaded resources a `GtkApplication` the id of the menu to look up Returns the menu model that has been set with [method@Gtk.Application.set_menubar]. the menubar for windows of `application` a `GtkApplication` Returns the [class@Gtk.ApplicationWindow] with the given ID. The ID of a `GtkApplicationWindow` can be retrieved with [method@Gtk.ApplicationWindow.get_id]. the window for the given `id` a `GtkApplication` an identifier number Gets a list of the [class@Gtk.Window] instances associated with `application`. 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. a `GList` of `GtkWindow` instances a `GtkApplication` 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 [method@Gtk.Application.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. The `reason` message 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. A non-zero cookie that is used to uniquely identify this request. It should be used as an argument to [method@Gtk.Application.uninhibit] in order to remove the request. If the platform does not support inhibiting or the request failed for some reason, 0 is returned. the `GtkApplication` a `GtkWindow` what types of actions should be inhibited a short, human-readable string that explains why these operations are inhibited Lists the detailed action names which have associated accelerators. See [method@Gtk.Application.set_accels_for_action]. the detailed action names a `GtkApplication` Remove a window from `application`. If `window` belongs to `application` then this call is equivalent to setting the [property@Gtk.Window:application] property of `window` to `NULL`. The application may stop running as a result of a call to this function, if `window` was the last window of the `application`. a `GtkApplication` a `GtkWindow` 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 `g_action_parse_detailed_name()` and `g_action_print_detailed_name()`. a `GtkApplication` a detailed action name, specifying an action and target to associate accelerators with a list of accelerators in the format understood by [func@Gtk.accelerator_parse] Sets or unsets the menubar for windows of `application`. 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. `GApplication::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 `GActionMap` interface to add actions, to respond to the user selecting these menu items. a `GtkApplication` a `GMenuModel` Removes an inhibitor that has been previously established. See [method@Gtk.Application.inhibit]. Inhibitors are also cleared when the application exits. the `GtkApplication` a cookie that was returned by [method@Gtk.Application.inhibit] The currently focused window of the application. The `GMenuModel` to be used for the application's menu bar. Set this property to `TRUE` to register with the session manager. This will make GTK track the session state (such as the [property@Gtk.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 [property@Gtk.Application:register-session] is set to %TRUE. Tracking the screensaver state is currently only supported on Linux. Emitted when the session manager is about to end the session. This signal is only emitted if [property@Gtk.Application:register-session] is `TRUE`. Applications can connect to this signal and call [method@Gtk.Application.inhibit] with `GTK_APPLICATION_INHIBIT_LOGOUT` to delay the end of the session until state has been saved. Emitted when a [class@Gtk.Window] is added to `application` through [method@Gtk.Application.add_window]. the newly-added [class@Gtk.Window] Emitted when a [class@Gtk.Window] is removed from `application`. This can happen as a side-effect of the window being destroyed or explicitly through [method@Gtk.Application.remove_window]. the [class@Gtk.Window] that is being removed The parent class. Signal emitted when a `GtkWindow` is added to application through gtk_application_add_window(). Signal emitted when a `GtkWindow` is removed from application, either as a side-effect of being destroyed or explicitly through gtk_application_remove_window(). Types of user actions that may be blocked by `GtkApplication`. See [method@Gtk.Application.inhibit]. Inhibit ending the user session by logging out or by shutting down the computer Inhibit user switching Inhibit suspending the session or computer Inhibit the session being marked as idle (and possibly locked) `GtkApplicationWindow` is a `GtkWindow` subclass that integrates with `GtkApplication`. Notably, `GtkApplicationWindow` can handle an application menubar. This class implements the `GActionGroup` and `GActionMap` interfaces, to let you add window-specific actions that will be exported by the associated [class@Gtk.Application], together with its application-wide actions. Window-specific actions are prefixed with the “win.” prefix and application-wide actions are prefixed with the “app.” prefix. Actions must be addressed with the prefixed name when referring to them from a `GMenuModel`. Note that widgets that are placed inside a `GtkApplicationWindow` can also activate these actions, if they implement the [iface@Gtk.Actionable] interface. The settings [property@Gtk.Settings:gtk-shell-shows-app-menu] and [property@Gtk.Settings:gtk-shell-shows-menubar] tell GTK whether the desktop environment is showing the application menu and menubar models outside the application as part of the desktop shell. For instance, on OS X, both menus will be displayed remotely; on Windows neither will be. If the desktop environment does not display the menubar, then `GtkApplicationWindow` will automatically show a menubar for it. This behaviour can be overridden with the [property@Gtk.ApplicationWindow:show-menubar] property. If the desktop environment does not display the application menu, then it will automatically be included in the menubar or in the windows client-side decorations. See [class@Gtk.PopoverMenu] for information about the XML language used by `GtkBuilder` for menu models. See also: [method@Gtk.Application.set_menubar]. ## A GtkApplicationWindow with a menubar The code sample below shows how to set up a `GtkApplicationWindow` with a menu bar defined on the [class@Gtk.Application]: ```c GtkApplication *app = gtk_application_new ("org.gtk.test", 0); GtkBuilder *builder = gtk_builder_new_from_string ( "<interface>" " <menu id='menubar'>" " <submenu>" " <attribute name='label' translatable='yes'>_Edit</attribute>" " <item>" " <attribute name='label' translatable='yes'>_Copy</attribute>" " <attribute name='action'>win.copy</attribute>" " </item>" " <item>" " <attribute name='label' translatable='yes'>_Paste</attribute>" " <attribute name='action'>win.paste</attribute>" " </item>" " </submenu>" " </menu>" "</interface>", -1); GMenuModel *menubar = G_MENU_MODEL (gtk_builder_get_object (builder, "menubar")); gtk_application_set_menubar (GTK_APPLICATION (app), menubar); g_object_unref (builder); // ... GtkWidget *window = gtk_application_window_new (app); ``` Creates a new `GtkApplicationWindow`. a newly created `GtkApplicationWindow` a `GtkApplication` Gets the `GtkShortcutsWindow` that is associated with @window. See [method@Gtk.ApplicationWindow.set_help_overlay]. the help overlay associated with @window a `GtkApplicationWindow` Returns the unique ID of the window. If the window has not yet been added to a `GtkApplication`, returns `0`. the unique ID for @window, or `0` if the window has not yet been added to a `GtkApplication` a `GtkApplicationWindow` Returns whether the window will display a menubar for the app menu and menubar as needed. %TRUE if @window will display a menubar when needed a `GtkApplicationWindow` Associates a shortcuts window with the application window. Additionally, sets up an action with the name `win.show-help-overlay` to present it. @window takes responsibility for destroying @help_overlay. a `GtkApplicationWindow` a `GtkShortcutsWindow` Sets whether the window will display a menubar for the app menu and menubar as needed. a `GtkApplicationWindow` whether to show a menubar when needed If this property is %TRUE, the window will display a menubar unless it is shown by the desktop shell. See [method@Gtk.Application.set_menubar]. If %FALSE, the window will not display a menubar, regardless of whether the desktop shell is showing it or not. The parent class. 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. `GtkAspectFrame` preserves the aspect ratio of its child. The frame can respect the aspect ratio of the child widget, or use its own aspect ratio. # CSS nodes `GtkAspectFrame` uses a CSS node with name `aspectframe`. # Accessibility Until GTK 4.10, `GtkAspectFrame` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. Starting from GTK 4.12, `GtkAspectFrame` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. Create a new `GtkAspectFrame`. the new `GtkAspectFrame`. Horizontal alignment of the child within the parent. Ranges from 0.0 (left aligned) to 1.0 (right aligned) Vertical alignment of the child within the parent. Ranges from 0.0 (top aligned) to 1.0 (bottom aligned) The desired aspect ratio. If %TRUE, @ratio is ignored, and the aspect ratio is taken from the requistion of the child. Gets the child widget of @self. the child widget of @self a `GtkAspectFrame` Returns whether the child's size request should override the set aspect ratio of the `GtkAspectFrame`. whether to obey the child's size request a `GtkAspectFrame` Returns the desired aspect ratio of the child. the desired aspect ratio a `GtkAspectFrame` Returns the horizontal alignment of the child within the allocation of the `GtkAspectFrame`. the horizontal alignment a `GtkAspectFrame` Returns the vertical alignment of the child within the allocation of the `GtkAspectFrame`. the vertical alignment a `GtkAspectFrame` Sets the child widget of @self. a `GtkAspectFrame` the child widget Sets whether the aspect ratio of the child's size request should override the set aspect ratio of the `GtkAspectFrame`. a `GtkAspectFrame` If %TRUE, @ratio is ignored, and the aspect ratio is taken from the requisition of the child. Sets the desired aspect ratio of the child. a `GtkAspectFrame` aspect ratio of the child Sets the horizontal alignment of the child within the allocation of the `GtkAspectFrame`. a `GtkAspectFrame` horizontal alignment, from 0.0 (left aligned) to 1.0 (right aligned) Sets the vertical alignment of the child within the allocation of the `GtkAspectFrame`. a `GtkAspectFrame` horizontal alignment, from 0.0 (top aligned) to 1.0 (bottom aligned) The child widget. Whether the `GtkAspectFrame` should use the aspect ratio of its child. The aspect ratio to be used by the `GtkAspectFrame`. This property is only used if [property@Gtk.AspectFrame:obey-child] is set to %FALSE. The horizontal alignment of the child. The vertical alignment of the child. `GtkAssistant` is used to represent a complex as a series of steps.  Each step consists of one or more pages. `GtkAssistant` guides the user through the pages, and controls the page flow to collect the data needed for the operation. `GtkAssistant` handles which buttons to show and to make sensitive based on page sequence knowledge and the [enum@Gtk.AssistantPageType] of each page in addition to state information like the *completed* and *committed* page statuses. If you have a case that doesn’t quite fit in `GtkAssistant`s way of handling buttons, you can use the %GTK_ASSISTANT_PAGE_CUSTOM page type and handle buttons yourself. `GtkAssistant` maintains a `GtkAssistantPage` object for each added child, which holds additional per-child properties. You obtain the `GtkAssistantPage` for a child with [method@Gtk.Assistant.get_page]. # GtkAssistant as GtkBuildable The `GtkAssistant` implementation of the `GtkBuildable` interface exposes the @action_area as internal children with the name “action_area”. To add pages to an assistant in `GtkBuilder`, simply add it as a child to the `GtkAssistant` object. If you need to set per-object properties, create a `GtkAssistantPage` object explicitly, and set the child widget as a property on it. # CSS nodes `GtkAssistant` has a single CSS node with the name window and style class .assistant. This widget will be removed in GTK 5 Creates a new `GtkAssistant`. This widget will be removed in GTK 5 a newly created `GtkAssistant` Adds a widget to the action area of a `GtkAssistant`. This widget will be removed in GTK 5 a `GtkAssistant` a `GtkWidget` Appends a page to the @assistant. This widget will be removed in GTK 5 the index (starting at 0) of the inserted page a `GtkAssistant` a `GtkWidget` Erases the visited page history. GTK will then hide the back button 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. This widget will be removed in GTK 5 a `GtkAssistant` Returns the page number of the current page. This widget will be removed in GTK 5 The index (starting from 0) of the current page in the @assistant, or -1 if the @assistant has no pages, or no current page a `GtkAssistant` Returns the number of pages in the @assistant This widget will be removed in GTK 5 the number of pages in the @assistant a `GtkAssistant` Returns the child widget contained in page number @page_num. This widget will be removed in GTK 5 the child widget, or %NULL if @page_num is out of bounds a `GtkAssistant` the index of a page in the @assistant, or -1 to get the last page Returns the `GtkAssistantPage` object for @child. This widget will be removed in GTK 5 the `GtkAssistantPage` for @child a `GtkAssistant` a child of @assistant Gets whether @page is complete. This widget will be removed in GTK 5 %TRUE if @page is complete. a `GtkAssistant` a page of @assistant Gets the title for @page. This widget will be removed in GTK 5 the title for @page a `GtkAssistant` a page of @assistant Gets the page type of @page. This widget will be removed in GTK 5 the page type of @page a `GtkAssistant` a page of @assistant Gets a list model of the assistant pages. This widget will be removed in GTK 5 A list model of the pages. a `GtkAssistant` Inserts a page in the @assistant at a given position. This widget will be removed in GTK 5 the index (starting from 0) of the inserted page a `GtkAssistant` a `GtkWidget` the index (starting at 0) at which to insert the page, or -1 to append the page to the @assistant 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 %GTK_ASSISTANT_PAGE_CUSTOM type. This widget will be removed in GTK 5 a `GtkAssistant` Prepends a page to the @assistant. This widget will be removed in GTK 5 the index (starting at 0) of the inserted page a `GtkAssistant` a `GtkWidget` 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 %GTK_ASSISTANT_PAGE_CUSTOM type. This widget will be removed in GTK 5 a `GtkAssistant` Removes a widget from the action area of a `GtkAssistant`. This widget will be removed in GTK 5 a `GtkAssistant` a `GtkWidget` Removes the @page_num’s page from @assistant. This widget will be removed in GTK 5 a `GtkAssistant` the index of a page in the @assistant, 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 @assistant flow can be set with gtk_assistant_set_forward_page_func(). This widget will be removed in GTK 5 a `GtkAssistant` 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 @assistant, 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 %NULL will make the assistant to use the default forward function, which just goes to the next visible page. This widget will be removed in GTK 5 a `GtkAssistant` the `GtkAssistantPageFunc`, or %NULL to use the default one user data for @page_func destroy notifier for @data Sets whether @page contents are complete. This will make @assistant update the buttons state to be able to continue the task. This widget will be removed in GTK 5 a `GtkAssistant` a page of @assistant 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. This widget will be removed in GTK 5 a `GtkAssistant` a page of @assistant the new title for @page Sets the page type for @page. The page type determines the page behavior in the @assistant. This widget will be removed in GTK 5 a `GtkAssistant` a page of @assistant the new type for @page Forces @assistant 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. This widget will be removed in GTK 5 a `GtkAssistant` `GListModel` containing the pages. %TRUE if the assistant uses a `GtkHeaderBar` 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. This widget will be removed in GTK 5 Emitted when the apply button is clicked. The default behavior of the `GtkAssistant` 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 %GTK_ASSISTANT_PAGE_PROGRESS after the confirmation page and handle this operation within the [signal@Gtk.Assistant::prepare] signal of the progress page. This widget will be removed in GTK 5 Emitted when then the cancel button is clicked. This widget will be removed in GTK 5 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 %GTK_ASSISTANT_PAGE_CONFIRM) is clicked. This widget will be removed in GTK 5 The action signal for the Escape binding. This widget will be removed in GTK 5 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. This widget will be removed in GTK 5 the current page `GtkAssistantPage` is an auxiliary object used by `GtkAssistant. This object will be removed in GTK 5 Returns the child to which @page belongs. This widget will be removed in GTK 5 the child to which @page belongs a `GtkAssistantPage` The child widget. This object will be removed in GTK 5 Whether all required fields are filled in. GTK uses this information to control the sensitivity of the navigation buttons. This object will be removed in GTK 5 The type of the assistant page. This object will be removed in GTK 5 The title of the page. This object will be removed in GTK 5 Type of callback used to calculate the next page in a `GtkAssistant`. It’s called both for computing the next page when the user presses the “forward” button and for handling the behavior of the “last” button. See [method@Gtk.Assistant.set_forward_page_func]. The next page number The page number used to calculate the next page. user data. Determines the page role inside a `GtkAssistant`. The role is used to handle buttons sensitivity and visibility. Note that an assistant needs to end its page flow with a page of type %GTK_ASSISTANT_PAGE_CONFIRM, %GTK_ASSISTANT_PAGE_SUMMARY or %GTK_ASSISTANT_PAGE_PROGRESS to be correct. The Cancel button will only be shown if the page isn’t “committed”. See gtk_assistant_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 gtk_assistant_add_action_widget(). Like [func@get_binary_age], but from the headers used at application compile time, rather than from the library linked against at application run time. This macro should be used to emit a warning about and unexpected @type value in a `GtkBuildable` add_child implementation. the `GtkBuildable` on which the warning occurred the unexpected type value Baseline position in a row of widgets. Whenever a container has some form of natural row it may align children in that row along a common typographical baseline. If the amount of vertical space in the row is taller than the total requested height of the baseline-aligned children then it can use a `GtkBaselinePosition` to select where to put the baseline inside the extra available space. Align the baseline at the top Center the baseline Align the baseline at the bottom `GtkBinLayout` is a `GtkLayoutManager` subclass useful for create "bins" of widgets. `GtkBinLayout` will stack each child of a widget on top of each other, using the [property@Gtk.Widget:hexpand], [property@Gtk.Widget:vexpand], [property@Gtk.Widget:halign], and [property@Gtk.Widget:valign] properties of each child to determine where they should be positioned. Creates a new `GtkBinLayout` instance. the newly created `GtkBinLayout` A `GtkBitset` represents a set of unsigned integers. Another name for this data structure is "bitmap". The current implementation is based on [roaring bitmaps](https://roaringbitmap.org/). A bitset allows adding a set of integers and provides support for set operations like unions, intersections and checks for equality or if a value is contained in the set. `GtkBitset` also contains various functions to query metadata about the bitset, such as the minimum or maximum values or its size. The fastest way to iterate values in a bitset is [struct@Gtk.BitsetIter]. The main use case for `GtkBitset` is implementing complex selections for [iface@Gtk.SelectionModel]. Creates a new empty bitset. A new empty bitset Creates a bitset with the given range set. A new bitset first value to add number of consecutive values to add Adds @value to @self if it wasn't part of it before. %TRUE if @value was not part of @self and @self was changed a `GtkBitset` value to add Adds all values from @start (inclusive) to @start + @n_items (exclusive) in @self. a `GtkBitset` first value to add number of consecutive values to add Adds the closed range [@first, @last], so @first, @last and all values in between. @first must be smaller than @last. a `GtkBitset` first value to add last value to add Interprets the values as a 2-dimensional boolean grid with the given @stride and inside that grid, adds a rectangle with the given @width and @height. a `GtkBitset` first value to add width of the rectangle height of the rectangle row stride of the grid Checks if the given @value has been added to @self %TRUE if @self contains @value a `GtkBitset` the value to check Creates a copy of @self. A new bitset that contains the same values as @self a `GtkBitset` Sets @self to be the symmetric difference of @self and @other. The symmetric difference is set @self to contain all values that were either contained in @self or in @other, but not in both. This operation is also called an XOR. It is allowed for @self and @other to be the same bitset. The bitset will be emptied in that case. a `GtkBitset` the `GtkBitset` to compute the difference from Returns %TRUE if @self and @other contain the same values. %TRUE if @self and @other contain the same values a `GtkBitset` another `GtkBitset` Returns the largest value in @self. If @self is empty, 0 is returned. The largest value in @self a `GtkBitset` Returns the smallest value in @self. If @self is empty, `G_MAXUINT` is returned. The smallest value in @self a `GtkBitset` Returns the value of the @nth item in self. If @nth is >= the size of @self, 0 is returned. the value of the @nth item in @self a `GtkBitset` index of the item to get Gets the number of values that were added to the set. For example, if the set is empty, 0 is returned. Note that this function returns a `guint64`, because when all values are set, the return value is `G_MAXUINT + 1`. Unless you are sure this cannot happen (it can't with `GListModel`), be sure to use a 64bit type. The number of values in the set. a `GtkBitset` Gets the number of values that are part of the set from @first to @last (inclusive). Note that this function returns a `guint64`, because when all values are set, the return value is `G_MAXUINT + 1`. Unless you are sure this cannot happen (it can't with `GListModel`), be sure to use a 64bit type. The number of values in the set from @first to @last. a `GtkBitset` the first element to include the last element to include Sets @self to be the intersection of @self and @other. In other words, remove all values from @self that are not part of @other. It is allowed for @self and @other to be the same bitset. Nothing will happen in that case. a `GtkBitset` the `GtkBitset` to intersect with Check if no value is contained in bitset. %TRUE if @self is empty a `GtkBitset` Acquires a reference on the given `GtkBitset`. the `GtkBitset` with an additional reference a `GtkBitset` Removes @value from @self if it was part of it before. %TRUE if @value was part of @self and @self was changed a `GtkBitset` value to remove Removes all values from the bitset so that it is empty again. a `GtkBitset` Removes all values from @start (inclusive) to @start + @n_items (exclusive) in @self. a `GtkBitset` first value to remove number of consecutive values to remove Removes the closed range [@first, @last], so @first, @last and all values in between. @first must be smaller than @last. a `GtkBitset` first value to remove last value to remove Interprets the values as a 2-dimensional boolean grid with the given @stride and inside that grid, removes a rectangle with the given @width and @height. a `GtkBitset` first value to remove width of the rectangle height of the rectangle row stride of the grid Shifts all values in @self to the left by @amount. Values smaller than @amount are discarded. a `GtkBitset` amount to shift all values to the left Shifts all values in @self to the right by @amount. Values that end up too large to be held in a #guint are discarded. a `GtkBitset` amount to shift all values to the right This is a support function for `GListModel` handling, by mirroring the `GlistModel::items-changed` signal. First, it "cuts" the values from @position to @removed from the bitset. That is, it removes all those values and shifts all larger values to the left by @removed places. Then, it "pastes" new room into the bitset by shifting all values larger than @position by @added spaces to the right. This frees up space that can then be filled. a `GtkBitset` position at which to slice number of values to remove number of values to add Sets @self to be the subtraction of @other from @self. In other words, remove all values from @self that are part of @other. It is allowed for @self and @other to be the same bitset. The bitset will be emptied in that case. a `GtkBitset` the `GtkBitset` to subtract Sets @self to be the union of @self and @other. That is, add all values from @other into @self that weren't part of it. It is allowed for @self and @other to be the same bitset. Nothing will happen in that case. a `GtkBitset` the `GtkBitset` to union with Releases a reference on the given `GtkBitset`. If the reference was the last, the resources associated to the @self are freed. a `GtkBitset` An opaque, stack-allocated struct for iterating over the elements of a `GtkBitset`. Before a `GtkBitsetIter` can be used, it needs to be initialized with [func@Gtk.BitsetIter.init_first], [func@Gtk.BitsetIter.init_last] or [func@Gtk.BitsetIter.init_at]. Gets the current value that @iter points to. If @iter is not valid and [method@Gtk.BitsetIter.is_valid] returns %FALSE, this function returns 0. The current value pointer to by @iter a `GtkBitsetIter` Checks if @iter points to a valid value. %TRUE if @iter points to a valid value a `GtkBitsetIter` Moves @iter to the next value in the set. If it was already pointing to the last value in the set, %FALSE is returned and @iter is invalidated. %TRUE if a next value existed a pointer to a valid `GtkBitsetIter` Set to the next value Moves @iter to the previous value in the set. If it was already pointing to the first value in the set, %FALSE is returned and @iter is invalidated. %TRUE if a previous value existed a pointer to a valid `GtkBitsetIter` Set to the previous value Initializes @iter to point to @target. If @target is not found, finds the next value after it. If no value >= @target exists in @set, this function returns %FALSE. %TRUE if a value was found. a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` target value to start iterating at Set to the found value in @set Initializes an iterator for @set and points it to the first value in @set. If @set is empty, %FALSE is returned and @value is set to %G_MAXUINT. %TRUE if @set isn't empty. a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` Set to the first value in @set Initializes an iterator for @set and points it to the last value in @set. If @set is empty, %FALSE is returned. %TRUE if @set isn't empty. a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` Set to the last value in @set `GtkBookmarkList` is a list model that wraps `GBookmarkFile`. It presents a `GListModel` and fills it asynchronously with the `GFileInfo`s returned from that function. The `GFileInfo`s in the list have some attributes in the recent namespace added: `recent::private` (boolean) and `recent:applications` (stringv). Creates a new `GtkBookmarkList` with the given @attributes. a new `GtkBookmarkList` The bookmark file to load The attributes to query Gets the attributes queried on the children. The queried attributes a `GtkBookmarkList` Returns the filename of the bookmark file that this list is loading. the filename of the .xbel file a `GtkBookmarkList` Gets the IO priority to use while loading file. The IO priority. a `GtkBookmarkList` Returns %TRUE if the files are currently being loaded. Files will be added to @self from time to time while loading is going on. The order in which are added is undefined and may change in between runs. %TRUE if @self is loading a `GtkBookmarkList` Sets the @attributes to be enumerated and starts the enumeration. If @attributes is %NULL, no attributes will be queried, but a list of `GFileInfo`s will still be created. a `GtkBookmarkList` the attributes to enumerate Sets the IO priority to use while loading files. The default IO priority is %G_PRIORITY_DEFAULT. a `GtkBookmarkList` IO priority to use The attributes to query. The bookmark file to load. Priority used when loading. The type of items. See [method@Gio.ListModel.get_item_type]. %TRUE if files are being loaded. The number of items. See [method@Gio.ListModel.get_n_items]. `GtkBoolFilter` evaluates a boolean `GtkExpression` to determine whether to include items. Creates a new bool filter. a new `GtkBoolFilter` The expression to evaluate Gets the expression that the filter uses to evaluate if an item should be filtered. a `GtkExpression` a `GtkBoolFilter` Returns whether the filter inverts the expression. %TRUE if the filter inverts a `GtkBoolFilter` Sets the expression that the filter uses to check if items should be filtered. The expression must have a value type of %G_TYPE_BOOLEAN. a `GtkBoolFilter` a `GtkExpression` Sets whether the filter should invert the expression. a `GtkBoolFilter` %TRUE to invert The boolean expression to evaluate on item. If the expression result should be inverted. A struct that specifies a border around a rectangular area. Each side can have different width. The width of the left border The width of the right border The width of the top border The width of the bottom border Allocates a new `GtkBorder` struct and initializes its elements to zero. a newly allocated `GtkBorder` struct. Free with [method@Gtk.Border.free] Copies a `GtkBorder`. a copy of @border_. a `GtkBorder` struct Frees a `GtkBorder`. a `GtkBorder` struct Describes how the border of a UI element should be rendered. No visible border Same as %GTK_BORDER_STYLE_NONE 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 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 `GtkBox` widget arranges child widgets into a single row or column.  Whether it is a row or column depends on the value of its [property@Gtk.Orientable:orientation] property. Within the other dimension, all children are allocated the same size. Of course, the [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties can be used on the children to influence their allocation. Use repeated calls to [method@Gtk.Box.append] to pack widgets into a `GtkBox` from start to end. Use [method@Gtk.Box.remove] to remove widgets from the `GtkBox`. [method@Gtk.Box.insert_child_after] can be used to add a child at a particular position. Use [method@Gtk.Box.set_homogeneous] to specify whether or not all children of the `GtkBox` are forced to get the same amount of space. Use [method@Gtk.Box.set_spacing] to determine how much space will be minimally placed between all children in the `GtkBox`. Note that spacing is added *between* the children. Use [method@Gtk.Box.reorder_child_after] to move a child to a different place in the box. # CSS nodes `GtkBox` uses a single CSS node with name box. # Accessibility Until GTK 4.10, `GtkBox` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. Starting from GTK 4.12, `GtkBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. Creates a new `GtkBox`. a new `GtkBox`. the box’s orientation the number of pixels to place by default between children Adds @child as the last child to @box. a `GtkBox` the `GtkWidget` to append Gets the value set by gtk_box_set_baseline_child(). the baseline child a `GtkBox` Gets the value set by gtk_box_set_baseline_position(). the baseline position a `GtkBox` Returns whether the box is homogeneous (all children are the same size). %TRUE if the box is homogeneous. a `GtkBox` Gets the value set by gtk_box_set_spacing(). spacing between children a `GtkBox` Inserts @child in the position after @sibling in the list of @box children. If @sibling is %NULL, insert @child at the first position. a `GtkBox` the `GtkWidget` to insert the sibling after which to insert @child Adds @child as the first child to @box. a `GtkBox` the `GtkWidget` to prepend Removes a child widget from @box. The child must have been added before with [method@Gtk.Box.append], [method@Gtk.Box.prepend], or [method@Gtk.Box.insert_child_after]. a `GtkBox` the child to remove Moves @child to the position after @sibling in the list of @box children. If @sibling is %NULL, move @child to the first position. a `GtkBox` the `GtkWidget` to move, must be a child of @box the sibling to move @child after Sets the baseline child of a box. This affects only vertical boxes. a `GtkBox` a child, or -1 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 with respect to the extra space available. a `GtkBox` a `GtkBaselinePosition` Sets whether or not all children of @box are given equal space in the box. a `GtkBox` a boolean value, %TRUE to create equal allotments, %FALSE for variable allotments Sets the number of pixels to place between children of @box. a `GtkBox` the number of pixels to put between children The child that determines the baseline, in vertical orientation. The position of the baseline aligned widgets if extra space is available. Whether the children should all be the same size. The amount of space between children. The parent class. `GtkBoxLayout` is a layout manager that arranges children in a single row or column. Whether it is a row or column depends on the value of its [property@Gtk.Orientable:orientation] property. Within the other dimension all children all allocated the same size. The `GtkBoxLayout` will respect the [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties of each child widget. If you want all children to be assigned the same size, you can use the [property@Gtk.BoxLayout:homogeneous] property. If you want to specify the amount of space placed between each child, you can use the [property@Gtk.BoxLayout:spacing] property. Creates a new `GtkBoxLayout`. a new box layout the orientation for the new layout Gets the value set by gtk_box_layout_set_baseline_child(). the index of the child that determines the baseline in vertical layout, or -1 a `GtkBoxLayout` Gets the value set by gtk_box_layout_set_baseline_position(). the baseline position a `GtkBoxLayout` Returns whether the layout is set to be homogeneous. %TRUE if the layout is homogeneous a `GtkBoxLayout` Returns the space that @box_layout puts between children. the spacing of the layout a `GtkBoxLayout` Sets the index of the child that determines the baseline in vertical layout. a `GtkBoxLayout` the child position, or -1 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. a `GtkBoxLayout` a `GtkBaselinePosition` Sets whether the box layout will allocate the same size to all children. a `GtkBoxLayout` %TRUE to set the box layout as homogeneous Sets how much spacing to put between children. a `GtkBoxLayout` the spacing to apply between children The child that determines the baseline of the box in vertical layout. If the child does baseline positioning, then its baseline is lined up with the baseline of the box. If it doesn't, then the bottom edge of the child is used. The position of the allocated baseline within the extra space allocated to each child. 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 equally among the children. The space to put between the children. `GtkBuildable` allows objects to extend and customize their deserialization from ui files. The interface includes methods for setting names and properties of objects, parsing custom tags and constructing child objects. The `GtkBuildable` interface is implemented by all widgets and many of the non-widget objects that are provided by GTK. The main user of this interface is [class@Gtk.Builder]. There should be very little need for applications to call any of these functions directly. An object only needs to implement this interface if it needs to extend the `GtkBuilder` XML format or run any extra routines at deserialization time. Adds a child to @buildable. @type is an optional string describing how the child should be added. a `GtkBuildable` a `GtkBuilder` child to add kind of child or %NULL Constructs a child of a buildable that has been specified as “constructor” in the UI definition. This can be used to reference a widget created in a `<ui>` tag which is outside of the normal GtkBuilder UI definition hierarchy. A reference to the constructed object is returned and becomes owned by the caller. Similar to gtk_buildable_parser_finished() but is called once for each custom tag handled by the @buildable. a `GtkBuildable` a `GtkBuilder` child object or %NULL for non-child tags the name of the tag user data created in custom_tag_start Called at the end of each custom element handled by the buildable. A `GtkBuildable` `GtkBuilder` used to construct this object child object or %NULL for non-child tags name of tag user data that will be passed in to parser functions Called for each unknown element under `<child>`. %TRUE if an object has a custom implementation, %FALSE if it doesn't. a `GtkBuildable` a `GtkBuilder` used to construct this object child object or %NULL for non-child tags name of tag a `GtkBuildableParser` to fill in return location for user data that will be passed in to parser functions The getter corresponding to @set_id. Implement this if you implement @set_id. Retrieves the internal child called @childname of the @buildable object. the internal child of the buildable object a `GtkBuildable` a `GtkBuilder` name of child Called when a builder finishes the parsing of a UI definition. It is normally not necessary to implement this, unless you need to perform special cleanup actions. `GtkWindow` sets the `GtkWidget:visible` property here. Sets a property of a buildable object. It is normally not necessary to implement this, g_object_set_property() is used by default. `GtkWindow` implements this to delay showing itself (i.e. setting the [property@Gtk.Widget:visible] property) until the whole interface is created. Stores the id attribute given in the `GtkBuilder` UI definition. `GtkWidget` stores the name as object data. Implement this method if your object has some notion of “ID” and it makes sense to map the XML id attribute to it. Gets the ID of the @buildable object. `GtkBuilder` sets the name based on the ID attribute of the `<object>` tag used to construct the @buildable. the ID of the buildable object a `GtkBuildable` The `GtkBuildableIface` interface contains methods that are necessary to allow `GtkBuilder` to construct an object from a `GtkBuilder` UI definition. the parent class Stores the id attribute given in the `GtkBuilder` UI definition. `GtkWidget` stores the name as object data. Implement this method if your object has some notion of “ID” and it makes sense to map the XML id attribute to it. The getter corresponding to @set_id. Implement this if you implement @set_id. Adds a child. The @type parameter can be used to differentiate the kind of child. `GtkWidget` implements this to add event controllers to the widget, `GtkNotebook` uses the @type to distinguish between page labels (of type "page-label") and normal children. a `GtkBuildable` a `GtkBuilder` child to add kind of child or %NULL Sets a property of a buildable object. It is normally not necessary to implement this, g_object_set_property() is used by default. `GtkWindow` implements this to delay showing itself (i.e. setting the [property@Gtk.Widget:visible] property) until the whole interface is created. Constructs a child of a buildable that has been specified as “constructor” in the UI definition. This can be used to reference a widget created in a `<ui>` tag which is outside of the normal GtkBuilder UI definition hierarchy. A reference to the constructed object is returned and becomes owned by the caller. Implement this if the buildable needs to parse content below `<child>`. To handle an element, the implementation must fill in the @parser and @user_data and return %TRUE. `GtkWidget` implements this to parse accessible attributes specified in `<accessibility>` elements. Note that @user_data must be freed in @custom_tag_end or @custom_finished. %TRUE if an object has a custom implementation, %FALSE if it doesn't. a `GtkBuildable` a `GtkBuilder` used to construct this object child object or %NULL for non-child tags name of tag a `GtkBuildableParser` to fill in return location for user data that will be passed in to parser functions Called for the end tag of each custom element that is handled by the buildable (see @custom_tag_start). A `GtkBuildable` `GtkBuilder` used to construct this object child object or %NULL for non-child tags name of tag user data that will be passed in to parser functions Called for each custom tag handled by the buildable when the builder finishes parsing (see @custom_tag_start) a `GtkBuildable` a `GtkBuilder` child object or %NULL for non-child tags the name of the tag user data created in custom_tag_start Called when a builder finishes the parsing of a UI definition. It is normally not necessary to implement this, unless you need to perform special cleanup actions. `GtkWindow` sets the `GtkWidget:visible` property here. Returns an internal child of a buildable. `GtkDialog` implements this to give access to its @vbox, making it possible to add children to the vbox in a UI definition. Implement this if the buildable has internal children that may need to be accessed from a UI definition. the internal child of the buildable object a `GtkBuildable` a `GtkBuilder` name of child An opaque context struct for `GtkBuildableParser`. Retrieves the name of the currently open element. If called from the start_element or end_element handlers this will give the element_name as passed to those functions. For the parent elements, see gtk_buildable_parse_context_get_element_stack(). the name of the currently open element a `GtkBuildablParseContext` Retrieves the element stack from the internal state of the parser. The returned `GPtrArray` is an array of strings where the last item is the currently open tag (as would be returned by gtk_buildable_parse_context_get_element()) and the previous item is its immediate parent. This function is intended to be used in the start_element and end_element handlers where gtk_buildable_parse_context_get_element() would merely return the name of the element that is being processed. the element stack, which must not be modified a `GtkBuildableParseContext` Retrieves the current line number and the number of the character on that line. Intended for use in error messages; there are no strict semantics for what constitutes the "current" line number other than "the best number we could come up with for error messages." a `GtkBuildableParseContext` return location for a line number return location for a char-on-line number Completes the process of a temporary sub-parser redirection. This function exists to collect the user_data allocated by a matching call to gtk_buildable_parse_context_push(). It must be called in the end_element handler corresponding to the start_element handler during which gtk_buildable_parse_context_push() was called. You must not call this function from the error callback -- the @user_data is provided directly to the callback in that case. This function is not intended to be directly called by users interested in invoking subparsers. Instead, it is intended to be used by the subparsers themselves to implement a higher-level interface. the user data passed to gtk_buildable_parse_context_push() a `GtkBuildableParseContext` Temporarily redirects markup data to a sub-parser. This function may only be called from the start_element handler of a `GtkBuildableParser`. It must be matched with a corresponding call to gtk_buildable_parse_context_pop() in the matching end_element handler (except in the case that the parser aborts due to an error). All tags, text and other data between the matching tags is redirected to the subparser given by @parser. @user_data is used as the user_data for that parser. @user_data is also passed to the error callback in the event that an error occurs. This includes errors that occur in subparsers of the subparser. The end tag matching the start tag for which this call was made is handled by the previous parser (which is given its own user_data) which is why gtk_buildable_parse_context_pop() is provided to allow "one last access" to the @user_data provided to this function. In the case of error, the @user_data provided here is passed directly to the error callback of the subparser and gtk_buildable_parse_context_pop() should not be called. In either case, if @user_data was allocated then it ought to be freed from both of these locations. This function is not intended to be directly called by users interested in invoking subparsers. Instead, it is intended to be used by the subparsers themselves to implement a higher-level interface. For an example of how to use this, see g_markup_parse_context_push() which has the same kind of API. a `GtkBuildableParseContext` a `GtkBuildableParser` user data to pass to `GtkBuildableParser` functions A sub-parser for `GtkBuildable` implementations. function called for open elements function called for close elements function called for character data function called on error A `GtkBuilder` reads XML descriptions of a user interface and instantiates the described objects. To create a `GtkBuilder` from a user interface description, call [ctor@Gtk.Builder.new_from_file], [ctor@Gtk.Builder.new_from_resource] or [ctor@Gtk.Builder.new_from_string]. In the (unusual) case that you want to add user interface descriptions from multiple sources to the same `GtkBuilder` you can call [ctor@Gtk.Builder.new] to get an empty builder and populate it by (multiple) calls to [method@Gtk.Builder.add_from_file], [method@Gtk.Builder.add_from_resource] or [method@Gtk.Builder.add_from_string]. A `GtkBuilder` holds a reference to all objects that it has constructed and drops these references when it is finalized. This finalization can cause the destruction of non-widget objects or widgets which are not contained in a toplevel window. For toplevel windows constructed by a builder, it is the responsibility of the user to call [method@Gtk.Window.destroy] to get rid of them and all the widgets they contain. The functions [method@Gtk.Builder.get_object] and [method@Gtk.Builder.get_objects] can be used to access the widgets in the interface by the names assigned to them inside the UI description. Toplevel windows returned by these functions will stay around until the user explicitly destroys them with [method@Gtk.Window.destroy]. Other widgets will either be part of a larger hierarchy constructed by the builder (in which case you should not have to worry about their lifecycle), or without a parent, in which case they have to be added to some container to make use of them. Non-widget objects need to be reffed with g_object_ref() to keep them beyond the lifespan of the builder. ## GtkBuilder UI Definitions `GtkBuilder` parses textual descriptions of user interfaces which are specified in XML format. We refer to these descriptions as “GtkBuilder UI definitions” or just “UI definitions” if the context is clear. ### Structure of UI definitions UI definition files are always encoded in UTF-8. The toplevel element is `<interface>`. It optionally takes a “domain” attribute, which will make the builder look for translated strings using `dgettext()` in the domain specified. This can also be done by calling [method@Gtk.Builder.set_translation_domain] on the builder. For example: ```xml <?xml version="1.0" encoding="UTF-8"> <interface domain="your-app"> ... </interface> ``` ### Requirements The target toolkit version(s) are described by `<requires>` elements, the “lib” attribute specifies the widget library in question (currently the only supported value is “gtk”) and the “version” attribute specifies the target version in the form “`<major>`.`<minor>`”. `GtkBuilder` will error out if the version requirements are not met. For example: ```xml <?xml version="1.0" encoding="UTF-8"> <interface domain="your-app"> <requires lib="gtk" version="4.0" /> </interface> ``` ### Objects Objects are defined as children of the `<interface>` element. Objects are described by `<object>` elements, which can contain `<property>` elements to set properties, `<signal>` elements which connect signals to handlers, and `<child>` elements, which describe child objects. Typically, the specific kind of object represented by an `<object>` element is specified by the “class” attribute. If the type has not been loaded yet, GTK tries to find the `get_type()` function from the class name by applying heuristics. This works in most cases, but if necessary, it is possible to specify the name of the `get_type()` function explicitly with the "type-func" attribute. If your UI definition is referencing internal types, you should make sure to call `g_type_ensure()` for each object type before parsing the UI definition. Objects may be given a name with the “id” attribute, which allows the application to retrieve them from the builder with [method@Gtk.Builder.get_object]. An id is also necessary to use the object as property value in other parts of the UI definition. GTK reserves ids starting and ending with `___` (three consecutive underscores) for its own purposes. ### Properties Setting properties of objects is pretty straightforward with the `<property>` element: the “name” attribute specifies the name of the property, and the content of the element specifies the value: ```xml <object class="GtkButton"> <property name="label">Hello, world</property> </object> ``` If the “translatable” attribute is set to a true value, GTK uses `gettext()` (or `dgettext()` if the builder has a translation domain set) to find a translation for the value. This happens before the value is parsed, so it can be used for properties of any type, but it is probably most useful for string properties. It is also possible to specify a context to disambiguate short strings, and comments which may help the translators: ```xml <object class="GtkButton"> <property name="label" translatable="yes" context="button">Hello, world</property> </object> ``` `GtkBuilder` can parse textual representations for the most common property types: - characters - strings - integers - floating-point numbers - booleans (strings like “TRUE”, “t”, “yes”, “y”, “1” are interpreted as true values, strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted as false values) - enumeration types (can be specified by their full C identifier their short name used when registering the enumeration type, or their integer value) - flag types (can be specified by their C identifier, short name, integer value, and optionally combined with “|” for bitwise OR, e.g. “GTK_INPUT_HINT_EMOJI|GTK_INPUT_HINT_LOWERCASE”, or “emoji|lowercase”) - colors (in a format understood by [method@Gdk.RGBA.parse]) - `GVariant` (can be specified in the format understood by [func@GLib.Variant.parse]) - pixbufs (can be specified as a filename of an image file to load) Objects can be referred to by their name and by default refer to objects declared in the local XML fragment and objects exposed via [method@Gtk.Builder.expose_object]. In general, `GtkBuilder` allows forward references to objects declared in the local XML; an object doesn’t have to be constructed before it can be referred to. The exception to this rule is that an object has to be constructed before it can be used as the value of a construct-only property. ### Child objects Many widgets have properties for child widgets, such as [property@Gtk.Expander:child]. In this case, the preferred way to specify the child widget in a ui file is to simply set the property: ```xml <object class="GtkExpander"> <property name="child"> <object class="GtkLabel"> ... </object> </property> </object> ``` Generic containers that can contain an arbitrary number of children, such as [class@Gtk.Box] instead use the `<child>` element. A `<child>` element contains an `<object>` element which describes the child object. Most often, child objects are widgets inside a container, but they can also be, e.g., actions in an action group, or columns in a tree model. Any object type that implements the [iface@Gtk.Buildable] interface can specify how children may be added to it. Since many objects and widgets that are included with GTK already implement the `GtkBuildable` interface, typically child objects can be added using the `<child>` element without having to be concerned about the underlying implementation. See the [`GtkWidget` documentation](class.Widget.html#gtkwidget-as-gtkbuildable) for many examples of using `GtkBuilder` with widgets, including setting child objects using the `<child>` element. A noteworthy special case to the general rule that only objects implementing `GtkBuildable` may specify how to handle the `<child>` element is that `GtkBuilder` provides special support for adding objects to a [class@Gio.ListStore] by using the `<child>` element. For instance: ```xml <object class="GListStore"> <property name="item-type">MyObject</property> <child> <object class="MyObject" /> </child> ... </object> ``` ### Property bindings It is also possible to bind a property value to another object's property value using the attributes "bind-source" to specify the source object of the binding, and optionally, "bind-property" and "bind-flags" to specify the source property and source binding flags respectively. Internally, `GtkBuilder` implements this using [class@GObject.Binding] objects. For instance, in the example below the “label” property of the `bottom_label` widget is bound to the “label” property of the `top_button` widget: ```xml <object class="GtkBox"> <property name="orientation">vertical</property> <child> <object class="GtkButton" id="top_button"> <property name="label">Hello, world</property> </object> </child> <child> <object class="GtkLabel" id="bottom_label"> <property name="label" bind-source="top_button" bind-property="label" bind-flags="sync-create" /> </object> </child> </object> ``` For more information, see the documentation of the [method@GObject.Object.bind_property] method. Please note that another way to set up bindings between objects in .ui files is to use the `GtkExpression` methodology. See the [`GtkExpression` documentation](class.Expression.html#gtkexpression-in-ui-files) for more information. ### Internal children Sometimes it is necessary to refer to widgets which have implicitly been constructed by GTK as part of a composite widget, to set properties on them or to add further children (e.g. the content area of a `GtkDialog`). This can be achieved by setting the “internal-child” property of the `<child>` element to a true value. Note that `GtkBuilder` still requires an `<object>` element for the internal child, even if it has already been constructed. ### Specialized children A number of widgets have different places where a child can be added (e.g. tabs vs. page content in notebooks). This can be reflected in a UI definition by specifying the “type” attribute on a `<child>` The possible values for the “type” attribute are described in the sections describing the widget-specific portions of UI definitions. ### Signal handlers and function pointers Signal handlers are set up with the `<signal>` element. The “name” attribute specifies the name of the signal, and the “handler” attribute specifies the function to connect to the signal. ```xml <object class="GtkButton" id="hello_button"> <signal name="clicked" handler="hello_button__clicked" /> </object> ``` The remaining attributes, “after”, “swapped” and “object”, have the same meaning as the corresponding parameters of the [func@GObject.signal_connect_object] or [func@GObject.signal_connect_data] functions: - “after” matches the `G_CONNECT_AFTER` flag, and will ensure that the handler is called after the default class closure for the signal - “swapped” matches the `G_CONNECT_SWAPPED` flag, and will swap the instance and closure arguments when invoking the signal handler - “object” will bind the signal handler to the lifetime of the object referenced by the attribute By default "swapped" will be set to "yes" if not specified otherwise, in the case where "object" is set, for convenience. A “last_modification_time” attribute is also allowed, but it does not have a meaning to the builder. When compiling applications for Windows, you must declare signal callbacks with the `G_MODULE_EXPORT` decorator, or they will not be put in the symbol table: ```c G_MODULE_EXPORT void hello_button__clicked (GtkButton *button, gpointer data) { // ... } ``` On Linux and Unix, this is not necessary; applications should instead be compiled with the `-Wl,--export-dynamic` argument inside their compiler flags, and linked against `gmodule-export-2.0`. ## Example UI Definition ```xml <interface> <object class="GtkDialog" id="dialog1"> <child internal-child="content_area"> <object class="GtkBox"> <child internal-child="action_area"> <object class="GtkBox"> <child> <object class="GtkButton" id="ok_button"> <property name="label" translatable="yes">_Ok</property> <property name="use-underline">True</property> <signal name="clicked" handler="ok_button_clicked"/> </object> </child> </object> </child> </object> </child> </object> </interface> ``` ## Using GtkBuildable for extending UI definitions Objects can implement the [iface@Gtk.Buildable] interface to add custom elements and attributes to the XML. Typically, any extension will be documented in each type that implements the interface. ## Templates When describing a [class@Gtk.Widget], you can use the `<template>` tag to describe a UI bound to a specific widget type. GTK will automatically load the UI definition when instantiating the type, and bind children and signal handlers to instance fields and function symbols. For more information, see the [`GtkWidget` documentation](class.Widget.html#building-composite-widgets-from-template-xml) for details. Creates a new empty builder object. This function is only useful if you intend to make multiple calls to [method@Gtk.Builder.add_from_file], [method@Gtk.Builder.add_from_resource] or [method@Gtk.Builder.add_from_string] in order to merge multiple UI descriptions into a single builder. a new (empty) `GtkBuilder` object Parses the UI definition in the file @filename. If there is an error opening the file or parsing the description then the program will be aborted. You should only ever attempt to parse user interface descriptions that are shipped as part of your program. a `GtkBuilder` containing the described interface filename of user interface description file Parses the UI definition at @resource_path. If there is an error locating the resource or parsing the description, then the program will be aborted. a `GtkBuilder` containing the described interface a `GResource` resource path Parses the UI definition in @string. If @string is %NULL-terminated, then @length should be -1. If @length is not -1, then it is the length of @string. If there is an error parsing @string then the program will be aborted. You should not attempt to parse user interface description from untrusted sources. a `GtkBuilder` containing the interface described by @string a user interface (XML) description the length of @string, or -1 Parses a file containing a UI definition and merges it with the current contents of @builder. This function is useful if you need to call [method@Gtk.Builder.set_current_object]) to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want [ctor@Gtk.Builder.new_from_file] instead. If an error occurs, 0 will be returned and @error will be assigned a `GError` from the `GTK_BUILDER_ERROR`, `G_MARKUP_ERROR` or `G_FILE_ERROR` domains. It’s not really reasonable to attempt to handle failures of this call. You should not use this function with untrusted files (ie: files that are not part of your application). Broken `GtkBuilder` files can easily crash your program, and it’s possible that memory was leaked leading up to the reported failure. The only reasonable thing to do when an error is detected is to call `g_error()`. %TRUE on success, %FALSE if an error occurred a `GtkBuilder` the name of the file to parse Parses a resource file containing a UI definition and merges it with the current contents of @builder. This function is useful if you need to call [method@Gtk.Builder.set_current_object] to add user data to callbacks before loading GtkBuilder UI. Otherwise, you probably want [ctor@Gtk.Builder.new_from_resource] instead. If an error occurs, 0 will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_RESOURCE_ERROR domain. It’s not really reasonable to attempt to handle failures of this call. The only reasonable thing to do when an error is detected is to call g_error(). %TRUE on success, %FALSE if an error occurred a `GtkBuilder` the path of the resource file to parse Parses a string containing a UI definition and merges it with the current contents of @builder. This function is useful if you need to call [method@Gtk.Builder.set_current_object] to add user data to callbacks before loading `GtkBuilder` UI. Otherwise, you probably want [ctor@Gtk.Builder.new_from_string] instead. Upon errors %FALSE will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_VARIANT_PARSE_ERROR domain. It’s not really reasonable to attempt to handle failures of this call. The only reasonable thing to do when an error is detected is to call g_error(). %TRUE on success, %FALSE if an error occurred a `GtkBuilder` the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) Parses a file containing a UI definition building only the requested objects and merges them with the current contents of @builder. Upon errors, 0 will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_FILE_ERROR domain. If you are adding an object that depends on an object that is not its child (for instance a `GtkTreeView` that depends on its `GtkTreeModel`), you have to explicitly list all of them in @object_ids. %TRUE on success, %FALSE if an error occurred a `GtkBuilder` the name of the file to parse nul-terminated array of objects to build Parses a resource file containing a UI definition, building only the requested objects and merges them with the current contents of @builder. Upon errors, 0 will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR, %G_MARKUP_ERROR or %G_RESOURCE_ERROR domain. If you are adding an object that depends on an object that is not its child (for instance a `GtkTreeView` that depends on its `GtkTreeModel`), you have to explicitly list all of them in @object_ids. %TRUE on success, %FALSE if an error occurred a `GtkBuilder` the path of the resource file to parse nul-terminated array of objects to build Parses a string containing a UI definition, building only the requested objects and merges them with the current contents of @builder. Upon errors %FALSE will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR or %G_MARKUP_ERROR domain. If you are adding an object that depends on an object that is not its child (for instance a `GtkTreeView` that depends on its `GtkTreeModel`), you have to explicitly list all of them in @object_ids. %TRUE on success, %FALSE if an error occurred a `GtkBuilder` the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) nul-terminated array of objects to build Creates a closure to invoke the function called @function_name. This is using the create_closure() implementation of @builder's [iface@Gtk.BuilderScope]. If no closure could be created, %NULL will be returned and @error will be set. A new closure for invoking @function_name a `GtkBuilder` name of the function to look up closure creation flags Object to create the closure with Add @object to the @builder object pool so it can be referenced just like any other object built by builder. Only a single object may be added using @name. However, it is not an error to expose the same object under multiple names. `gtk_builder_get_object()` may be used to determine if an object has already been added with @name. a `GtkBuilder` the name of the object exposed to the builder the object to expose Main private entry point for building composite components from template XML. Most likely you do not need to call this function in applications as templates are handled by `GtkWidget`. A positive value on success, 0 if an error occurred a `GtkBuilder` the object that is being extended the type that the template is for the string to parse the length of @buffer (may be -1 if @buffer is nul-terminated) Gets the current object set via gtk_builder_set_current_object(). the current object a `GtkBuilder` Gets the object named @name. Note that this function does not increment the reference count of the returned object. the object named @name a `GtkBuilder` name of object to get Gets all objects that have been constructed by @builder. Note that this function does not increment the reference counts of the returned objects. a newly-allocated `GSList` containing all the objects constructed by the `GtkBuilder instance`. It should be freed by g_slist_free() a `GtkBuilder` Gets the scope in use that was set via gtk_builder_set_scope(). the current scope a `GtkBuilder` Gets the translation domain of @builder. the translation domain a `GtkBuilder` Looks up a type by name. This is using the virtual function that `GtkBuilder` has for that purpose. This is mainly used when implementing the `GtkBuildable` interface on a type. the `GType` found for @type_name or %G_TYPE_INVALID if no type was found a `GtkBuilder` type name to lookup Sets the current object for the @builder. The current object can be thought of as the `this` object that the builder is working for and will often be used as the default object when an object is optional. [method@Gtk.Widget.init_template] for example will set the current object to the widget the template is inited for. For functions like [ctor@Gtk.Builder.new_from_resource], the current object will be %NULL. a `GtkBuilder` the new current object Sets the scope the builder should operate in. If @scope is %NULL, a new [class@Gtk.BuilderCScope] will be created. a `GtkBuilder` the scope to use Sets the translation domain of @builder. a `GtkBuilder` the translation domain Demarshals a value from a string. This function calls g_value_init() on the @value argument, so it need not be initialised beforehand. Can handle char, uchar, boolean, int, uint, long, ulong, enum, flags, float, double, string, `GdkRGBA` and `GtkAdjustment` type values. Upon errors %FALSE will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR domain. %TRUE on success a `GtkBuilder` the `GParamSpec` for the property the string representation of the value the `GValue` to store the result in Demarshals a value from a string. Unlike [method@Gtk.Builder.value_from_string], this function takes a `GType` instead of `GParamSpec`. Calls g_value_init() on the @value argument, so it need not be initialised beforehand. Upon errors %FALSE will be returned and @error will be assigned a `GError` from the %GTK_BUILDER_ERROR domain. %TRUE on success a `GtkBuilder` the `GType` of the value the string representation of the value the `GValue` to store the result in The object the builder is evaluating for. The scope the builder is operating in The translation domain used when translating property values that have been marked as translatable. If the translation domain is %NULL, `GtkBuilder` uses gettext(), otherwise g_dgettext(). A `GtkBuilderScope` implementation for the C language. `GtkBuilderCScope` instances use symbols explicitly added to @builder with prior calls to [method@Gtk.BuilderCScope.add_callback_symbol]. If developers want to do that, they are encouraged to create their own scopes for that purpose. In the case that symbols are not explicitly added; GTK will uses `GModule`’s introspective features (by opening the module %NULL) to look at the application’s symbol table. From here it tries to match the signal function names given in the interface description with symbols in the application. Note that unless [method@Gtk.BuilderCScope.add_callback_symbol] is called for all signal callbacks which are referenced by the loaded XML, this functionality will require that `GModule` be supported on the platform. Creates a new `GtkBuilderCScope` object to use with future `GtkBuilder` instances. Calling this function is only necessary if you want to add custom callbacks via [method@Gtk.BuilderCScope.add_callback_symbol]. a new `GtkBuilderCScope` Adds the @callback_symbol to the scope of @builder under the given @callback_name. Using this function overrides the behavior of [method@Gtk.Builder.create_closure] for any callback symbols that are added. Using this method allows for better encapsulation as it does not require that callback symbols be declared in the global namespace. a `GtkBuilderCScope` The name of the callback, as expected in the XML The callback pointer A convenience function to add many callbacks. This is equivalent to calling [method@Gtk.BuilderCScope.add_callback_symbol] for each symbol. a `GtkBuilderCScope` The name of the callback, as expected in the XML The callback pointer A list of callback name and callback symbol pairs terminated with %NULL Fetches a symbol previously added with gtk_builder_cscope_add_callback_symbol(). The callback symbol in @builder for @callback_name a `GtkBuilderCScope` The name of the callback The list of flags that can be passed to gtk_builder_create_closure(). New values may be added in the future for new features, so external implementations of [iface@Gtk.BuilderScope] should test the flags for unknown values and raise a %GTK_BUILDER_ERROR_INVALID_ATTRIBUTE error when they encounter one. The closure should be created swapped. See g_cclosure_new_swap() for details. Error codes that identify various errors that can occur while using `GtkBuilder`. A type-func attribute didn’t name a function that returns a `GType`. The input contained a tag that `GtkBuilder` can’t handle. An attribute that is required by `GtkBuilder` was missing. `GtkBuilder` found an attribute that it doesn’t understand. `GtkBuilder` found a tag that it doesn’t understand. A required property value was missing. `GtkBuilder` couldn’t parse some attribute value. The input file requires a newer version of GTK. An object id occurred twice. A specified object type is of the same type or derived from the type of the composite class being extended with builder XML. The wrong type was specified in a composite class’s template XML The specified property is unknown for the object class. The specified signal is unknown for the object class. An object id is unknown. A function could not be found. This often happens when symbols are set to be kept private. Compiling code with -rdynamic or using the `gmodule-export-2.0` pkgconfig module can fix this problem. Registers an error quark for [class@Gtk.Builder] errors. the error quark `GtkBuilderListItemFactory` is a `GtkListItemFactory` that creates widgets by instantiating `GtkBuilder` UI templates. The templates must extend the class that the parent widget expects. For example, a factory provided to [property@Gtk.ListView:factory] must have a template that extends [class@Gtk.ListItem]. Templates typically use `GtkExpression`s to obtain data from the items in the model. Example: ```xml <interface> <template class="GtkListItem"> <property name="child"> <object class="GtkLabel"> <property name="xalign">0</property> <binding name="label"> <lookup name="name" type="SettingsKey"> <lookup name="item">GtkListItem</lookup> </lookup> </binding> </object> </property> </template> </interface> ``` Creates a new `GtkBuilderListItemFactory` that instantiates widgets using @bytes as the data to pass to `GtkBuilder`. a new `GtkBuilderListItemFactory` A scope to use when instantiating the `GBytes` containing the ui file to instantiate Creates a new `GtkBuilderListItemFactory` that instantiates widgets using data read from the given @resource_path to pass to `GtkBuilder`. a new `GtkBuilderListItemFactory` A scope to use when instantiating valid path to a resource that contains the data Gets the data used as the `GtkBuilder` UI template for constructing listitems. The `GtkBuilder` data a `GtkBuilderListItemFactory` If the data references a resource, gets the path of that resource. The path to the resource a `GtkBuilderListItemFactory` Gets the scope used when constructing listitems. The scope used when constructing listitems a `GtkBuilderListItemFactory` `GBytes` containing the UI definition. Path of the resource containing the UI definition. `GtkBuilderScope` to use when instantiating listitems `GtkBuilderScope` is an interface to provide language binding support to `GtkBuilder`. The goal of `GtkBuilderScope` is to look up programming-language-specific values for strings that are given in a `GtkBuilder` UI file. The primary intended audience is bindings that want to provide deeper integration of `GtkBuilder` into the language. A `GtkBuilderScope` instance may be used with multiple `GtkBuilder` objects, even at once. By default, GTK will use its own implementation of `GtkBuilderScope` for the C language which can be created via [ctor@Gtk.BuilderCScope.new]. If you implement `GtkBuilderScope` for a language binding, you may want to (partially) derive from or fall back to a [class@Gtk.BuilderCScope], as that class implements support for automatic lookups from C symbols. Create a closure with the given arguments. See gtk_builder_create_closure() for more details on those. The C implementation will try to use dlsym() to locate the function name and then g_cclosure_new() to create a closure for the symbol. The default implementation just fails and returns %NULL. Try to lookup a `GType` via the given function name, specified explicitly in a GtkBuilder file, like via the "type-func" attribute in the `<object>` tag. This function is very rarely used. The C implementation will use dlsym() and call the resulting function as a `GTypeFunc`. The default implementation will fail and just return %G_TYPE_INVALID. Try to lookup a `GType` via the its name. See gtk_builder_get_type_from_name() for more details. The C implementation will use g_type_from_name() and if that fails try to guess the correct function name for registering the type and then use dlsym() to load it. The default implementation just tries g_type_from_name() and otherwise fails. The virtual function table to implement for `GtkBuilderScope` implementations. Default implementations for each function do exist, but they usually just fail, so it is suggested that implementations implement all of them. Try to lookup a `GType` via the its name. See gtk_builder_get_type_from_name() for more details. The C implementation will use g_type_from_name() and if that fails try to guess the correct function name for registering the type and then use dlsym() to load it. The default implementation just tries g_type_from_name() and otherwise fails. Try to lookup a `GType` via the given function name, specified explicitly in a GtkBuilder file, like via the "type-func" attribute in the `<object>` tag. This function is very rarely used. The C implementation will use dlsym() and call the resulting function as a `GTypeFunc`. The default implementation will fail and just return %G_TYPE_INVALID. Create a closure with the given arguments. See gtk_builder_create_closure() for more details on those. The C implementation will try to use dlsym() to locate the function name and then g_cclosure_new() to create a closure for the symbol. The default implementation just fails and returns %NULL. The `GtkButton` widget is generally used to trigger a callback function that is called when the button is pressed.  The `GtkButton` widget can hold any valid child widget. That is, it can hold almost any other standard `GtkWidget`. The most commonly used child is the `GtkLabel`. # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.Button::activate] # CSS nodes `GtkButton` has a single CSS node with name button. The node will get the style classes .image-button or .text-button, if the content is just an image or label, respectively. It may also receive the .flat style class. When activating a button via the keyboard, the button will temporarily gain the .keyboard-activating style class. Other style classes that are commonly used with `GtkButton` include .suggested-action and .destructive-action. In special cases, buttons can be made round by adding the .circular style class. Button-like widgets like [class@Gtk.ToggleButton], [class@Gtk.MenuButton], [class@Gtk.VolumeButton], [class@Gtk.LockButton], [class@Gtk.ColorButton] or [class@Gtk.FontButton] use style classes such as .toggle, .popup, .scale, .lock, .color on the button node to differentiate themselves from a plain `GtkButton`. # Accessibility `GtkButton` uses the %GTK_ACCESSIBLE_ROLE_BUTTON role. Creates a new `GtkButton` widget. To add a child widget to the button, use [method@Gtk.Button.set_child]. The newly created `GtkButton` widget. Creates a new button containing an icon from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately. a new `GtkButton` displaying the themed icon an icon name Creates a `GtkButton` widget with a `GtkLabel` child. The newly created `GtkButton` widget The text you want the `GtkLabel` to hold Creates a new `GtkButton` containing a label. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing <kbd>Alt</kbd> and that key activates the button. a new `GtkButton` The text of the button, with an underscore in front of the mnemonic character Signal that causes the button to animate press then release. Applications should never connect to this signal, but use the @clicked signal. Signal emitted when the button has been activated (pressed and released). Retrieves whether the button can be smaller than the natural size of its contents. true if the button can shrink, and false otherwise a button Gets the child widget of @button. the child widget of @button a `GtkButton` Returns whether the button has a frame. %TRUE if the button has a frame a `GtkButton` Returns the icon name of the button. If the icon name has not been set with [method@Gtk.Button.set_icon_name] the return value will be %NULL. This will be the case if you create an empty button with [ctor@Gtk.Button.new] to use as a container. The icon name set via [method@Gtk.Button.set_icon_name] A `GtkButton` Fetches the text from the label of the button. If the label text has not been set with [method@Gtk.Button.set_label] the return value will be %NULL. This will be the case if you create an empty button with [ctor@Gtk.Button.new] to use as a container. The text of the label widget. This string is owned by the widget and must not be modified or freed. a `GtkButton` gets whether underlines are interpreted as mnemonics. See [method@Gtk.Button.set_use_underline]. %TRUE if an embedded underline in the button label indicates the mnemonic accelerator keys. a `GtkButton` Sets whether the button size can be smaller than the natural size of its contents. For text buttons, setting @can_shrink to true will ellipsize the label. For icons and custom children, this function has no effect. a button whether the button can shrink Sets the child widget of @button. Note that by using this API, you take full responsibility for setting up the proper accessibility label and description information for @button. Most likely, you'll either set the accessibility label or description for @button explicitly, or you'll set a labelled-by or described-by relations from @child to @button. a `GtkButton` the child widget Sets the style of the button. Buttons can have a flat appearance or have a frame drawn around them. a `GtkButton` whether the button should have a visible frame Adds a `GtkImage` with the given icon name as a child. If @button already contains a child widget, that child widget will be removed and replaced with the image. A `GtkButton` An icon name Sets the text of the label of the button to @label. This will also clear any previously set labels. a `GtkButton` a string Sets whether to use underlines as mnemonics. If true, an underline in the text of the button label indicates the next character should be used for the mnemonic accelerator key. a `GtkButton` %TRUE if underlines in the text indicate mnemonics Whether the size of the button can be made smaller than the natural size of its contents. For text buttons, setting this property will allow ellipsizing the label. If the contents of a button are an icon or a custom widget, setting this property has no effect. The child widget. Whether the button has a frame. The name of the icon used to automatically populate the button. Text of the label inside the button, if the button contains a label widget. If set, an underline in the text indicates that the following character is to be used as mnemonic. Emitted to animate press then release. This is an action signal. Applications should never connect to this signal, but use the [signal@Gtk.Button::clicked] signal. The default bindings for this signal are all forms of the <kbd>␣</kbd> and <kbd>Enter</kbd> keys. Emitted when the button has been activated (pressed and released). The parent class. Signal emitted when the button has been activated (pressed and released). Signal that causes the button to animate press then release. Applications should never connect to this signal, but use the @clicked signal. Prebuilt sets of buttons for `GtkDialog`. If none of these choices are appropriate, simply use %GTK_BUTTONS_NONE and call [method@Gtk.Dialog.add_buttons]. > Please note that %GTK_BUTTONS_OK, %GTK_BUTTONS_YES_NO > and %GTK_BUTTONS_OK_CANCEL are discouraged by the > [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/). no buttons at all an OK button a Close button a Cancel button Yes and No buttons OK and Cancel buttons A variant of `GtkClosureExpression` using a C closure. Creates a `GtkExpression` that calls `callback_func` when it is evaluated. This function is a variant of [ctor@Gtk.ClosureExpression.new] that creates a `GClosure` by calling g_cclosure_new() with the given `callback_func`, `user_data` and `user_destroy`. a new `GtkExpression` the type of the value that this expression evaluates to marshaller used for creating a closure the number of params needed for evaluating @closure expressions for each parameter callback used for creating a closure user data used for creating a closure destroy notify for @user_data This macro should be used to emit a standard warning about unexpected properties in set_cell_property() and get_cell_property() implementations. the `GObject` on which set_cell_property() or get_cell_property() was called the numeric id of the property the `GParamSpec` of the property Returns %TRUE if the version of the GTK header files is the same as or newer than the passed-in version. major version (e.g. 1 for version 1.2.5) minor version (e.g. 2 for version 1.2.5) micro version (e.g. 5 for version 1.2.5) `GtkCalendar` is a widget that displays a Gregorian calendar, one month at a time.  A `GtkCalendar` can be created with [ctor@Gtk.Calendar.new]. The date that is currently displayed can be altered with [method@Gtk.Calendar.select_day]. To place a visual marker on a particular day, use [method@Gtk.Calendar.mark_day] and to remove the marker, [method@Gtk.Calendar.unmark_day]. Alternative, all marks can be cleared with [method@Gtk.Calendar.clear_marks]. The selected date can be retrieved from a `GtkCalendar` using [method@Gtk.Calendar.get_date]. Users should be aware that, although the Gregorian calendar is the legal calendar in most countries, it was adopted progressively between 1582 and 1929. Display before these dates is likely to be historically incorrect. # Shortcuts and Gestures `GtkCalendar` supports the following gestures: - Scrolling up or down will switch to the previous or next month. - Date strings can be dropped for setting the current day. # CSS nodes ``` calendar.view ├── header │ ├── button │ ├── stack.month │ ├── button │ ├── button │ ├── label.year │ ╰── button ╰── grid ╰── label[.day-name][.week-number][.day-number][.other-month][.today] ``` `GtkCalendar` has a main node with name calendar. It contains a subnode called header containing the widgets for switching between years and months. The grid subnode contains all day labels, including week numbers on the left (marked with the .week-number css class) and day names on top (marked with the .day-name css class). Day labels that belong to the previous or next month get the .other-month style class. The label of the current day get the .today style class. Marked day labels get the :selected state assigned. Creates a new calendar, with the current date being selected. a newly `GtkCalendar` widget Remove all visual markers. a `GtkCalendar` Returns a `GDateTime` representing the shown year, month and the selected day. The returned date is in the local time zone. the `GDateTime` representing the shown date a `GtkCalendar` Gets the day of the selected date. the day of the selected date. a `GtkCalendar` Returns if the @day of the @calendar is already marked. whether the day is marked. a `GtkCalendar` the day number between 1 and 31. Gets the month of the selected date. The month of the selected date (as a number between 0 and 11). a `GtkCalendar` Returns whether @self is currently showing the names of the week days. This is the value of the [property@Gtk.Calendar:show-day-names] property. Whether the calendar shows day names. a `GtkCalendar` Returns whether @self is currently showing the heading. This is the value of the [property@Gtk.Calendar:show-heading] property. Whether the calendar is showing a heading. a `GtkCalendar` Returns whether @self is showing week numbers right now. This is the value of the [property@Gtk.Calendar:show-week-numbers] property. Whether the calendar is showing week numbers. a `GtkCalendar` Gets the year of the selected date. the year of the selected date. a `GtkCalendar` Places a visual marker on a particular day of the current month. a `GtkCalendar` the day number to mark between 1 and 31. Switches to @date's year and month and select its day. a `GtkCalendar`. a `GDateTime` representing the day to select Sets the day for the selected date. The new date must be valid. For example, setting 31 for the day when the month is February, fails. a `GtkCalendar` The desired day for the selected date (as a number between 1 and 31). Sets the month for the selected date. The new date must be valid. For example, setting 1 (February) for the month when the day is 31, fails. a `GtkCalendar` The desired month for the selected date (as a number between 0 and 11). Sets whether the calendar shows day names. a `GtkCalendar` Whether to show day names above the day numbers Sets whether the calendar should show a heading. The heading contains the current year and month as well as buttons for changing both. a `GtkCalendar` Whether to show the heading in the calendar Sets whether week numbers are shown in the calendar. a `GtkCalendar` whether to show week numbers on the left of the days Sets the year for the selected date. The new date must be valid. For example, setting 2023 for the year when then the date is 2024-02-29, fails. a `GtkCalendar` The desired year for the selected date (within [struct@GLib.DateTime] limits, i.e. from 0001 to 9999). Removes the visual marker from a particular day. a `GtkCalendar`. the day number to unmark between 1 and 31. The selected day (as a number between 1 and 31). The selected month (as a number between 0 and 11). This property gets initially set to the current month. Determines whether day names are displayed. Determines whether a heading is displayed. Determines whether week numbers are displayed. The selected year. This property gets initially set to the current year. Emitted when the user selects a day. Emitted when the user switched to the next month. Emitted when user switched to the next year. Emitted when the user switched to the previous month. Emitted when user switched to the previous year. A `GtkShortcutAction` that invokes a callback. Create a custom action that calls the given @callback when activated. A new shortcut action the callback to call when the action is activated the data to be passed to @callback the function to be called when the callback action is finalized The type of the callback functions used for iterating over the cell renderers and their allocated areas inside a `GtkCellArea`, see gtk_cell_area_foreach_alloc(). %TRUE to stop iterating over cells. the cell renderer to operate on the area allocated to @renderer inside the rectangle provided to gtk_cell_area_foreach_alloc(). the background area for @renderer inside the background area provided to gtk_cell_area_foreach_alloc(). user-supplied data An abstract class for laying out `GtkCellRenderer`s The `GtkCellArea` is an abstract class for [iface@Gtk.CellLayout] widgets (also referred to as "layouting widgets") to interface with an arbitrary number of [class@Gtk.CellRenderer]s and interact with the user for a given [iface@Gtk.TreeModel] row. The cell area handles events, focus navigation, drawing and size requests and allocations for a given row of data. Usually users dont have to interact with the `GtkCellArea` directly unless they are implementing a cell-layouting widget themselves. ## Requesting area sizes As outlined in [GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management), GTK uses a height-for-width geometry management system to compute the sizes of widgets and user interfaces. `GtkCellArea` uses the same semantics to calculate the size of an area for an arbitrary number of `GtkTreeModel` rows. When requesting the size of a cell area one needs to calculate the size for a handful of rows, and this will be done differently by different layouting widgets. For instance a [class@Gtk.TreeViewColumn] always lines up the areas from top to bottom while a [class@Gtk.IconView] on the other hand might enforce that all areas received the same width and wrap the areas around, requesting height for more cell areas when allocated less width. It’s also important for areas to maintain some cell alignments with areas rendered for adjacent rows (cells can appear “columnized” inside an area even when the size of cells are different in each row). For this reason the `GtkCellArea` uses a [class@Gtk.CellAreaContext] object to store the alignments and sizes along the way (as well as the overall largest minimum and natural size for all the rows which have been calculated with the said context). The [class@Gtk.CellAreaContext] is an opaque object specific to the `GtkCellArea` which created it (see [method@Gtk.CellArea.create_context]). The owning cell-layouting widget can create as many contexts as it wishes to calculate sizes of rows which should receive the same size in at least one orientation (horizontally or vertically), However, it’s important that the same [class@Gtk.CellAreaContext] which was used to request the sizes for a given `GtkTreeModel` row be used when rendering or processing events for that row. In order to request the width of all the rows at the root level of a `GtkTreeModel` one would do the following: ```c GtkTreeIter iter; int minimum_width; int natural_width; valid = gtk_tree_model_get_iter_first (model, &iter); while (valid) { gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE); gtk_cell_area_get_preferred_width (area, context, widget, NULL, NULL); valid = gtk_tree_model_iter_next (model, &iter); } gtk_cell_area_context_get_preferred_width (context, &minimum_width, &natural_width); ``` Note that in this example it’s not important to observe the returned minimum and natural width of the area for each row unless the cell-layouting object is actually interested in the widths of individual rows. The overall width is however stored in the accompanying `GtkCellAreaContext` object and can be consulted at any time. This can be useful since `GtkCellLayout` widgets usually have to support requesting and rendering rows in treemodels with an exceedingly large amount of rows. The `GtkCellLayout` widget in that case would calculate the required width of the rows in an idle or timeout source (see [func@GLib.timeout_add]) and when the widget is requested its actual width in [vfunc@Gtk.Widget.measure] it can simply consult the width accumulated so far in the `GtkCellAreaContext` object. A simple example where rows are rendered from top to bottom and take up the full width of the layouting widget would look like: ```c static void foo_get_preferred_width (GtkWidget *widget, int *minimum_size, int *natural_size) { Foo *self = FOO (widget); FooPrivate *priv = foo_get_instance_private (self); foo_ensure_at_least_one_handfull_of_rows_have_been_requested (self); gtk_cell_area_context_get_preferred_width (priv->context, minimum_size, natural_size); } ``` In the above example the `Foo` widget has to make sure that some row sizes have been calculated (the amount of rows that `Foo` judged was appropriate to request space for in a single timeout iteration) before simply returning the amount of space required by the area via the `GtkCellAreaContext`. Requesting the height for width (or width for height) of an area is a similar task except in this case the `GtkCellAreaContext` does not store the data (actually, it does not know how much space the layouting widget plans to allocate it for every row. It’s up to the layouting widget to render each row of data with the appropriate height and width which was requested by the `GtkCellArea`). In order to request the height for width of all the rows at the root level of a `GtkTreeModel` one would do the following: ```c GtkTreeIter iter; int minimum_height; int natural_height; int full_minimum_height = 0; int full_natural_height = 0; valid = gtk_tree_model_get_iter_first (model, &iter); while (valid) { gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE); gtk_cell_area_get_preferred_height_for_width (area, context, widget, width, &minimum_height, &natural_height); if (width_is_for_allocation) cache_row_height (&iter, minimum_height, natural_height); full_minimum_height += minimum_height; full_natural_height += natural_height; valid = gtk_tree_model_iter_next (model, &iter); } ``` Note that in the above example we would need to cache the heights returned for each row so that we would know what sizes to render the areas for each row. However we would only want to really cache the heights if the request is intended for the layouting widgets real allocation. In some cases the layouting widget is requested the height for an arbitrary for_width, this is a special case for layouting widgets who need to request size for tens of thousands of rows. For this case it’s only important that the layouting widget calculate one reasonably sized chunk of rows and return that height synchronously. The reasoning here is that any layouting widget is at least capable of synchronously calculating enough height to fill the screen height (or scrolled window height) in response to a single call to [vfunc@Gtk.Widget.measure]. Returning a perfect height for width that is larger than the screen area is inconsequential since after the layouting receives an allocation from a scrolled window it simply continues to drive the scrollbar values while more and more height is required for the row heights that are calculated in the background. ## Rendering Areas Once area sizes have been acquired at least for the rows in the visible area of the layouting widget they can be rendered at [vfunc@Gtk.Widget.snapshot] time. A crude example of how to render all the rows at the root level runs as follows: ```c GtkAllocation allocation; GdkRectangle cell_area = { 0, }; GtkTreeIter iter; int minimum_width; int natural_width; gtk_widget_get_allocation (widget, &allocation); cell_area.width = allocation.width; valid = gtk_tree_model_get_iter_first (model, &iter); while (valid) { cell_area.height = get_cached_height_for_row (&iter); gtk_cell_area_apply_attributes (area, model, &iter, FALSE, FALSE); gtk_cell_area_render (area, context, widget, cr, &cell_area, &cell_area, state_flags, FALSE); cell_area.y += cell_area.height; valid = gtk_tree_model_iter_next (model, &iter); } ``` Note that the cached height in this example really depends on how the layouting widget works. The layouting widget might decide to give every row its minimum or natural height or, if the model content is expected to fit inside the layouting widget without scrolling, it would make sense to calculate the allocation for each row at the time the widget is allocated using [func@Gtk.distribute_natural_allocation]. ## Handling Events and Driving Keyboard Focus Passing events to the area is as simple as handling events on any normal widget and then passing them to the [method@Gtk.CellArea.event] API as they come in. Usually `GtkCellArea` is only interested in button events, however some customized derived areas can be implemented who are interested in handling other events. Handling an event can trigger the [signal@Gtk.CellArea::focus-changed] signal to fire; as well as [signal@Gtk.CellArea::add-editable] in the case that an editable cell was clicked and needs to start editing. You can call [method@Gtk.CellArea.stop_editing] at any time to cancel any cell editing that is currently in progress. The `GtkCellArea` drives keyboard focus from cell to cell in a way similar to `GtkWidget`. For layouting widgets that support giving focus to cells it’s important to remember to pass `GTK_CELL_RENDERER_FOCUSED` to the area functions for the row that has focus and to tell the area to paint the focus at render time. Layouting widgets that accept focus on cells should implement the [vfunc@Gtk.Widget.focus] virtual method. The layouting widget is always responsible for knowing where `GtkTreeModel` rows are rendered inside the widget, so at [vfunc@Gtk.Widget.focus] time the layouting widget should use the `GtkCellArea` methods to navigate focus inside the area and then observe the [enum@Gtk.DirectionType] to pass the focus to adjacent rows and areas. A basic example of how the [vfunc@Gtk.Widget.focus] virtual method should be implemented: ``` static gboolean foo_focus (GtkWidget *widget, GtkDirectionType direction) { Foo *self = FOO (widget); FooPrivate *priv = foo_get_instance_private (self); int focus_row = priv->focus_row; gboolean have_focus = FALSE; if (!gtk_widget_has_focus (widget)) gtk_widget_grab_focus (widget); valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, priv->focus_row); while (valid) { gtk_cell_area_apply_attributes (priv->area, priv->model, &iter, FALSE, FALSE); if (gtk_cell_area_focus (priv->area, direction)) { priv->focus_row = focus_row; have_focus = TRUE; break; } else { if (direction == GTK_DIR_RIGHT || direction == GTK_DIR_LEFT) break; else if (direction == GTK_DIR_UP || direction == GTK_DIR_TAB_BACKWARD) { if (focus_row == 0) break; else { focus_row--; valid = gtk_tree_model_iter_nth_child (priv->model, &iter, NULL, focus_row); } } else { if (focus_row == last_row) break; else { focus_row++; valid = gtk_tree_model_iter_next (priv->model, &iter); } } } } return have_focus; } ``` Note that the layouting widget is responsible for matching the `GtkDirectionType` values to the way it lays out its cells. ## Cell Properties The `GtkCellArea` introduces cell properties for `GtkCellRenderer`s. This provides some general interfaces for defining the relationship cell areas have with their cells. For instance in a [class@Gtk.CellAreaBox] a cell might “expand” and receive extra space when the area is allocated more than its full natural request, or a cell might be configured to “align” with adjacent rows which were requested and rendered with the same `GtkCellAreaContext`. Use [method@Gtk.CellAreaClass.install_cell_property] to install cell properties for a cell area class and [method@Gtk.CellAreaClass.find_cell_property] or [method@Gtk.CellAreaClass.list_cell_properties] to get information about existing cell properties. To set the value of a cell property, use [method@Gtk.CellArea.cell_set_property], [method@Gtk.CellArea.cell_set] or [method@Gtk.CellArea.cell_set_valist]. To obtain the value of a cell property, use [method@Gtk.CellArea.cell_get_property] [method@Gtk.CellArea.cell_get] or [method@Gtk.CellArea.cell_get_valist]. List views use widgets for displaying their contents Activates @area, usually by activating the currently focused cell, however some subclasses which embed widgets in the area can also activate a widget if it currently has the focus. Whether @area was successfully activated. a `GtkCellArea` the `GtkCellArea`Context in context with the current row data the `GtkWidget` that @area is rendering on the size and location of @area relative to @widget’s allocation the `GtkCellRenderer`State flags for @area for this row of data. if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated. Adds @renderer to @area with the default child cell properties. a `GtkCellArea` the `GtkCellRenderer` to add to @area Applies any connected attributes to the renderers in @area by pulling the values from @tree_model. a `GtkCellArea` the `GtkTreeModel` to pull values from the `GtkTreeIter` in @tree_model to apply values for whether @iter has children whether @iter is expanded in the view and children are visible This is sometimes needed for cases where rows need to share alignments in one orientation but may be separately grouped in the opposing orientation. For instance, `GtkIconView` creates all icons (rows) to have the same width and the cells theirin to have the same horizontal alignments. However each row of icons may have a separate collective height. `GtkIconView` uses this to request the heights of each row based on a context which was already used to request all the row widths that are to be displayed. a newly created `GtkCellArea`Context copy of @context. a `GtkCellArea` the `GtkCellArea`Context to copy Creates a `GtkCellArea`Context to be used with @area for all purposes. `GtkCellArea`Context stores geometry information for rows for which it was operated on, it is important to use the same context for the same row of data at all times (i.e. one should render and handle events with the same `GtkCellArea`Context which was used to request the size of those rows of data). a newly created `GtkCellArea`Context which can be used with @area. a `GtkCellArea` Delegates event handling to a `GtkCellArea`. %TRUE if the event was handled by @area. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the `GdkEvent` to handle the @widget relative coordinates for @area the `GtkCellRenderer`State for @area in this row. This should be called by the @area’s owning layout widget when focus is to be passed to @area, or moved within @area for a given @direction and row data. Implementing `GtkCellArea` classes should implement this method to receive and navigate focus in its own way particular to how it lays out cells. %TRUE if focus remains inside @area as a result of this call. a `GtkCellArea` the `GtkDirectionType` Calls @callback for every `GtkCellRenderer` in @area. a `GtkCellArea` the `GtkCellCallback` to call user provided data pointer Calls @callback for every `GtkCellRenderer` in @area with the allocated rectangle inside @cell_area. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the @widget relative coordinates and size for @area the @widget relative coordinates of the background area the `GtkCellAllocCallback` to call user provided data pointer This should be implemented to report the values of child cell properties for a given child `GtkCellRenderer`. Retrieves a cell area’s initial minimum and natural height. @area will store some geometrical information in @context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the @minimum_height and @natural_height of this call but rather to consult gtk_cell_area_context_get_preferred_height() after a series of requests. a `GtkCellArea` the `GtkCellArea`Context to perform this request with the `GtkWidget` where @area will be rendering location to store the minimum height location to store the natural height Retrieves a cell area’s minimum and natural height if it would be given the specified @width. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_width(). It’s important to perform a series of gtk_cell_area_get_preferred_width() requests with @context first and then call gtk_cell_area_get_preferred_height_for_width() on each cell area individually to get the height for width of each fully requested row. If at some point, the width of a single row changes, it should be requested with gtk_cell_area_get_preferred_width() again and then the full width of the requested rows checked again with gtk_cell_area_context_get_preferred_width(). a `GtkCellArea` the `GtkCellArea`Context which has already been requested for widths. the `GtkWidget` where @area will be rendering the width for which to check the height of this area location to store the minimum height location to store the natural height Retrieves a cell area’s initial minimum and natural width. @area will store some geometrical information in @context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the @minimum_width and @natural_width of this call but rather to consult gtk_cell_area_context_get_preferred_width() after a series of requests. a `GtkCellArea` the `GtkCellArea`Context to perform this request with the `GtkWidget` where @area will be rendering location to store the minimum width location to store the natural width Retrieves a cell area’s minimum and natural width if it would be given the specified @height. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_height(). It’s important to perform a series of gtk_cell_area_get_preferred_height() requests with @context first and then call gtk_cell_area_get_preferred_width_for_height() on each cell area individually to get the height for width of each fully requested row. If at some point, the height of a single row changes, it should be requested with gtk_cell_area_get_preferred_height() again and then the full height of the requested rows checked again with gtk_cell_area_context_get_preferred_height(). a `GtkCellArea` the `GtkCellArea`Context which has already been requested for widths. the `GtkWidget` where @area will be rendering the height for which to check the width of this area location to store the minimum width location to store the natural width Gets whether the area prefers a height-for-width layout or a width-for-height layout. The `GtkSizeRequestMode` preferred by @area. a `GtkCellArea` Returns whether the area can do anything when activated, after applying new attributes to @area. whether @area can do anything when activated. a `GtkCellArea` Removes @renderer from @area. a `GtkCellArea` the `GtkCellRenderer` to remove from @area This should be implemented to handle changes in child cell properties for a given `GtkCellRenderer` that were previously installed on the `GtkCellAreaClass` with gtk_cell_area_class_install_cell_property(). Snapshots @area’s cells according to @area’s layout onto at the given coordinates. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the `GtkSnapshot` to draw to the @widget relative coordinates for @area’s background the @widget relative coordinates for @area the `GtkCellRenderer`State for @area in this row. whether @area should paint focus on focused cells for focused rows or not. Activates @area, usually by activating the currently focused cell, however some subclasses which embed widgets in the area can also activate a widget if it currently has the focus. Whether @area was successfully activated. a `GtkCellArea` the `GtkCellArea`Context in context with the current row data the `GtkWidget` that @area is rendering on the size and location of @area relative to @widget’s allocation the `GtkCellRenderer`State flags for @area for this row of data. if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated. This is used by `GtkCellArea` subclasses when handling events to activate cells, the base `GtkCellArea` class activates cells for keyboard events for free in its own GtkCellArea->activate() implementation. whether cell activation was successful a `GtkCellArea` the `GtkWidget` that @area is rendering onto the `GtkCellRenderer` in @area to activate the `GdkEvent` for which cell activation should occur the `GdkRectangle` in @widget relative coordinates of @renderer for the current row. the `GtkCellRenderer`State for @renderer Adds @renderer to @area with the default child cell properties. a `GtkCellArea` the `GtkCellRenderer` to add to @area Adds @sibling to @renderer’s focusable area, focus will be drawn around @renderer and all of its siblings if @renderer can focus for a given row. Events handled by focus siblings can also activate the given focusable @renderer. a `GtkCellArea` the `GtkCellRenderer` expected to have focus the `GtkCellRenderer` to add to @renderer’s focus area Adds @renderer to @area, setting cell properties at the same time. See gtk_cell_area_add() and gtk_cell_area_cell_set() for more details. a `GtkCellArea` a `GtkCellRenderer` to be placed inside @area the name of the first cell property to set a %NULL-terminated list of property names and values, starting with @first_prop_name Applies any connected attributes to the renderers in @area by pulling the values from @tree_model. a `GtkCellArea` the `GtkTreeModel` to pull values from the `GtkTreeIter` in @tree_model to apply values for whether @iter has children whether @iter is expanded in the view and children are visible Connects an @attribute to apply values from @column for the `GtkTreeModel` in use. a `GtkCellArea` the `GtkCellRenderer` to connect an attribute for the attribute name the `GtkTreeModel` column to fetch attribute values from Disconnects @attribute for the @renderer in @area so that attribute will no longer be updated with values from the model. a `GtkCellArea` the `GtkCellRenderer` to disconnect an attribute for the attribute name Returns the model column that an attribute has been mapped to, or -1 if the attribute is not mapped. the model column, or -1 a `GtkCellArea` a `GtkCellRenderer` an attribute on the renderer Gets the values of one or more cell properties for @renderer in @area. a `GtkCellArea` a `GtkCellRenderer` which is inside @area the name of the first cell property to get return location for the first cell property, followed optionally by more name/return location pairs, followed by %NULL Gets the value of a cell property for @renderer in @area. a `GtkCellArea` a `GtkCellRenderer` inside @area the name of the property to get a location to return the value Gets the values of one or more cell properties for @renderer in @area. a `GtkCellArea` a `GtkCellRenderer` inside @area the name of the first property to get return location for the first property, followed optionally by more name/return location pairs, followed by %NULL Sets one or more cell properties for @cell in @area. a `GtkCellArea` a `GtkCellRenderer` which is a cell inside @area the name of the first cell property to set a %NULL-terminated list of property names and values, starting with @first_prop_name Sets a cell property for @renderer in @area. a `GtkCellArea` a `GtkCellRenderer` inside @area the name of the cell property to set the value to set the cell property to Sets one or more cell properties for @renderer in @area. a `GtkCellArea` a `GtkCellRenderer` which inside @area the name of the first cell property to set a %NULL-terminated list of property names and values, starting with @first_prop_name This is sometimes needed for cases where rows need to share alignments in one orientation but may be separately grouped in the opposing orientation. For instance, `GtkIconView` creates all icons (rows) to have the same width and the cells theirin to have the same horizontal alignments. However each row of icons may have a separate collective height. `GtkIconView` uses this to request the heights of each row based on a context which was already used to request all the row widths that are to be displayed. a newly created `GtkCellArea`Context copy of @context. a `GtkCellArea` the `GtkCellArea`Context to copy Creates a `GtkCellArea`Context to be used with @area for all purposes. `GtkCellArea`Context stores geometry information for rows for which it was operated on, it is important to use the same context for the same row of data at all times (i.e. one should render and handle events with the same `GtkCellArea`Context which was used to request the size of those rows of data). a newly created `GtkCellArea`Context which can be used with @area. a `GtkCellArea` Delegates event handling to a `GtkCellArea`. %TRUE if the event was handled by @area. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the `GdkEvent` to handle the @widget relative coordinates for @area the `GtkCellRenderer`State for @area in this row. This should be called by the @area’s owning layout widget when focus is to be passed to @area, or moved within @area for a given @direction and row data. Implementing `GtkCellArea` classes should implement this method to receive and navigate focus in its own way particular to how it lays out cells. %TRUE if focus remains inside @area as a result of this call. a `GtkCellArea` the `GtkDirectionType` Calls @callback for every `GtkCellRenderer` in @area. a `GtkCellArea` the `GtkCellCallback` to call user provided data pointer Calls @callback for every `GtkCellRenderer` in @area with the allocated rectangle inside @cell_area. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the @widget relative coordinates and size for @area the @widget relative coordinates of the background area the `GtkCellAllocCallback` to call user provided data pointer Derives the allocation of @renderer inside @area if @area were to be rendered in @cell_area. a `GtkCellArea` the `GtkCellArea`Context used to hold sizes for @area. the `GtkWidget` that @area is rendering on the `GtkCellRenderer` to get the allocation for the whole allocated area for @area in @widget for this row where to store the allocation for @renderer Gets the `GtkCellRenderer` at @x and @y coordinates inside @area and optionally returns the full cell allocation for it inside @cell_area. the `GtkCellRenderer` at @x and @y. a `GtkCellArea` the `GtkCellArea`Context used to hold sizes for @area. the `GtkWidget` that @area is rendering on the whole allocated area for @area in @widget for this row the x position the y position where to store the inner allocated area of the returned cell renderer Gets the current `GtkTreePath` string for the currently applied `GtkTreeIter`, this is implicitly updated when gtk_cell_area_apply_attributes() is called and can be used to interact with renderers from `GtkCellArea` subclasses. The current `GtkTreePath` string for the current attributes applied to @area. This string belongs to the area and should not be freed. a `GtkCellArea` Gets the `GtkCellEditable` widget currently used to edit the currently edited cell. The currently active `GtkCellEditable` widget a `GtkCellArea` Gets the `GtkCellRenderer` in @area that is currently being edited. The currently edited `GtkCellRenderer` a `GtkCellArea` Retrieves the currently focused cell for @area the currently focused cell in @area. a `GtkCellArea` Gets the `GtkCellRenderer` which is expected to be focusable for which @renderer is, or may be a sibling. This is handy for `GtkCellArea` subclasses when handling events, after determining the renderer at the event location it can then chose to activate the focus cell for which the event cell may have been a sibling. the `GtkCellRenderer` for which @renderer is a sibling a `GtkCellArea` the `GtkCellRenderer` Gets the focus sibling cell renderers for @renderer. A `GList` of `GtkCellRenderer`s. The returned list is internal and should not be freed. a `GtkCellArea` the `GtkCellRenderer` expected to have focus Retrieves a cell area’s initial minimum and natural height. @area will store some geometrical information in @context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the @minimum_height and @natural_height of this call but rather to consult gtk_cell_area_context_get_preferred_height() after a series of requests. a `GtkCellArea` the `GtkCellArea`Context to perform this request with the `GtkWidget` where @area will be rendering location to store the minimum height location to store the natural height Retrieves a cell area’s minimum and natural height if it would be given the specified @width. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_width(). It’s important to perform a series of gtk_cell_area_get_preferred_width() requests with @context first and then call gtk_cell_area_get_preferred_height_for_width() on each cell area individually to get the height for width of each fully requested row. If at some point, the width of a single row changes, it should be requested with gtk_cell_area_get_preferred_width() again and then the full width of the requested rows checked again with gtk_cell_area_context_get_preferred_width(). a `GtkCellArea` the `GtkCellArea`Context which has already been requested for widths. the `GtkWidget` where @area will be rendering the width for which to check the height of this area location to store the minimum height location to store the natural height Retrieves a cell area’s initial minimum and natural width. @area will store some geometrical information in @context along the way; when requesting sizes over an arbitrary number of rows, it’s not important to check the @minimum_width and @natural_width of this call but rather to consult gtk_cell_area_context_get_preferred_width() after a series of requests. a `GtkCellArea` the `GtkCellArea`Context to perform this request with the `GtkWidget` where @area will be rendering location to store the minimum width location to store the natural width Retrieves a cell area’s minimum and natural width if it would be given the specified @height. @area stores some geometrical information in @context along the way while calling gtk_cell_area_get_preferred_height(). It’s important to perform a series of gtk_cell_area_get_preferred_height() requests with @context first and then call gtk_cell_area_get_preferred_width_for_height() on each cell area individually to get the height for width of each fully requested row. If at some point, the height of a single row changes, it should be requested with gtk_cell_area_get_preferred_height() again and then the full height of the requested rows checked again with gtk_cell_area_context_get_preferred_height(). a `GtkCellArea` the `GtkCellArea`Context which has already been requested for widths. the `GtkWidget` where @area will be rendering the height for which to check the width of this area location to store the minimum width location to store the natural width Gets whether the area prefers a height-for-width layout or a width-for-height layout. The `GtkSizeRequestMode` preferred by @area. a `GtkCellArea` Checks if @area contains @renderer. %TRUE if @renderer is in the @area. a `GtkCellArea` the `GtkCellRenderer` to check This is a convenience function for `GtkCellArea` implementations to get the inner area where a given `GtkCellRenderer` will be rendered. It removes any padding previously added by gtk_cell_area_request_renderer(). a `GtkCellArea` the `GtkWidget` that @area is rendering onto the @widget relative coordinates where one of @area’s cells is to be placed the return location for the inner cell area Returns whether the area can do anything when activated, after applying new attributes to @area. whether @area can do anything when activated. a `GtkCellArea` Returns whether @sibling is one of @renderer’s focus siblings (see gtk_cell_area_add_focus_sibling()). %TRUE if @sibling is a focus sibling of @renderer a `GtkCellArea` the `GtkCellRenderer` expected to have focus the `GtkCellRenderer` to check against @renderer’s sibling list Removes @renderer from @area. a `GtkCellArea` the `GtkCellRenderer` to remove from @area Removes @sibling from @renderer’s focus sibling list (see gtk_cell_area_add_focus_sibling()). a `GtkCellArea` the `GtkCellRenderer` expected to have focus the `GtkCellRenderer` to remove from @renderer’s focus area This is a convenience function for `GtkCellArea` implementations to request size for cell renderers. It’s important to use this function to request size and then use gtk_cell_area_inner_cell_area() at render and event time since this function will add padding around the cell for focus painting. a `GtkCellArea` the `GtkCellRenderer` to request size for the `GtkOrientation` in which to request size the `GtkWidget` that @area is rendering onto the allocation contextual size to request for, or -1 if the base request for the orientation is to be returned. location to store the minimum size location to store the natural size Explicitly sets the currently focused cell to @renderer. This is generally called by implementations of `GtkCellAreaClass.focus()` or `GtkCellAreaClass.event()`, however it can also be used to implement functions such as gtk_tree_view_set_cursor_on_cell(). a `GtkCellArea` the `GtkCellRenderer` to give focus to Snapshots @area’s cells according to @area’s layout onto at the given coordinates. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the `GtkSnapshot` to draw to the @widget relative coordinates for @area’s background the @widget relative coordinates for @area the `GtkCellRenderer`State for @area in this row. whether @area should paint focus on focused cells for focused rows or not. Explicitly stops the editing of the currently edited cell. If @canceled is %TRUE, the currently edited cell renderer will emit the ::editing-canceled signal, otherwise the the ::editing-done signal will be emitted on the current edit widget. See gtk_cell_area_get_edited_cell() and gtk_cell_area_get_edit_widget(). a `GtkCellArea` whether editing was canceled. The widget currently editing the edited cell This property is read-only and only changes as a result of a call gtk_cell_area_activate_cell(). The cell in the area that is currently edited This property is read-only and only changes as a result of a call gtk_cell_area_activate_cell(). The cell in the area that currently has focus Indicates that editing has started on @renderer and that @editable should be added to the owning cell-layouting widget at @cell_area. the `GtkCellRenderer` that started the edited the `GtkCellEditable` widget to add the `GtkWidget` relative `GdkRectangle` coordinates where @editable should be added the `GtkTreePath` string this edit was initiated for This signal is emitted whenever applying attributes to @area from @model the `GtkTreeModel` to apply the attributes from the `GtkTreeIter` indicating which row to apply the attributes of whether the view shows children for this row whether the view is currently showing the children of this row Indicates that focus changed on this @area. This signal is emitted either as a result of focus handling or event handling. It's possible that the signal is emitted even if the currently focused renderer did not change, this is because focus may change to the same renderer in the same cell area for a different row of data. the `GtkCellRenderer` that has focus the current `GtkTreePath` string set for @area Indicates that editing finished on @renderer and that @editable should be removed from the owning cell-layouting widget. the `GtkCellRenderer` that finished editeding the `GtkCellEditable` widget to remove A cell area that renders GtkCellRenderers into a row or a column The `GtkCellAreaBox` renders cell renderers into a row or a column depending on its `GtkOrientation`. GtkCellAreaBox uses a notion of packing. Packing refers to adding cell renderers with reference to a particular position in a `GtkCellAreaBox`. There are two reference positions: the start and the end of the box. When the `GtkCellAreaBox` is oriented in the %GTK_ORIENTATION_VERTICAL orientation, the start is defined as the top of the box and the end is defined as the bottom. In the %GTK_ORIENTATION_HORIZONTAL orientation start is defined as the left side and the end is defined as the right side. Alignments of `GtkCellRenderer`s rendered in adjacent rows can be configured by configuring the `GtkCellAreaBox` align child cell property with gtk_cell_area_cell_set_property() or by specifying the "align" argument to gtk_cell_area_box_pack_start() and gtk_cell_area_box_pack_end(). List views use widgets for displaying their contents Creates a new `GtkCellAreaBox`. a newly created `GtkCellAreaBox` Gets the spacing added between cell renderers. the space added between cell renderers in @box. a `GtkCellAreaBox` Adds @renderer to @box, packed with reference to the end of @box. The @renderer is packed after (away from end of) any other `GtkCellRenderer` packed with reference to the end of @box. a `GtkCellAreaBox` the `GtkCellRenderer` to add whether @renderer should receive extra space when the area receives more than its natural size whether @renderer should be aligned in adjacent rows whether @renderer should have the same size in all rows Adds @renderer to @box, packed with reference to the start of @box. The @renderer is packed after any other `GtkCellRenderer` packed with reference to the start of @box. a `GtkCellAreaBox` the `GtkCellRenderer` to add whether @renderer should receive extra space when the area receives more than its natural size whether @renderer should be aligned in adjacent rows whether @renderer should have the same size in all rows Sets the spacing to add between cell renderers in @box. a `GtkCellAreaBox` the space to add between `GtkCellRenderer`s The amount of space to reserve between cells. adds a `GtkCellRenderer` to the area. a `GtkCellArea` the `GtkCellRenderer` to add to @area removes a `GtkCellRenderer` from the area. a `GtkCellArea` the `GtkCellRenderer` to remove from @area calls the `GtkCellCallback` function on every `GtkCellRenderer` in the area with the provided user data until the callback returns %TRUE. a `GtkCellArea` the `GtkCellCallback` to call user provided data pointer Calls the `GtkCellAllocCallback` function on every `GtkCellRenderer` in the area with the allocated area for the cell and the provided user data until the callback returns %TRUE. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the @widget relative coordinates and size for @area the @widget relative coordinates of the background area the `GtkCellAllocCallback` to call user provided data pointer Handle an event in the area, this is generally used to activate a cell at the event location for button events but can also be used to generically pass events to `GtkWidget`s drawn onto the area. %TRUE if the event was handled by @area. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the `GdkEvent` to handle the @widget relative coordinates for @area the `GtkCellRenderer`State for @area in this row. Actually snapshot the area’s cells to the specified rectangle, @background_area should be correctly distributed to the cells corresponding background areas. a `GtkCellArea` the `GtkCellArea`Context for this row of data. the `GtkWidget` that @area is rendering to the `GtkSnapshot` to draw to the @widget relative coordinates for @area’s background the @widget relative coordinates for @area the `GtkCellRenderer`State for @area in this row. whether @area should paint focus on focused cells for focused rows or not. Apply the cell attributes to the cells. This is implemented as a signal and generally `GtkCellArea` subclasses don't need to implement it since it is handled by the base class. a `GtkCellArea` the `GtkTreeModel` to pull values from the `GtkTreeIter` in @tree_model to apply values for whether @iter has children whether @iter is expanded in the view and children are visible Creates and returns a class specific `GtkCellAreaContext` to store cell alignment and allocation details for a said `GtkCellArea` class. a newly created `GtkCellArea`Context which can be used with @area. a `GtkCellArea` Creates a new `GtkCellAreaContext` in the same state as the passed @context with any cell alignment data and allocations intact. a newly created `GtkCellArea`Context copy of @context. a `GtkCellArea` the `GtkCellArea`Context to copy This allows an area to tell its layouting widget whether it prefers to be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. The `GtkSizeRequestMode` preferred by @area. a `GtkCellArea` Calculates the minimum and natural width of the areas cells with the current attributes applied while considering the particular layouting details of the said `GtkCellArea`. While requests are performed over a series of rows, alignments and overall minimum and natural sizes should be stored in the corresponding `GtkCellAreaContext`. a `GtkCellArea` the `GtkCellArea`Context to perform this request with the `GtkWidget` where @area will be rendering location to store the minimum width location to store the natural width Calculates the minimum and natural height for the area if the passed @context would be allocated the given width. When implementing this virtual method it is safe to assume that @context has already stored the aligned cell widths for every `GtkTreeModel` row that @context will be allocated for since this information was stored at `GtkCellAreaClass.get_preferred_width()` time. This virtual method should also store any necessary alignments of cell heights for the case that the context is allocated a height. a `GtkCellArea` the `GtkCellArea`Context which has already been requested for widths. the `GtkWidget` where @area will be rendering the width for which to check the height of this area location to store the minimum height location to store the natural height Calculates the minimum and natural height of the areas cells with the current attributes applied. Essentially this is the same as `GtkCellAreaClass.get_preferred_width()` only for areas that are being requested as %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT. a `GtkCellArea` the `GtkCellArea`Context to perform this request with the `GtkWidget` where @area will be rendering location to store the minimum height location to store the natural height Calculates the minimum and natural width for the area if the passed @context would be allocated the given height. The same as `GtkCellAreaClass.get_preferred_height_for_width()` only for handling requests in the %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. a `GtkCellArea` the `GtkCellArea`Context which has already been requested for widths. the `GtkWidget` where @area will be rendering the height for which to check the width of this area location to store the minimum width location to store the natural width This should be implemented to handle changes in child cell properties for a given `GtkCellRenderer` that were previously installed on the `GtkCellAreaClass` with gtk_cell_area_class_install_cell_property(). This should be implemented to report the values of child cell properties for a given child `GtkCellRenderer`. This virtual method should be implemented to navigate focus from cell to cell inside the `GtkCellArea`. The `GtkCellArea` should move focus from cell to cell inside the area and return %FALSE if focus logically leaves the area with the following exceptions: When the area contains no activatable cells, the entire area receives focus. Focus should not be given to cells that are actually “focus siblings” of other sibling cells (see gtk_cell_area_get_focus_from_sibling()). Focus is set by calling gtk_cell_area_set_focus_cell(). %TRUE if focus remains inside @area as a result of this call. a `GtkCellArea` the `GtkDirectionType` Returns whether the `GtkCellArea` can respond to `GtkCellAreaClass.activate()`, usually this does not need to be implemented since the base class takes care of this however it can be enhanced if the `GtkCellArea` subclass can handle activation in other ways than activating its `GtkCellRenderers`. whether @area can do anything when activated. a `GtkCellArea` This is called when the layouting widget rendering the `GtkCellArea` activates the focus cell (see gtk_cell_area_get_focus_cell()). Whether @area was successfully activated. a `GtkCellArea` the `GtkCellArea`Context in context with the current row data the `GtkWidget` that @area is rendering on the size and location of @area relative to @widget’s allocation the `GtkCellRenderer`State flags for @area for this row of data. if %TRUE then only cell renderers that are %GTK_CELL_RENDERER_MODE_EDITABLE will be activated. Finds a cell property of a cell area class by name. the `GParamSpec` of the child property a `GtkCellAreaClass` the name of the child property to find Installs a cell property on a cell area class. a `GtkCellAreaClass` the id for the property the `GParamSpec` for the property Returns all cell properties of a cell area class. a newly allocated %NULL-terminated array of `GParamSpec`*. The array must be freed with g_free(). a `GtkCellAreaClass` location to return the number of cell properties found Stores geometrical information for a series of rows in a GtkCellArea The `GtkCellAreaContext` object is created by a given `GtkCellArea` implementation via its `GtkCellAreaClass.create_context()` virtual method and is used to store cell sizes and alignments for a series of `GtkTreeModel` rows that are requested and rendered in the same context. `GtkCellLayout` widgets can create any number of contexts in which to request and render groups of data rows. However, it’s important that the same context which was used to request sizes for a given `GtkTreeModel` row also be used for the same row when calling other `GtkCellArea` APIs such as gtk_cell_area_render() and gtk_cell_area_event(). This object will be removed in GTK 5 Allocates a width and/or a height for all rows which are to be rendered with @context. Usually allocation is performed only horizontally or sometimes vertically since a group of rows are usually rendered side by side vertically or horizontally and share either the same width or the same height. Sometimes they are allocated in both horizontal and vertical orientations producing a homogeneous effect of the rows. This is generally the case for `GtkTreeView` when `GtkTreeView:fixed-height-mode` is enabled. This object will be removed in GTK 5 a `GtkCellAreaContext` the allocated width for all `GtkTreeModel` rows rendered with @context, or -1 the allocated height for all `GtkTreeModel` rows rendered with @context, or -1 Gets the accumulative preferred height for @width for all rows which have been requested for the same said @width with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a `GtkCellArea`, the returned values are -1. This object will be removed in GTK 5 a `GtkCellAreaContext` a proposed width for allocation location to store the minimum height location to store the natural height Gets the accumulative preferred width for @height for all rows which have been requested for the same said @height with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a `GtkCellArea`, the returned values are -1. This object will be removed in GTK 5 a `GtkCellAreaContext` a proposed height for allocation location to store the minimum width location to store the natural width Resets any previously cached request and allocation data. When underlying `GtkTreeModel` data changes its important to reset the context if the content size is allowed to shrink. If the content size is only allowed to grow (this is usually an option for views rendering large data stores as a measure of optimization), then only the row that changed or was inserted needs to be (re)requested with gtk_cell_area_get_preferred_width(). When the new overall size of the context requires that the allocated size changes (or whenever this allocation changes at all), the variable row sizes need to be re-requested for every row. For instance, if the rows are displayed all with the same width from top to bottom then a change in the allocated width necessitates a recalculation of all the displayed row heights using gtk_cell_area_get_preferred_height_for_width(). This object will be removed in GTK 5 a `GtkCellAreaContext` Allocates a width and/or a height for all rows which are to be rendered with @context. Usually allocation is performed only horizontally or sometimes vertically since a group of rows are usually rendered side by side vertically or horizontally and share either the same width or the same height. Sometimes they are allocated in both horizontal and vertical orientations producing a homogeneous effect of the rows. This is generally the case for `GtkTreeView` when `GtkTreeView:fixed-height-mode` is enabled. This object will be removed in GTK 5 a `GtkCellAreaContext` the allocated width for all `GtkTreeModel` rows rendered with @context, or -1 the allocated height for all `GtkTreeModel` rows rendered with @context, or -1 Fetches the current allocation size for @context. If the context was not allocated in width or height, or if the context was recently reset with gtk_cell_area_context_reset(), the returned value will be -1. This object will be removed in GTK 5 a `GtkCellAreaContext` location to store the allocated width location to store the allocated height Fetches the `GtkCellArea` this @context was created by. This is generally unneeded by layouting widgets; however, it is important for the context implementation itself to fetch information about the area it is being used for. For instance at `GtkCellAreaContextClass.allocate()` time it’s important to know details about any cell spacing that the `GtkCellArea` is configured with in order to compute a proper allocation. This object will be removed in GTK 5 the `GtkCellArea` this context was created by. a `GtkCellAreaContext` Gets the accumulative preferred height for all rows which have been requested with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a `GtkCellArea`, the returned values are 0. This object will be removed in GTK 5 a `GtkCellAreaContext` location to store the minimum height location to store the natural height Gets the accumulative preferred height for @width for all rows which have been requested for the same said @width with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a `GtkCellArea`, the returned values are -1. This object will be removed in GTK 5 a `GtkCellAreaContext` a proposed width for allocation location to store the minimum height location to store the natural height Gets the accumulative preferred width for all rows which have been requested with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a `GtkCellArea`, the returned values are 0. This object will be removed in GTK 5 a `GtkCellAreaContext` location to store the minimum width location to store the natural width Gets the accumulative preferred width for @height for all rows which have been requested for the same said @height with this context. After gtk_cell_area_context_reset() is called and/or before ever requesting the size of a `GtkCellArea`, the returned values are -1. This object will be removed in GTK 5 a `GtkCellAreaContext` a proposed height for allocation location to store the minimum width location to store the natural width Causes the minimum and/or natural height to grow if the new proposed sizes exceed the current minimum and natural height. This is used by `GtkCellAreaContext` implementations during the request process over a series of `GtkTreeModel` rows to progressively push the requested height over a series of gtk_cell_area_get_preferred_height() requests. This object will be removed in GTK 5 a `GtkCellAreaContext` the proposed new minimum height for @context the proposed new natural height for @context Causes the minimum and/or natural width to grow if the new proposed sizes exceed the current minimum and natural width. This is used by `GtkCellAreaContext` implementations during the request process over a series of `GtkTreeModel` rows to progressively push the requested width over a series of gtk_cell_area_get_preferred_width() requests. This object will be removed in GTK 5 a `GtkCellAreaContext` the proposed new minimum width for @context the proposed new natural width for @context Resets any previously cached request and allocation data. When underlying `GtkTreeModel` data changes its important to reset the context if the content size is allowed to shrink. If the content size is only allowed to grow (this is usually an option for views rendering large data stores as a measure of optimization), then only the row that changed or was inserted needs to be (re)requested with gtk_cell_area_get_preferred_width(). When the new overall size of the context requires that the allocated size changes (or whenever this allocation changes at all), the variable row sizes need to be re-requested for every row. For instance, if the rows are displayed all with the same width from top to bottom then a change in the allocated width necessitates a recalculation of all the displayed row heights using gtk_cell_area_get_preferred_height_for_width(). This object will be removed in GTK 5 a `GtkCellAreaContext` The `GtkCellArea` this context was created by This object will be removed in GTK 5 The minimum height for the `GtkCellArea` in this context for all `GtkTreeModel` rows that this context was requested for using gtk_cell_area_get_preferred_height(). This object will be removed in GTK 5 The minimum width for the `GtkCellArea` in this context for all `GtkTreeModel` rows that this context was requested for using gtk_cell_area_get_preferred_width(). This object will be removed in GTK 5 The natural height for the `GtkCellArea` in this context for all `GtkTreeModel` rows that this context was requested for using gtk_cell_area_get_preferred_height(). This object will be removed in GTK 5 The natural width for the `GtkCellArea` in this context for all `GtkTreeModel` rows that this context was requested for using gtk_cell_area_get_preferred_width(). This object will be removed in GTK 5 This tells the context that an allocation width or height (or both) have been decided for a group of rows. The context should store any allocations for internally aligned cells at this point so that they dont need to be recalculated at gtk_cell_area_render() time. a `GtkCellAreaContext` the allocated width for all `GtkTreeModel` rows rendered with @context, or -1 the allocated height for all `GtkTreeModel` rows rendered with @context, or -1 Clear any previously stored information about requested and allocated sizes for the context. a `GtkCellAreaContext` Returns the aligned height for the given width that context must store while collecting sizes for it’s rows. a `GtkCellAreaContext` a proposed width for allocation location to store the minimum height location to store the natural height Returns the aligned width for the given height that context must store while collecting sizes for it’s rows. a `GtkCellAreaContext` a proposed height for allocation location to store the minimum width location to store the natural width The type of the callback functions used for iterating over the cell renderers of a `GtkCellArea`, see gtk_cell_area_foreach(). %TRUE to stop iterating over cells. the cell renderer to operate on user-supplied data Interface for widgets that can be used for editing cells The `GtkCellEditable` interface must be implemented for widgets to be usable to edit the contents of a `GtkTreeView` cell. It provides a way to specify how temporary widgets should be configured for editing, get the new value, etc. List views use widgets for displaying their contents. See [iface@Gtk.Editable] for editable text widgets Emits the `GtkCellEditable::editing-done` signal. A `GtkCellEditable` Emits the `GtkCellEditable::remove-widget` signal. A `GtkCellEditable` Begins editing on a @cell_editable. The `GtkCellRenderer` for the cell creates and returns a `GtkCellEditable` from gtk_cell_renderer_start_editing(), configured for the `GtkCellRenderer` type. gtk_cell_editable_start_editing() can then set up @cell_editable suitably for editing a cell, e.g. making the Esc key emit `GtkCellEditable::editing-done`. Note that the @cell_editable is created on-demand for the current edit; its lifetime is temporary and does not persist across other edits and/or cells. A `GtkCellEditable` The `GdkEvent` that began the editing process, or %NULL if editing was initiated programmatically Emits the `GtkCellEditable::editing-done` signal. A `GtkCellEditable` Emits the `GtkCellEditable::remove-widget` signal. A `GtkCellEditable` Begins editing on a @cell_editable. The `GtkCellRenderer` for the cell creates and returns a `GtkCellEditable` from gtk_cell_renderer_start_editing(), configured for the `GtkCellRenderer` type. gtk_cell_editable_start_editing() can then set up @cell_editable suitably for editing a cell, e.g. making the Esc key emit `GtkCellEditable::editing-done`. Note that the @cell_editable is created on-demand for the current edit; its lifetime is temporary and does not persist across other edits and/or cells. A `GtkCellEditable` The `GdkEvent` that began the editing process, or %NULL if editing was initiated programmatically Indicates whether editing on the cell has been canceled. This signal is a sign for the cell renderer to update its value from the @cell_editable. Implementations of `GtkCellEditable` are responsible for emitting this signal when they are done editing, e.g. `GtkEntry` emits this signal when the user presses Enter. Typical things to do in a handler for ::editing-done are to capture the edited value, disconnect the @cell_editable from signals on the `GtkCellRenderer`, etc. gtk_cell_editable_editing_done() is a convenience method for emitting `GtkCellEditable::editing-done`. This signal is meant to indicate that the cell is finished editing, and the @cell_editable widget is being removed and may subsequently be destroyed. Implementations of `GtkCellEditable` are responsible for emitting this signal when they are done editing. It must be emitted after the `GtkCellEditable::editing-done` signal, to give the cell renderer a chance to update the cell's value before the widget is removed. gtk_cell_editable_remove_widget() is a convenience method for emitting `GtkCellEditable::remove-widget`. Signal is a sign for the cell renderer to update its value from the cell_editable. A `GtkCellEditable` Signal is meant to indicate that the cell is finished editing, and the widget may now be destroyed. A `GtkCellEditable` Begins editing on a cell_editable. A `GtkCellEditable` The `GdkEvent` that began the editing process, or %NULL if editing was initiated programmatically An interface for packing cells `GtkCellLayout` is an interface to be implemented by all objects which want to provide a `GtkTreeViewColumn` like API for packing cells, setting attributes and data funcs. One of the notable features provided by implementations of `GtkCellLayout` are attributes. Attributes let you set the properties in flexible ways. They can just be set to constant values like regular properties. But they can also be mapped to a column of the underlying tree model with gtk_cell_layout_set_attributes(), which means that the value of the attribute can change from cell to cell as they are rendered by the cell renderer. Finally, it is possible to specify a function with gtk_cell_layout_set_cell_data_func() that is called to determine the value of the attribute for each cell that is rendered. ## GtkCellLayouts as GtkBuildable Implementations of GtkCellLayout which also implement the GtkBuildable interface (`GtkCellView`, `GtkIconView`, `GtkComboBox`, `GtkEntryCompletion`, `GtkTreeViewColumn`) accept `GtkCellRenderer` objects as `<child>` elements in UI definitions. They support a custom `<attributes>` element for their children, which can contain multiple `<attribute>` elements. Each `<attribute>` element has a name attribute which specifies a property of the cell renderer; the content of the element is the attribute value. This is an example of a UI definition fragment specifying attributes: ```xml <object class="GtkCellView"> <child> <object class="GtkCellRendererText"/> <attributes> <attribute name="text">0</attribute> </attributes> </child> </object> ``` Furthermore for implementations of `GtkCellLayout` that use a `GtkCellArea` to lay out cells (all `GtkCellLayout`s in GTK use a `GtkCellArea`) [cell properties](class.CellArea.html#cell-properties) can also be defined in the format by specifying the custom `<cell-packing>` attribute which can contain multiple `<property>` elements. Here is a UI definition fragment specifying cell properties: ```xml <object class="GtkTreeViewColumn"> <child> <object class="GtkCellRendererText"/> <cell-packing> <property name="align">True</property> <property name="expand">False</property> </cell-packing> </child> </object> ``` ## Subclassing GtkCellLayout implementations When subclassing a widget that implements `GtkCellLayout` like `GtkIconView` or `GtkComboBox`, there are some considerations related to the fact that these widgets internally use a `GtkCellArea`. The cell area is exposed as a construct-only property by these widgets. This means that it is possible to e.g. do ```c GtkWIdget *combo = g_object_new (GTK_TYPE_COMBO_BOX, "cell-area", my_cell_area, NULL); ``` to use a custom cell area with a combo box. But construct properties are only initialized after instance `init()` functions have run, which means that using functions which rely on the existence of the cell area in your subclass `init()` function will cause the default cell area to be instantiated. In this case, a provided construct property value will be ignored (with a warning, to alert you to the problem). ```c static void my_combo_box_init (MyComboBox *b) { GtkCellRenderer *cell; cell = gtk_cell_renderer_pixbuf_new (); // The following call causes the default cell area for combo boxes, // a GtkCellAreaBox, to be instantiated gtk_cell_layout_pack_start (GTK_CELL_LAYOUT (b), cell, FALSE); ... } GtkWidget * my_combo_box_new (GtkCellArea *area) { // This call is going to cause a warning about area being ignored return g_object_new (MY_TYPE_COMBO_BOX, "cell-area", area, NULL); } ``` If supporting alternative cell areas with your derived widget is not important, then this does not have to concern you. If you want to support alternative cell areas, you can do so by moving the problematic calls out of `init()` and into a `constructor()` for your class. List views use widgets to display their contents. See [class@Gtk.LayoutManager] for layout manager delegate objects Adds an attribute mapping to the list in @cell_layout. The @column is the column of the model to get a value from, and the @attribute is the property on @cell to be set from that value. So for example if column 2 of the model contains strings, you could have the “text” attribute of a `GtkCellRendererText` get its values from column 2. In this context "attribute" and "property" are used interchangeably. a `GtkCellLayout` a `GtkCellRenderer` a property on the renderer the column position on the model to get the attribute from Unsets all the mappings on all renderers on @cell_layout and removes all renderers from @cell_layout. a `GtkCellLayout` Clears all existing attributes previously set with gtk_cell_layout_set_attributes(). a `GtkCellLayout` a `GtkCellRenderer` to clear the attribute mapping on Returns the underlying `GtkCellArea` which might be @cell_layout if called on a `GtkCellArea` or might be %NULL if no `GtkCellArea` is used by @cell_layout. the cell area used by @cell_layout a `GtkCellLayout` Returns the cell renderers which have been added to @cell_layout. a list of cell renderers. The list, but not the renderers has been newly allocated and should be freed with g_list_free() when no longer needed. a `GtkCellLayout` Adds the @cell to the end of @cell_layout. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Note that reusing the same cell renderer is not supported. a `GtkCellLayout` a `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @cell_layout Packs the @cell into the beginning of @cell_layout. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Note that reusing the same cell renderer is not supported. a `GtkCellLayout` a `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @cell_layout Re-inserts @cell at @position. Note that @cell has already to be packed into @cell_layout for this to function properly. a `GtkCellLayout` a `GtkCellRenderer` to reorder new position to insert @cell at Sets the `GtkCellLayout`DataFunc to use for @cell_layout. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of @cell_layout’s cell renderer(s) as appropriate. @func may be %NULL to remove a previously set function. a `GtkCellLayout` a `GtkCellRenderer` the `GtkCellLayout`DataFunc to use user data for @func destroy notify for @func_data Adds an attribute mapping to the list in @cell_layout. The @column is the column of the model to get a value from, and the @attribute is the property on @cell to be set from that value. So for example if column 2 of the model contains strings, you could have the “text” attribute of a `GtkCellRendererText` get its values from column 2. In this context "attribute" and "property" are used interchangeably. a `GtkCellLayout` a `GtkCellRenderer` a property on the renderer the column position on the model to get the attribute from Unsets all the mappings on all renderers on @cell_layout and removes all renderers from @cell_layout. a `GtkCellLayout` Clears all existing attributes previously set with gtk_cell_layout_set_attributes(). a `GtkCellLayout` a `GtkCellRenderer` to clear the attribute mapping on Returns the underlying `GtkCellArea` which might be @cell_layout if called on a `GtkCellArea` or might be %NULL if no `GtkCellArea` is used by @cell_layout. the cell area used by @cell_layout a `GtkCellLayout` Returns the cell renderers which have been added to @cell_layout. a list of cell renderers. The list, but not the renderers has been newly allocated and should be freed with g_list_free() when no longer needed. a `GtkCellLayout` Adds the @cell to the end of @cell_layout. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Note that reusing the same cell renderer is not supported. a `GtkCellLayout` a `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @cell_layout Packs the @cell into the beginning of @cell_layout. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Note that reusing the same cell renderer is not supported. a `GtkCellLayout` a `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @cell_layout Re-inserts @cell at @position. Note that @cell has already to be packed into @cell_layout for this to function properly. a `GtkCellLayout` a `GtkCellRenderer` to reorder new position to insert @cell at Sets the attributes in the parameter list as the attributes of @cell_layout. See [method@Gtk.CellLayout.add_attribute] for more details. The attributes should be in attribute/column order, as in gtk_cell_layout_add_attribute(). All existing attributes are removed, and replaced with the new attributes. a `GtkCellLayout` a `GtkCellRenderer` a %NULL-terminated list of attributes Sets the `GtkCellLayout`DataFunc to use for @cell_layout. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of @cell_layout’s cell renderer(s) as appropriate. @func may be %NULL to remove a previously set function. a `GtkCellLayout` a `GtkCellRenderer` the `GtkCellLayout`DataFunc to use user data for @func destroy notify for @func_data A function which should set the value of @cell_layout’s cell renderer(s) as appropriate. a `GtkCellLayout` the cell renderer whose value is to be set the model a `GtkTreeIter` indicating the row to set the value for user data passed to gtk_cell_layout_set_cell_data_func() Packs the cell into the beginning of cell_layout. a `GtkCellLayout` a `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @cell_layout Adds the cell to the end of cell_layout. a `GtkCellLayout` a `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @cell_layout Unsets all the mappings on all renderers on cell_layout and removes all renderers from cell_layout. a `GtkCellLayout` Adds an attribute mapping to the list in cell_layout. a `GtkCellLayout` a `GtkCellRenderer` a property on the renderer the column position on the model to get the attribute from Sets the `GtkCellLayout`DataFunc to use for cell_layout. a `GtkCellLayout` a `GtkCellRenderer` the `GtkCellLayout`DataFunc to use user data for @func destroy notify for @func_data Clears all existing attributes previously set with gtk_cell_layout_set_attributes(). a `GtkCellLayout` a `GtkCellRenderer` to clear the attribute mapping on Re-inserts cell at position. a `GtkCellLayout` a `GtkCellRenderer` to reorder new position to insert @cell at Get the cell renderers which have been added to cell_layout. a list of cell renderers. The list, but not the renderers has been newly allocated and should be freed with g_list_free() when no longer needed. a `GtkCellLayout` Get the underlying `GtkCellArea` which might be cell_layout if called on a `GtkCellArea` or might be NULL if no `GtkCellArea` is used by cell_layout. the cell area used by @cell_layout a `GtkCellLayout` An object for rendering a single cell The `GtkCellRenderer` is a base class of a set of objects used for rendering a cell to a `cairo_t`. These objects are used primarily by the `GtkTreeView` widget, though they aren’t tied to them in any specific way. It is worth noting that `GtkCellRenderer` is not a `GtkWidget` and cannot be treated as such. The primary use of a `GtkCellRenderer` is for drawing a certain graphical elements on a `cairo_t`. Typically, one cell renderer is used to draw many cells on the screen. To this extent, it isn’t expected that a CellRenderer keep any permanent state around. Instead, any state is set just prior to use using `GObject`s property system. Then, the cell is measured using gtk_cell_renderer_get_preferred_size(). Finally, the cell is rendered in the correct location using gtk_cell_renderer_snapshot(). There are a number of rules that must be followed when writing a new `GtkCellRenderer`. First and foremost, it’s important that a certain set of properties will always yield a cell renderer of the same size, barring a style change. The `GtkCellRenderer` also has a number of generic properties that are expected to be honored by all children. Beyond merely rendering a cell, cell renderers can optionally provide active user interface elements. A cell renderer can be “activatable” like `GtkCellRenderer`Toggle, which toggles when it gets activated by a mouse click, or it can be “editable” like `GtkCellRenderer`Text, which allows the user to edit the text using a widget implementing the `GtkCellEditable` interface, e.g. `GtkEntry`. To make a cell renderer activatable or editable, you have to implement the `GtkCellRenderer`Class.activate or `GtkCellRenderer`Class.start_editing virtual functions, respectively. Many properties of `GtkCellRenderer` and its subclasses have a corresponding “set” property, e.g. “cell-background-set” corresponds to “cell-background”. These “set” properties reflect whether a property has been set or not. You should not set them independently. List views use widgets for displaying their contents Passes an activate event to the cell renderer for possible processing. Some cell renderers may use events; for example, `GtkCellRendererToggle` toggles when it gets a mouse click. %TRUE if the event was consumed/handled a `GtkCellRenderer` a `GdkEvent` widget that received the event widget-dependent string representation of the event location; e.g. for `GtkTreeView`, a string representation of `GtkTreePath` background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Signal gets emitted when the user cancels the process of editing a cell. Signal gets emitted when a cell starts to be edited. Gets the aligned area used by @cell inside @cell_area. Used for finding the appropriate edit and focus rectangle. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to render flags cell area which would be passed to gtk_cell_renderer_render() the return location for the space inside @cell_area that would actually be used to render. Retrieves a renderer’s natural size when rendered to @widget. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location to store the minimum size location to store the natural size Retrieves a cell renderers’s minimum and natural height if it were rendered to @widget with the specified @width. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to the size which is available for allocation location for storing the minimum size location for storing the preferred size Retrieves a renderer’s natural size when rendered to @widget. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location to store the minimum size location to store the natural size Retrieves a cell renderers’s minimum and natural width if it were rendered to @widget with the specified @height. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to the size which is available for allocation location for storing the minimum size location for storing the preferred size Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. The `GtkSizeRequestMode` preferred by this renderer. a `GtkCellRenderer` instance Invokes the virtual render function of the `GtkCellRenderer`. The three passed-in rectangles are areas in @cr. Most renderers will draw within @cell_area; the xalign, yalign, xpad, and ypad fields of the `GtkCellRenderer` should be honored with respect to @cell_area. @background_area includes the blank space around the cell, and also the area containing the tree expander; so the @background_area rectangles for all cells tile to cover the entire @window. a `GtkCellRenderer` a `GtkSnapshot` to draw to the widget owning @window entire cell area (including tree expanders and maybe padding on the sides) area normally rendered by a cell renderer flags that affect rendering Starts editing the contents of this @cell, through a new `GtkCellEditable` widget created by the `GtkCellRenderer`Class.start_editing virtual function. A new `GtkCellEditable` for editing this @cell, or %NULL if editing is not possible a `GtkCellRenderer` a `GdkEvent` widget that received the event widget-dependent string representation of the event location; e.g. for `GtkTreeView`, a string representation of `GtkTreePath` background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Passes an activate event to the cell renderer for possible processing. Some cell renderers may use events; for example, `GtkCellRendererToggle` toggles when it gets a mouse click. %TRUE if the event was consumed/handled a `GtkCellRenderer` a `GdkEvent` widget that received the event widget-dependent string representation of the event location; e.g. for `GtkTreeView`, a string representation of `GtkTreePath` background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Gets the aligned area used by @cell inside @cell_area. Used for finding the appropriate edit and focus rectangle. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to render flags cell area which would be passed to gtk_cell_renderer_render() the return location for the space inside @cell_area that would actually be used to render. Fills in @xalign and @yalign with the appropriate values of @cell. A `GtkCellRenderer` location to fill in with the x alignment of the cell location to fill in with the y alignment of the cell Fills in @width and @height with the appropriate size of @cell. A `GtkCellRenderer` location to fill in with the fixed width of the cell location to fill in with the fixed height of the cell Checks whether the given `GtkCellRenderer` is expanded. %TRUE if the cell renderer is expanded a `GtkCellRenderer` Checks whether the given `GtkCellRenderer` is an expander. %TRUE if @cell is an expander, and %FALSE otherwise a `GtkCellRenderer` Fills in @xpad and @ypad with the appropriate values of @cell. A `GtkCellRenderer` location to fill in with the x padding of the cell location to fill in with the y padding of the cell Retrieves a renderer’s natural size when rendered to @widget. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location to store the minimum size location to store the natural size Retrieves a cell renderers’s minimum and natural height if it were rendered to @widget with the specified @width. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to the size which is available for allocation location for storing the minimum size location for storing the preferred size Retrieves the minimum and natural size of a cell taking into account the widget’s preference for height-for-width management. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location for storing the minimum size location for storing the natural size Retrieves a renderer’s natural size when rendered to @widget. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location to store the minimum size location to store the natural size Retrieves a cell renderers’s minimum and natural width if it were rendered to @widget with the specified @height. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to the size which is available for allocation location for storing the minimum size location for storing the preferred size Gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. The `GtkSizeRequestMode` preferred by this renderer. a `GtkCellRenderer` instance Returns the cell renderer’s sensitivity. %TRUE if the cell renderer is sensitive A `GtkCellRenderer` Translates the cell renderer state to `GtkStateFlags`, based on the cell renderer and widget sensitivity, and the given `GtkCellRenderer`State. the widget state flags applying to @cell a `GtkCellRenderer` a `GtkWidget` cell renderer state Returns the cell renderer’s visibility. %TRUE if the cell renderer is visible A `GtkCellRenderer` Checks whether the cell renderer can do something when activated. %TRUE if the cell renderer can do anything when activated A `GtkCellRenderer` Sets the renderer’s alignment within its available space. A `GtkCellRenderer` the x alignment of the cell renderer the y alignment of the cell renderer Sets the renderer size to be explicit, independent of the properties set. A `GtkCellRenderer` the width of the cell renderer, or -1 the height of the cell renderer, or -1 Sets whether the given `GtkCellRenderer` is expanded. a `GtkCellRenderer` whether @cell should be expanded Sets whether the given `GtkCellRenderer` is an expander. a `GtkCellRenderer` whether @cell is an expander Sets the renderer’s padding. A `GtkCellRenderer` the x padding of the cell renderer the y padding of the cell renderer Sets the cell renderer’s sensitivity. A `GtkCellRenderer` the sensitivity of the cell Sets the cell renderer’s visibility. A `GtkCellRenderer` the visibility of the cell Invokes the virtual render function of the `GtkCellRenderer`. The three passed-in rectangles are areas in @cr. Most renderers will draw within @cell_area; the xalign, yalign, xpad, and ypad fields of the `GtkCellRenderer` should be honored with respect to @cell_area. @background_area includes the blank space around the cell, and also the area containing the tree expander; so the @background_area rectangles for all cells tile to cover the entire @window. a `GtkCellRenderer` a `GtkSnapshot` to draw to the widget owning @window entire cell area (including tree expanders and maybe padding on the sides) area normally rendered by a cell renderer flags that affect rendering Starts editing the contents of this @cell, through a new `GtkCellEditable` widget created by the `GtkCellRenderer`Class.start_editing virtual function. A new `GtkCellEditable` for editing this @cell, or %NULL if editing is not possible a `GtkCellRenderer` a `GdkEvent` widget that received the event widget-dependent string representation of the event location; e.g. for `GtkTreeView`, a string representation of `GtkTreePath` background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Informs the cell renderer that the editing is stopped. If @canceled is %TRUE, the cell renderer will emit the `GtkCellRenderer`::editing-canceled signal. This function should be called by cell renderer implementations in response to the `GtkCellEditable::editing-done` signal of `GtkCellEditable`. A `GtkCellRenderer` %TRUE if the editing has been canceled Cell background as a `GdkRGBA` This signal gets emitted when the user cancels the process of editing a cell. For example, an editable cell renderer could be written to cancel editing when the user presses Escape. See also: gtk_cell_renderer_stop_editing(). This signal gets emitted when a cell starts to be edited. The intended use of this signal is to do special setup on @editable, e.g. adding a `GtkEntryCompletion` or setting up additional columns in a `GtkComboBox`. See gtk_cell_editable_start_editing() for information on the lifecycle of the @editable and a way to do setup that doesn’t depend on the @renderer. Note that GTK doesn't guarantee that cell renderers will continue to use the same kind of widget for editing in future releases, therefore you should check the type of @editable before doing any specific setup, as in the following example: |[<!-- language="C" --> static void text_editing_started (GtkCellRenderer *cell, GtkCellEditable *editable, const char *path, gpointer data) { if (GTK_IS_ENTRY (editable)) { GtkEntry *entry = GTK_ENTRY (editable); // ... create a GtkEntryCompletion gtk_entry_set_completion (entry, completion); } } ]| the `GtkCellEditable` the path identifying the edited cell Renders a keyboard accelerator in a cell `GtkCellRendererAccel` displays a keyboard accelerator (i.e. a key combination like `Control + a`). If the cell renderer is editable, the accelerator can be changed by simply typing the new combination. Applications editing keyboard accelerators should provide their own implementation according to platform design guidelines Creates a new `GtkCellRendererAccel`. the new cell renderer The keyval of the accelerator. Determines if the edited accelerators are GTK accelerators. If they are, consumed modifiers are suppressed, only accelerators accepted by GTK are allowed, and the accelerators are rendered in the same way as they are in menus. The modifier mask of the accelerator. The hardware keycode of the accelerator. Note that the hardware keycode is only relevant if the key does not have a keyval. Normally, the keyboard configuration should assign keyvals to all keys. Gets emitted when the user has removed the accelerator. the path identifying the row of the edited cell Gets emitted when the user has selected a new accelerator. the path identifying the row of the edited cell the new accelerator keyval the new accelerator modifier mask the keycode of the new accelerator The available modes for [property@Gtk.CellRendererAccel:accel-mode]. GTK accelerators mode Other accelerator mode Called to gets whether the cell renderer prefers a height-for-width layout or a width-for-height layout. The `GtkSizeRequestMode` preferred by this renderer. a `GtkCellRenderer` instance Called to get a renderer’s natural width. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location to store the minimum size location to store the natural size Called to get a renderer’s natural height for width. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to the size which is available for allocation location for storing the minimum size location for storing the preferred size Called to get a renderer’s natural height. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to location to store the minimum size location to store the natural size Called to get a renderer’s natural width for height. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to the size which is available for allocation location for storing the minimum size location for storing the preferred size Called to get the aligned area used by @cell inside @cell_area. a `GtkCellRenderer` instance the `GtkWidget` this cell will be rendering to render flags cell area which would be passed to gtk_cell_renderer_render() the return location for the space inside @cell_area that would actually be used to render. Called to snapshot the content of the `GtkCellRenderer`. a `GtkCellRenderer` a `GtkSnapshot` to draw to the widget owning @window entire cell area (including tree expanders and maybe padding on the sides) area normally rendered by a cell renderer flags that affect rendering Called to activate the content of the `GtkCellRenderer`. %TRUE if the event was consumed/handled a `GtkCellRenderer` a `GdkEvent` widget that received the event widget-dependent string representation of the event location; e.g. for `GtkTreeView`, a string representation of `GtkTreePath` background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Called to initiate editing the content of the `GtkCellRenderer`. A new `GtkCellEditable` for editing this @cell, or %NULL if editing is not possible a `GtkCellRenderer` a `GdkEvent` widget that received the event widget-dependent string representation of the event location; e.g. for `GtkTreeView`, a string representation of `GtkTreePath` background area as passed to gtk_cell_renderer_render() cell area as passed to gtk_cell_renderer_render() render flags Signal gets emitted when the user cancels the process of editing a cell. Signal gets emitted when a cell starts to be edited. Renders a combobox in a cell `GtkCellRendererCombo` renders text in a cell like `GtkCellRendererText` from which it is derived. But while `GtkCellRendererText` offers a simple entry to edit the text, `GtkCellRendererCombo` offers a `GtkComboBox` widget to edit the text. The values to display in the combo box are taken from the tree model specified in the `GtkCellRendererCombo`:model property. The combo cell renderer takes care of adding a text cell renderer to the combo box and sets it to display the column specified by its `GtkCellRendererCombo`:text-column property. Further properties of the combo box can be set in a handler for the `GtkCellRenderer::editing-started` signal. List views use widgets to display their contents. You should use [class@Gtk.DropDown] instead Creates a new `GtkCellRendererCombo`. Adjust how text is drawn using object properties. Object properties can be set globally (with g_object_set()). Also, with `GtkTreeViewColumn`, you can bind a property to a value in a `GtkTreeModel`. For example, you can bind the “text” property on the cell renderer to a string value in the model, thus rendering a different string in each row of the `GtkTreeView`. the new cell renderer If %TRUE, the cell renderer will include an entry and allow to enter values other than the ones in the popup list. Holds a tree model containing the possible values for the combo box. Use the text_column property to specify the column holding the values. Specifies the model column which holds the possible values for the combo box. Note that this refers to the model specified in the model property, not the model backing the tree view to which this cell renderer is attached. `GtkCellRendererCombo` automatically adds a text cell renderer for this column to its combo box. This signal is emitted each time after the user selected an item in the combo box, either by using the mouse or the arrow keys. Contrary to GtkComboBox, GtkCellRendererCombo::changed is not emitted for changes made to a selected item in the entry. The argument @new_iter corresponds to the newly selected item in the combo box and it is relative to the GtkTreeModel set via the model property on GtkCellRendererCombo. Note that as soon as you change the model displayed in the tree view, the tree view will immediately cease the editing operating. This means that you most probably want to refrain from changing the model until the combo cell renderer emits the edited or editing_canceled signal. a string of the path identifying the edited cell (relative to the tree view model) the new iter selected in the combo box (relative to the combo box model) Identifies how the user can interact with a particular cell. The cell is just for display and cannot be interacted with. Note that this doesn’t mean that eg. the row being drawn can’t be selected -- just that a particular element of it cannot be individually modified. The cell can be clicked. The cell can be edited or otherwise modified. Renders a pixbuf in a cell A `GtkCellRendererPixbuf` can be used to render an image in a cell. It allows to render either a given `GdkPixbuf` (set via the `GtkCellRendererPixbuf:pixbuf` property) or a named icon (set via the `GtkCellRendererPixbuf:icon-name` property). To support the tree view, `GtkCellRendererPixbuf` also supports rendering two alternative pixbufs, when the `GtkCellRenderer:is-expander` property is %TRUE. If the `GtkCellRenderer:is-expanded property` is %TRUE and the `GtkCellRendererPixbuf:pixbuf-expander-open` property is set to a pixbuf, it renders that pixbuf, if the `GtkCellRenderer:is-expanded` property is %FALSE and the `GtkCellRendererPixbuf:pixbuf-expander-closed` property is set to a pixbuf, it renders that one. List views use widgets to display their contents. You should use [class@Gtk.Image] for icons, and [class@Gtk.Picture] for images Creates a new `GtkCellRendererPixbuf`. Adjust rendering parameters using object properties. Object properties can be set globally (with g_object_set()). Also, with `GtkTreeViewColumn`, you can bind a property to a value in a `GtkTreeModel`. For example, you can bind the “pixbuf” property on the cell renderer to a pixbuf value in the model, thus rendering a different image in each row of the `GtkTreeView`. the new cell renderer The GIcon representing the icon to display. If the icon theme is changed, the image will be updated automatically. The name of the themed icon to display. This property only has an effect if not overridden by the "pixbuf" property. The `GtkIconSize` value that specifies the size of the rendered icon. Renders numbers as progress bars `GtkCellRendererProgress` renders a numeric value as a progress par in a cell. Additionally, it can display a text on top of the progress bar. List views use widgets to display their contents. You should use [class@Gtk.ProgressBar] instead Creates a new `GtkCellRendererProgress`. the new cell renderer Whether progess is inverted. Setting this to a non-negative value causes the cell renderer to enter "activity mode", where a block bounces back and forth to indicate that some progress is made, without specifying exactly how much. Each increment of the property causes the block to move by a little bit. To indicate that the activity has not started yet, set the property to zero. To indicate completion, set the property to %G_MAXINT. The "text" property determines the label which will be drawn over the progress bar. Setting this property to %NULL causes the default label to be displayed. Setting this property to an empty string causes no label to be displayed. The "text-xalign" property controls the horizontal alignment of the text in the progress bar. Valid values range from 0 (left) to 1 (right). Reserved for RTL layouts. The "text-yalign" property controls the vertical alignment of the text in the progress bar. Valid values range from 0 (top) to 1 (bottom). The "value" property determines the percentage to which the progress bar will be "filled in". Renders a spin button in a cell `GtkCellRendererSpin` renders text in a cell like `GtkCellRendererText` from which it is derived. But while `GtkCellRendererText` offers a simple entry to edit the text, `GtkCellRendererSpin` offers a `GtkSpinButton` widget. Of course, that means that the text has to be parseable as a floating point number. The range of the spinbutton is taken from the adjustment property of the cell renderer, which can be set explicitly or mapped to a column in the tree model, like all properties of cell renders. `GtkCellRendererSpin` also has properties for the `GtkCellRendererSpin:climb-rate` and the number of `GtkCellRendererSpin:digits` to display. Other `GtkSpinButton` properties can be set in a handler for the `GtkCellRenderer::editing-started` signal. List views use widgets to display their contents. You should use [class@Gtk.SpinButton] instead Creates a new `GtkCellRendererSpin`. a new `GtkCellRendererSpin` The adjustment that holds the value of the spinbutton. This must be non-%NULL for the cell renderer to be editable. The acceleration rate when you hold down a button. The number of decimal places to display. Renders a spinning animation in a cell `GtkCellRendererSpinner` renders a spinning animation in a cell, very similar to `GtkSpinner`. It can often be used as an alternative to a `GtkCellRendererProgress` for displaying indefinite activity, instead of actual progress. To start the animation in a cell, set the `GtkCellRendererSpinner:active` property to %TRUE and increment the `GtkCellRendererSpinner:pulse` property at regular intervals. The usual way to set the cell renderer properties for each cell is to bind them to columns in your tree model using e.g. gtk_tree_view_column_add_attribute(). List views use widgets to display their contents. You should use [class@Gtk.Spinner] instead Returns a new cell renderer which will show a spinner to indicate activity. a new `GtkCellRenderer` Whether the spinner is active (ie. shown) in the cell Pulse of the spinner. Increment this value to draw the next frame of the spinner animation. Usually, you would update this value in a timeout. By default, the `GtkSpinner` widget draws one full cycle of the animation, consisting of 12 frames, in 750 milliseconds. The `GtkIconSize` value that specifies the size of the rendered spinner. Tells how a cell is to be rendered. The cell is currently selected, and probably has a selection colored background to render to. The mouse is hovering over the cell. The cell is drawn in an insensitive manner The cell is in a sorted row The cell is in the focus row. The cell is in a row that can be expanded The cell is in a row that is expanded Renders text in a cell A `GtkCellRendererText` renders a given text in its cell, using the font, color and style information provided by its properties. The text will be ellipsized if it is too long and the `GtkCellRendererText:ellipsize` property allows it. If the `GtkCellRenderer:mode` is %GTK_CELL_RENDERER_MODE_EDITABLE, the `GtkCellRendererText` allows to edit its text using an entry. List views use widgets to display their contents. You should use [class@Gtk.Inscription] or [class@Gtk.Label] instead Creates a new `GtkCellRendererText`. Adjust how text is drawn using object properties. Object properties can be set globally (with g_object_set()). Also, with `GtkTreeViewColumn`, you can bind a property to a value in a `GtkTreeModel`. For example, you can bind the “text” property on the cell renderer to a string value in the model, thus rendering a different string in each row of the `GtkTreeView`. the new cell renderer Sets the height of a renderer to explicitly be determined by the “font” and “y_pad” property set on it. Further changes in these properties do not affect the height, so they must be accompanied by a subsequent call to this function. Using this function is inflexible, and should really only be used if calculating the size of a cell is too slow (ie, a massive number of cells displayed). If @number_of_rows is -1, then the fixed height is unset, and the height is determined by the properties again. A `GtkCellRendererText` Number of rows of text each cell renderer is allocated, or -1 Specifies how to align the lines of text with respect to each other. Note that this property describes how to align the lines of text in case there are several of them. The "xalign" property of `GtkCellRenderer`, on the other hand, sets the horizontal alignment of the whole text. Background color as a `GdkRGBA` Specifies the preferred place to ellipsize the string, if the cell renderer does not have enough room to display the entire string. Setting it to %PANGO_ELLIPSIZE_NONE turns off ellipsizing. See the wrap-width property for another way of making the text fit into a given width. Foreground color as a `GdkRGBA` The desired maximum width of the cell, in characters. If this property is set to -1, the width will be calculated automatically. For cell renderers that ellipsize or wrap text; this property controls the maximum reported width of the cell. The cell should not receive any greater allocation unless it is set to expand in its `GtkCellLayout` and all of the cell's siblings have received their natural width. The text that will be displayed in the `GtkCellRenderer` if `GtkCellRendererText:editable` is %TRUE and the cell is empty. The desired width of the cell, in characters. If this property is set to -1, the width will be calculated automatically, otherwise the cell will request either 3 characters or the property value, whichever is greater. Specifies how to break the string into multiple lines, if the cell renderer does not have enough room to display the entire string. This property has no effect unless the wrap-width property is set. Specifies the minimum width at which the text is wrapped. The wrap-mode property can be used to influence at what character positions the line breaks can be placed. Setting wrap-width to -1 turns wrapping off. This signal is emitted after @renderer has been edited. It is the responsibility of the application to update the model and store @new_text at the position indicated by @path. the path identifying the edited cell the new text Renders a toggle button in a cell `GtkCellRendererToggle` renders a toggle button in a cell. The button is drawn as a radio or a checkbutton, depending on the `GtkCellRendererToggle:radio` property. When activated, it emits the `GtkCellRendererToggle::toggled` signal. List views use widgets to display their contents. You should use [class@Gtk.ToggleButton] instead Creates a new `GtkCellRendererToggle`. Adjust rendering parameters using object properties. Object properties can be set globally (with g_object_set()). Also, with `GtkTreeViewColumn`, you can bind a property to a value in a `GtkTreeModel`. For example, you can bind the “active” property on the cell renderer to a boolean value in the model, thus causing the check button to reflect the state of the model. the new cell renderer Returns whether the cell renderer is activatable. See gtk_cell_renderer_toggle_set_activatable(). %TRUE if the cell renderer is activatable. a `GtkCellRendererToggle` Returns whether the cell renderer is active. See gtk_cell_renderer_toggle_set_active(). %TRUE if the cell renderer is active. a `GtkCellRendererToggle` Returns whether we’re rendering radio toggles rather than checkboxes. %TRUE if we’re rendering radio toggles rather than checkboxes a `GtkCellRendererToggle` Makes the cell renderer activatable. a `GtkCellRendererToggle`. the value to set. Activates or deactivates a cell renderer. a `GtkCellRendererToggle`. the value to set. If @radio is %TRUE, the cell renderer renders a radio toggle (i.e. a toggle in a group of mutually-exclusive toggles). If %FALSE, it renders a check toggle (a standalone boolean option). This can be set globally for the cell renderer, or changed just before rendering each cell in the model (for `GtkTreeView`, you set up a per-row setting using `GtkTreeViewColumn` to associate model columns with cell renderer properties). a `GtkCellRendererToggle` %TRUE to make the toggle look like a radio button The ::toggled signal is emitted when the cell is toggled. It is the responsibility of the application to update the model with the correct value to store at @path. Often this is simply the opposite of the value currently stored at @path. string representation of `GtkTreePath` describing the event location A widget displaying a single row of a GtkTreeModel A `GtkCellView` displays a single row of a `GtkTreeModel` using a `GtkCellArea` and `GtkCellAreaContext`. A `GtkCellAreaContext` can be provided to the `GtkCellView` at construction time in order to keep the cellview in context of a group of cell views, this ensures that the renderers displayed will be properly aligned with each other (like the aligned cells in the menus of `GtkComboBox`). `GtkCellView` is `GtkOrientable` in order to decide in which orientation the underlying `GtkCellAreaContext` should be allocated. Taking the `GtkComboBox` menu as an example, cellviews should be oriented horizontally if the menus are listed top-to-bottom and thus all share the same width but may have separate individual heights (left-to-right menus should be allocated vertically since they all share the same height but may have variable widths). ## CSS nodes GtkCellView has a single CSS node with name cellview. List views use widgets to display their contents. You can use [class@Gtk.Box] instead Creates a new `GtkCellView` widget. A newly created `GtkCellView` widget. Creates a new `GtkCellView` widget with a specific `GtkCellArea` to layout cells and a specific `GtkCellAreaContext`. Specifying the same context for a handful of cells lets the underlying area synchronize the geometry for those cells, in this way alignments with cellviews for other rows are possible. A newly created `GtkCellView` widget. the `GtkCellArea` to layout cells the `GtkCellAreaContext` in which to calculate cell geometry Creates a new `GtkCellView` widget, adds a `GtkCellRendererText` to it, and makes it show @markup. The text can be marked up with the [Pango text markup language](https://docs.gtk.org/Pango/pango_markup.html). A newly created `GtkCellView` widget. the text to display in the cell view Creates a new `GtkCellView` widget, adds a `GtkCellRendererText` to it, and makes it show @text. A newly created `GtkCellView` widget. the text to display in the cell view Creates a new `GtkCellView` widget, adds a `GtkCellRendererPixbuf` to it, and makes it show @texture. A newly created `GtkCellView` widget. the image to display in the cell view Returns a `GtkTreePath` referring to the currently displayed row. If no row is currently displayed, %NULL is returned. the currently displayed row a `GtkCellView` Gets whether @cell_view is configured to draw all of its cells in a sensitive state. whether @cell_view draws all of its cells in a sensitive state a `GtkCellView` Gets whether @cell_view is configured to request space to fit the entire `GtkTreeModel`. whether @cell_view requests space to fit the entire `GtkTreeModel`. a `GtkCellView` Returns the model for @cell_view. If no model is used %NULL is returned. a `GtkTreeModel` used a `GtkCellView` Sets the row of the model that is currently displayed by the `GtkCellView`. If the path is unset, then the contents of the cellview “stick” at their last value; this is not normally a desired result, but may be a needed intermediate state if say, the model for the `GtkCellView` becomes temporarily empty. a `GtkCellView` a `GtkTreePath` or %NULL to unset. Sets whether @cell_view should draw all of its cells in a sensitive state, this is used by `GtkComboBox` menus to ensure that rows with insensitive cells that contain children appear sensitive in the parent menu item. a `GtkCellView` whether to draw all cells in a sensitive state. Sets whether @cell_view should request space to fit the entire `GtkTreeModel`. This is used by `GtkComboBox` to ensure that the cell view displayed on the combo box’s button always gets enough space and does not resize when selection changes. a `GtkCellView` whether @cell_view should request space for the whole model. Sets the model for @cell_view. If @cell_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. a `GtkCellView` a `GtkTreeModel` The `GtkCellArea` rendering cells If no area is specified when creating the cell view with gtk_cell_view_new_with_context() a horizontally oriented `GtkCellArea`Box will be used. since 3.0 The `GtkCellAreaContext` used to compute the geometry of the cell view. A group of cell views can be assigned the same context in order to ensure the sizes and cell alignments match across all the views with the same context. `GtkComboBox` menus uses this to assign the same context to all cell views in the menu items for a single menu (each submenu creates its own context since the size of each submenu does not depend on parent or sibling menus). since 3.0 Whether all cells should be draw as sensitive for this view regardless of the actual cell properties (used to make menus with submenus appear sensitive when the items in submenus might be insensitive). since 3.0 Whether the view should request enough space to always fit the size of every row in the model (used by the combo box to ensure the combo box size doesn't change when different items are selected). since 3.0 The model for cell view since 2.10 `GtkCenterBox` arranges three children in a row, keeping the middle child centered as well as possible.  To add children to `GtkCenterBox`, use [method@Gtk.CenterBox.set_start_widget], [method@Gtk.CenterBox.set_center_widget] and [method@Gtk.CenterBox.set_end_widget]. The sizing and positioning of children can be influenced with the align and expand properties of the children. # GtkCenterBox as GtkBuildable The `GtkCenterBox` implementation of the `GtkBuildable` interface supports placing children in the 3 positions by specifying “start”, “center” or “end” as the “type” attribute of a `<child>` element. # CSS nodes `GtkCenterBox` uses a single CSS node with the name “box”, The first child of the `GtkCenterBox` will be allocated depending on the text direction, i.e. in left-to-right layouts it will be allocated on the left and in right-to-left layouts on the right. In vertical orientation, the nodes of the children are arranged from top to bottom. # Accessibility Until GTK 4.10, `GtkCenterBox` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. Starting from GTK 4.12, `GtkCenterBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. Creates a new `GtkCenterBox`. the new `GtkCenterBox`. Gets the value set by gtk_center_box_set_baseline_position(). the baseline position a `GtkCenterBox` Gets the center widget, or %NULL if there is none. the center widget. a `GtkCenterBox` Gets the end widget, or %NULL if there is none. the end widget. a `GtkCenterBox` Gets whether @self shrinks the center widget after other children. whether to shrink the center widget after others a `GtkCenterBox` Gets the start widget, or %NULL if there is none. the start widget. a `GtkCenterBox` Sets the baseline position of a center 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. a `GtkCenterBox` a `GtkBaselinePosition` Sets the center widget. To remove the existing center widget, pass %NULL. a `GtkCenterBox` the new center widget Sets the end widget. To remove the existing end widget, pass %NULL. a `GtkCenterBox` the new end widget Sets whether to shrink the center widget after other children. By default, when there's no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. If set to `FALSE`, start and end widgets keep natural width and the center widget starts shrinking instead. a `GtkCenterBox` whether to shrink the center widget after others Sets the start widget. To remove the existing start widget, pass %NULL. a `GtkCenterBox` the new start widget The position of the baseline aligned widget if extra space is available. The widget that is placed at the center position. The widget that is placed at the end position. In vertical orientation, the end position is at the bottom. In horizontal orientation, the end position is at the trailing edge wrt. to the text direction. Whether to shrink the center widget after other children. By default, when there's no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. If set to `FALSE`, start and end widgets keep natural width and the center widget starts shrinking instead. The widget that is placed at the start position. In vertical orientation, the start position is at the top. In horizontal orientation, the start position is at the leading edge wrt. to the text direction. `GtkCenterLayout` is a layout manager that manages up to three children. The start widget is allocated at the start of the layout (left in left-to-right locales and right in right-to-left ones), and the end widget at the end. The center widget is centered regarding the full width of the layout's. Creates a new `GtkCenterLayout`. the newly created `GtkCenterLayout` Returns the baseline position of the layout. The current baseline position of @self. a `GtkCenterLayout` Returns the center widget of the layout. the current center widget of @self a `GtkCenterLayout` Returns the end widget of the layout. the current end widget of @self a `GtkCenterLayout` Gets the current orienration of the layout manager. The current orientation of @self a `GtkCenterLayout` Gets whether @self shrinks the center widget after other children. whether to shrink the center widget after others a `GtkCenterLayout` Returns the start widget of the layout. The current start widget of @self a `GtkCenterLayout` Sets the new baseline position of @self a `GtkCenterLayout` the new baseline position Sets the new center widget of @self. To remove the existing center widget, pass %NULL. a `GtkCenterLayout` the new center widget Sets the new end widget of @self. To remove the existing center widget, pass %NULL. a `GtkCenterLayout` the new end widget Sets the orientation of @self. a `GtkCenterLayout` the new orientation Sets whether to shrink the center widget after other children. By default, when there's no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. If set to `FALSE`, start and end widgets keep natural width and the center widget starts shrinking instead. a `GtkCenterLayout` whether to shrink the center widget after others Sets the new start widget of @self. To remove the existing start widget, pass %NULL. a `GtkCenterLayout` the new start widget Whether to shrink the center widget after other children. By default, when there's no space to give all three children their natural widths, the start and end widgets start shrinking and the center child keeps natural width until they reach minimum width. If set to `FALSE`, start and end widgets keep natural width and the center widget starts shrinking instead. A `GtkCheckButton` places a label next to an indicator.  A `GtkCheckButton` is created by calling either [ctor@Gtk.CheckButton.new] or [ctor@Gtk.CheckButton.new_with_label]. The state of a `GtkCheckButton` can be set specifically using [method@Gtk.CheckButton.set_active], and retrieved using [method@Gtk.CheckButton.get_active]. # Inconsistent state In addition to "on" and "off", check buttons can be an "in between" state that is neither on nor off. This can be used e.g. when the user has selected a range of elements (such as some text or spreadsheet cells) that are affected by a check button, and the current values in that range are inconsistent. To set a `GtkCheckButton` to inconsistent state, use [method@Gtk.CheckButton.set_inconsistent]. # Grouping Check buttons can be grouped together, to form mutually exclusive groups - only one of the buttons can be toggled at a time, and toggling another one will switch the currently toggled one off. Grouped check buttons use a different indicator, and are commonly referred to as *radio buttons*.  To add a `GtkCheckButton` to a group, use [method@Gtk.CheckButton.set_group]. When the code must keep track of the state of a group of radio buttons, it is recommended to keep track of such state through a stateful `GAction` with a target for each button. Using the `toggled` signals to keep track of the group changes and state is discouraged. # Shortcuts and Gestures `GtkCheckButton` supports the following keyboard shortcuts: - <kbd>␣</kbd> or <kbd>Enter</kbd> activates the button. # CSS nodes ``` checkbutton[.text-button] ├── check ╰── [label] ``` A `GtkCheckButton` has a main node with name checkbutton. If the [property@Gtk.CheckButton:label] or [property@Gtk.CheckButton:child] properties are set, it contains a child widget. The indicator node is named check when no group is set, and radio if the checkbutton is grouped together with other checkbuttons. # Accessibility `GtkCheckButton` uses the %GTK_ACCESSIBLE_ROLE_CHECKBOX role. Creates a new `GtkCheckButton`. a new `GtkCheckButton` Creates a new `GtkCheckButton` with the given text. a new `GtkCheckButton` the text for the check button. Creates a new `GtkCheckButton` with the given text and a mnemonic. a new `GtkCheckButton` The text of the button, with an underscore in front of the mnemonic character Returns whether the check button is active. whether the check button is active a `GtkCheckButton` Gets the child widget of @button or `NULL` if [property@CheckButton:label] is set. the child widget of @button a `GtkCheckButton` Returns whether the check button is in an inconsistent state. %TRUE if @check_button is currently in an inconsistent state a `GtkCheckButton` Returns the label of the check button or `NULL` if [property@CheckButton:child] is set. The label @self shows next to the indicator. If no label is shown, %NULL will be returned. a `GtkCheckButton` Returns whether underlines in the label indicate mnemonics. The value of the [property@Gtk.CheckButton:use-underline] property. See [method@Gtk.CheckButton.set_use_underline] for details on how to set a new value. a `GtkCheckButton` Changes the check buttons active state. a `GtkCheckButton` the new value to set Sets the child widget of @button. Note that by using this API, you take full responsibility for setting up the proper accessibility label and description information for @button. Most likely, you'll either set the accessibility label or description for @button explicitly, or you'll set a labelled-by or described-by relations from @child to @button. a `GtkCheckButton` the child widget Adds @self to the group of @group. In a group of multiple check buttons, only one button can be active at a time. The behavior of a checkbutton in a group is also commonly known as a *radio button*. Setting the group of a check button also changes the css name of the indicator widget's CSS node to 'radio'. Setting up groups in a cycle leads to undefined behavior. Note that the same effect can be achieved via the [iface@Gtk.Actionable] API, by using the same action with parameter type and state type 's' for all buttons in the group, and giving each button its own target value. a `GtkCheckButton` another `GtkCheckButton` to form a group with Sets the `GtkCheckButton` to inconsistent state. You should turn off the inconsistent state again if the user checks the check button. This has to be done manually. a `GtkCheckButton` %TRUE if state is inconsistent Sets the text of @self. If [property@Gtk.CheckButton:use-underline] is %TRUE, an underscore in @label is interpreted as mnemonic indicator, see [method@Gtk.CheckButton.set_use_underline] for details on this behavior. a `GtkCheckButton` The text shown next to the indicator, or %NULL to show no text Sets whether underlines in the label indicate mnemonics. If @setting is %TRUE, an underscore character in @self's label indicates a mnemonic accelerator key. This behavior is similar to [property@Gtk.Label:use-underline]. a `GtkCheckButton` the new value to set If the check button is active. Setting `active` to %TRUE will add the `:checked:` state to both the check button and the indicator CSS node. The child widget. The check button whose group this widget belongs to. If the check button is in an “in between” state. The inconsistent state only affects visual appearance, not the semantics of the button. Text of the label inside the check button, if it contains a label widget. If set, an underline in the text indicates that the following character is to be used as mnemonic. Emitted to when the check button is activated. The `::activate` signal on `GtkCheckButton` is an action signal and emitting it causes the button to animate press then release. Applications should never connect to this signal, but use the [signal@Gtk.CheckButton::toggled] signal. The default bindings for this signal are all forms of the <kbd>␣</kbd> and <kbd>Enter</kbd> keys. Emitted when the buttons's [property@Gtk.CheckButton:active] property changes. An expression using a custom `GClosure` to compute the value from its parameters. Creates a `GtkExpression` that calls `closure` when it is evaluated. `closure` is called with the `this` object and the results of evaluating the `params` expressions. a new `GtkExpression` the type of the value that this expression evaluates to closure to call when evaluating this expression. If closure is floating, it is adopted the number of params needed for evaluating `closure` expressions for each parameter Describes how a [class@Gtk.StringSorter] turns strings into sort keys to compare them. Note that the result of sorting will in general depend on the current locale unless the mode is @GTK_COLLATION_NONE. Don't do any collation Use [func@GLib.utf8_collate_key] Use [func@GLib.utf8_collate_key_for_filename] The `GtkColorButton` allows to open a color chooser dialog to change the color.  It is suitable widget for selecting a color in a preference dialog. # CSS nodes ``` colorbutton ╰── button.color ╰── [content] ``` `GtkColorButton` has a single CSS node with name colorbutton which contains a button node. To differentiate it from a plain `GtkButton`, it gets the .color style class. Use [class@Gtk.ColorDialogButton] instead Creates a new color button. This returns a widget in the form of a small button containing a swatch representing the current selected color. When the button is clicked, a color chooser dialog will open, allowing the user to select a color. The swatch will be updated to reflect the new color when the user finishes. Use [class@Gtk.ColorDialogButton] instead a new color button Creates a new color button showing the given color. a new color button A `GdkRGBA` to set the current color with Gets whether the dialog is modal. Use [class@Gtk.ColorDialogButton] instead %TRUE if the dialog is modal a `GtkColorButton` Gets the title of the color chooser dialog. Use [class@Gtk.ColorDialogButton] instead An internal string, do not free the return value a `GtkColorButton` Sets whether the dialog should be modal. Use [class@Gtk.ColorDialogButton] instead a `GtkColorButton` %TRUE to make the dialog modal Sets the title for the color chooser dialog. Use [class@Gtk.ColorDialogButton] instead a `GtkColorButton` String containing new window title Whether the color chooser dialog should be modal. Whether the color chooser should open in editor mode. This property should be used in cases where the palette in the editor would be redundant, such as when the color button is already part of a palette. The title of the color chooser dialog Emitted to when the color button is activated. The `::activate` signal on `GtkMenuButton` is an action signal and emitting it causes the button to pop up its dialog. Emitted when the user selects a color. When handling this signal, use [method@Gtk.ColorChooser.get_rgba] to find out which color was just selected. Note that this signal is only emitted when the user changes the color. If you need to react to programmatic color changes as well, use the notify::rgba signal. `GtkColorChooser` is an interface that is implemented by widgets for choosing colors. Depending on the situation, colors may be allowed to have alpha (translucency). In GTK, the main widgets that implement this interface are [class@Gtk.ColorChooserWidget], [class@Gtk.ColorChooserDialog] and [class@Gtk.ColorButton]. Use [class@Gtk.ColorDialog] and [class@Gtk.ColorDialogButton] instead of widgets implementing `GtkColorChooser` Adds a palette to the color chooser. If @orientation is horizontal, the colors are grouped in rows, with @colors_per_line colors in each row. If @horizontal is %FALSE, the colors are grouped in columns instead. The default color palette of [class@Gtk.ColorChooserWidget] has 45 colors, organized in columns of 5 colors (this includes some grays). The layout of the color chooser widget works best when the palettes have 9-10 columns. Calling this function for the first time has the side effect of removing the default color palette from the color chooser. If @colors is %NULL, removes all previously added palettes. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` %GTK_ORIENTATION_HORIZONTAL if the palette should be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns the number of colors to show in each row/column the total number of elements in @colors the colors of the palette Gets the currently-selected color. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` a `GdkRGBA` to fill in with the current color Sets the color. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` the new color Adds a palette to the color chooser. If @orientation is horizontal, the colors are grouped in rows, with @colors_per_line colors in each row. If @horizontal is %FALSE, the colors are grouped in columns instead. The default color palette of [class@Gtk.ColorChooserWidget] has 45 colors, organized in columns of 5 colors (this includes some grays). The layout of the color chooser widget works best when the palettes have 9-10 columns. Calling this function for the first time has the side effect of removing the default color palette from the color chooser. If @colors is %NULL, removes all previously added palettes. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` %GTK_ORIENTATION_HORIZONTAL if the palette should be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns the number of colors to show in each row/column the total number of elements in @colors the colors of the palette Gets the currently-selected color. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` a `GdkRGBA` to fill in with the current color Returns whether the color chooser shows the alpha channel. Use [class@Gtk.ColorDialog] instead %TRUE if the color chooser uses the alpha channel, %FALSE if not a `GtkColorChooser` Sets the color. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` the new color Sets whether or not the color chooser should use the alpha channel. Use [class@Gtk.ColorDialog] instead a `GtkColorChooser` %TRUE if color chooser should use alpha channel, %FALSE if not The currently selected color, as a `GdkRGBA` struct. The property can be set to change the current selection programmatically. Use [class@Gtk.ColorDialog] and [class@Gtk.ColorDialogButton] instead of widgets implementing `GtkColorChooser` Whether colors may have alpha (translucency). When ::use-alpha is %FALSE, the `GdkRGBA` struct obtained via the [property@Gtk.ColorChooser:rgba] property will be forced to have alpha == 1. Implementations are expected to show alpha by rendering the color over a non-uniform background (like a checkerboard pattern). Use [class@Gtk.ColorDialog] and [class@Gtk.ColorDialogButton] instead of widgets implementing `GtkColorChooser` Emitted when a color is activated from the color chooser. This usually happens when the user clicks a color swatch, or a color is selected and the user presses one of the keys Space, Shift+Space, Return or Enter. Use [class@Gtk.ColorDialog] and [class@Gtk.ColorDialogButton] instead of widgets implementing `GtkColorChooser` the color A dialog for choosing a color.  `GtkColorChooserDialog` implements the [iface@Gtk.ColorChooser] interface and does not provide much API of its own. To create a `GtkColorChooserDialog`, use [ctor@Gtk.ColorChooserDialog.new]. To change the initially selected color, use [method@Gtk.ColorChooser.set_rgba]. To get the selected color use [method@Gtk.ColorChooser.get_rgba]. `GtkColorChooserDialog` has been deprecated in favor of [class@Gtk.ColorDialog]. ## CSS nodes `GtkColorChooserDialog` has a single CSS node with the name `window` and style class `.colorchooser`. Use [class@Gtk.ColorDialog] instead Creates a new `GtkColorChooserDialog`. Use [class@Gtk.ColorDialog] instead a new `GtkColorChooserDialog` Title of the dialog Transient parent of the dialog Whether the color chooser dialog is showing the single-color editor. It can be set to switch the color chooser into single-color editing mode. a `GtkColorChooser` a `GdkRGBA` to fill in with the current color a `GtkColorChooser` the new color a `GtkColorChooser` %GTK_ORIENTATION_HORIZONTAL if the palette should be displayed in rows, %GTK_ORIENTATION_VERTICAL for columns the number of colors to show in each row/column the total number of elements in @colors the colors of the palette The `GtkColorChooserWidget` widget lets the user select a color. By default, the chooser presents a predefined palette of colors, plus a small number of settable custom colors. It is also possible to select a different color with the single-color editor. To enter the single-color editing mode, use the context menu of any color of the palette, or use the '+' button to add a new custom color. The chooser automatically remembers the last selection, as well as custom colors. To create a `GtkColorChooserWidget`, use [ctor@Gtk.ColorChooserWidget.new]. To change the initially selected color, use [method@Gtk.ColorChooser.set_rgba]. To get the selected color use [method@Gtk.ColorChooser.get_rgba]. The `GtkColorChooserWidget` is used in the [class@Gtk.ColorChooserDialog] to provide a dialog for selecting colors. # Actions `GtkColorChooserWidget` defines a set of built-in actions: - `color.customize` activates the color editor for the given color. - `color.select` emits the [signal@Gtk.ColorChooser::color-activated] signal for the given color. # CSS names `GtkColorChooserWidget` has a single CSS node with name colorchooser. Direct use of `GtkColorChooserWidget` is deprecated. Creates a new `GtkColorChooserWidget`. a new `GtkColorChooserWidget` %TRUE when the color chooser is showing the single-color editor. It can be set to switch the color chooser into single-color editing mode. A `GtkColorDialog` object collects the arguments that are needed to present a color chooser dialog to the user, such as a title for the dialog and whether it should be modal. The dialog is shown with the [method@Gtk.ColorDialog.choose_rgba] function. See [class@Gtk.ColorDialogButton] for a convenient control that uses `GtkColorDialog` and presents the results. Creates a new `GtkColorDialog` object. the new `GtkColorDialog` This function initiates a color choice operation by presenting a color chooser dialog to the user. a `GtkColorDialog` the parent `GtkWindow` the color to select initially a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.ColorDialog.choose_rgba] call and returns the resulting color. the selected color, or `NULL` and @error is set a `GtkColorDialog` a `GAsyncResult` Returns whether the color chooser dialog blocks interaction with the parent window while it is presented. `TRUE` if the color chooser dialog is modal a `GtkColorDialog` Returns the title that will be shown on the color chooser dialog. the title a `GtkColorDialog` Returns whether colors may have alpha. `TRUE` if colors may have alpha a `GtkColorDialog` Sets whether the color chooser dialog blocks interaction with the parent window while it is presented. a `GtkColorDialog` the new value Sets the title that will be shown on the color chooser dialog. a `GtkColorDialog` the new title Sets whether colors may have alpha. a `GtkColorDialog` the new value Whether the color chooser dialog is modal. A title that may be shown on the color chooser dialog that is presented by [method@Gtk.ColorDialog.choose_rgba]. Whether colors may have alpha (translucency). When with-alpha is %FALSE, the color that is selected will be forced to have alpha == 1. The `GtkColorDialogButton` is a wrapped around a [class@Gtk.ColorDialog] and allows to open a color chooser dialog to change the color.  It is suitable widget for selecting a color in a preference dialog. # CSS nodes ``` colorbutton ╰── button.color ╰── [content] ``` `GtkColorDialogButton` has a single CSS node with name colorbutton which contains a button node. To differentiate it from a plain `GtkButton`, it gets the .color style class. Creates a new `GtkColorDialogButton` with the given `GtkColorDialog`. You can pass `NULL` to this function and set a `GtkColorDialog` later. The button will be insensitive until that happens. the new `GtkColorDialogButton` the `GtkColorDialog` to use Returns the `GtkColorDialog` of @self. the `GtkColorDialog` a `GtkColorDialogButton` Returns the color of the button. This function is what should be used to obtain the color that was chosen by the user. To get informed about changes, listen to "notify::rgba". the color a `GtkColorDialogButton` Sets a `GtkColorDialog` object to use for creating the color chooser dialog that is presented when the user clicks the button. a `GtkColorDialogButton` the new `GtkColorDialog` Sets the color of the button. a `GtkColorDialogButton` the new color The `GtkColorDialog` that contains parameters for the color chooser dialog. The selected color. This property can be set to give the button its initial color, and it will be updated to reflect the users choice in the color chooser dialog. Listen to `notify::rgba` to get informed about changes to the buttons color. Emitted when the color dialog button is activated. The `::activate` signal on `GtkColorDialogButton` is an action signal and emitting it causes the button to pop up its dialog. `GtkColumnView` presents a large dynamic list of items using multiple columns with headers. `GtkColumnView` uses the factories of its columns to generate a cell widget for each column, for each visible item and displays them together as the row for this item. The [property@Gtk.ColumnView:show-row-separators] and [property@Gtk.ColumnView:show-column-separators] properties offer a simple way to display separators between the rows or columns. `GtkColumnView` allows the user to select items according to the selection characteristics of the model. For models that allow multiple selected items, it is possible to turn on *rubberband selection*, using [property@Gtk.ColumnView:enable-rubberband]. The column view supports sorting that can be customized by the user by clicking on column headers. To set this up, the `GtkSorter` returned by [method@Gtk.ColumnView.get_sorter] must be attached to a sort model for the data that the view is showing, and the columns must have sorters attached to them by calling [method@Gtk.ColumnViewColumn.set_sorter]. The initial sort order can be set with [method@Gtk.ColumnView.sort_by_column]. The column view also supports interactive resizing and reordering of columns, via Drag-and-Drop of the column headers. This can be enabled or disabled with the [property@Gtk.ColumnView:reorderable] and [property@Gtk.ColumnViewColumn:resizable] properties. To learn more about the list widget framework, see the [overview](section-list-widget.html). # CSS nodes ``` columnview[.column-separators][.rich-list][.navigation-sidebar][.data-table] ├── header │ ├── <column header> ┊ ┊ │ ╰── <column header> │ ├── listview │ ┊ ╰── [rubberband] ``` `GtkColumnView` uses a single CSS node named columnview. It may carry the .column-separators style class, when [property@Gtk.ColumnView:show-column-separators] property is set. Header widgets appear below a node with name header. The rows are contained in a `GtkListView` widget, so there is a listview node with the same structure as for a standalone `GtkListView` widget. If [property@Gtk.ColumnView:show-row-separators] is set, it will be passed on to the list view, causing its CSS node to carry the .separators style class. For rubberband selection, a node with name rubberband is used. The main columnview node may also carry style classes to select the style of [list presentation](section-list-widget.html#list-styles): .rich-list, .navigation-sidebar or .data-table. # Accessibility `GtkColumnView` uses the %GTK_ACCESSIBLE_ROLE_TREE_GRID role, header title widgets are using the %GTK_ACCESSIBLE_ROLE_COLUMN_HEADER role. The row widgets are using the %GTK_ACCESSIBLE_ROLE_ROW role, and individual cells are using the %GTK_ACCESSIBLE_ROLE_GRID_CELL role Creates a new `GtkColumnView`. You most likely want to call [method@Gtk.ColumnView.append_column] to add columns next. a new `GtkColumnView` the list model to use Appends the @column to the end of the columns in @self. a `GtkColumnView` a `GtkColumnViewColumn` that hasn't been added to a `GtkColumnView` yet Gets the list of columns in this column view. This list is constant over the lifetime of @self and can be used to monitor changes to the columns of @self by connecting to the ::items-changed signal. The list managing the columns a `GtkColumnView` Returns whether rows can be selected by dragging with the mouse. %TRUE if rubberband selection is enabled a `GtkColumnView` Gets the factory that's currently used to populate section headers. The factory in use a `GtkColumnView` Gets the model that's currently used to read the items displayed. The model in use a `GtkColumnView` Returns whether columns are reorderable. %TRUE if columns are reorderable a `GtkColumnView` Gets the factory set via [method@Gtk.ColumnView.set_row_factory]. The factory a `GtkColumnView` Returns whether the list should show separators between columns. %TRUE if the list shows column separators a `GtkColumnView` Returns whether the list should show separators between rows. %TRUE if the list shows separators a `GtkColumnView` Returns whether rows will be activated on single click and selected on hover. %TRUE if rows are activated on single click a `GtkColumnView` Returns a special sorter that reflects the users sorting choices in the column view. To allow users to customizable sorting by clicking on column headers, this sorter needs to be set on the sort model underneath the model that is displayed by the view. See [method@Gtk.ColumnViewColumn.set_sorter] for setting up per-column sorting. Here is an example: ```c gtk_column_view_column_set_sorter (column, sorter); gtk_column_view_append_column (view, column); sorter = g_object_ref (gtk_column_view_get_sorter (view))); model = gtk_sort_list_model_new (store, sorter); selection = gtk_no_selection_new (model); gtk_column_view_set_model (view, selection); ``` the `GtkSorter` of @self a `GtkColumnView` Gets the behavior set for the <kbd>Tab</kbd> key. The behavior of the <kbd>Tab</kbd> key a `GtkColumnView` Inserts a column at the given position in the columns of @self. If @column is already a column of @self, it will be repositioned. a `GtkColumnView` the position to insert @column at the `GtkColumnViewColumn` to insert Removes the @column from the list of columns of @self. a `GtkColumnView` a `GtkColumnViewColumn` that's part of @self Scroll to the row at the given position - or cell if a column is given - and performs the actions specified in @flags. This function works no matter if the listview is shown or focused. If it isn't, then the changes will take effect once that happens. The columnview to scroll in position of the item. Must be less than the number of items in the view. The column to scroll to or %NULL to not scroll columns. actions to perform details of how to perform the scroll operation or %NULL to scroll into view Sets whether selections can be changed by dragging with the mouse. a `GtkColumnView` %TRUE to enable rubberband selection Sets the `GtkListItemFactory` to use for populating the [class@Gtk.ListHeader] objects used in section headers. If this factory is set to %NULL, the list will not show section headers. a `GtkColumnView` the factory to use Sets the model to use. This must be a [iface@Gtk.SelectionModel]. a `GtkColumnView` the model to use Sets whether columns should be reorderable by dragging. a `GtkColumnView` whether columns should be reorderable Sets the factory used for configuring rows. The factory must be for configuring [class@Gtk.ColumnViewRow] objects. If this factory is not set - which is the default - then the defaults will be used. This factory is not used to set the widgets displayed in the individual cells. For that see [method@GtkColumnViewColumn.set_factory] and [class@GtkColumnViewCell]. a `GtkColumnView` The row factory Sets whether the list should show separators between columns. a `GtkColumnView` %TRUE to show column separators Sets whether the list should show separators between rows. a `GtkColumnView` %TRUE to show row separators Sets whether rows should be activated on single click and selected on hover. a `GtkColumnView` %TRUE to activate items on single click Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. a `GtkColumnView` The desired tab behavior Sets the sorting of the view. This function should be used to set up the initial sorting. At runtime, users can change the sorting of a column view by clicking on the list headers. This call only has an effect if the sorter returned by [method@Gtk.ColumnView.get_sorter] is set on a sort model, and [method@Gtk.ColumnViewColumn.set_sorter] has been called on @column to associate a sorter with the column. If @column is %NULL, the view will be unsorted. a `GtkColumnView` the `GtkColumnViewColumn` to sort by the direction to sort in The list of columns. Allow rubberband selection. Factory for creating header widgets. The factory must be for configuring [class@Gtk.ListHeader] objects. Model for the items displayed. Whether columns are reorderable. The factory used for configuring rows. The factory must be for configuring [class@Gtk.ColumnViewRow] objects. Show separators between columns. Show separators between rows. Activate rows on single click and select them on hover. Sorter with the sorting choices of the user. Behavior of the <kbd>Tab</kbd> key Emitted when a row has been activated by the user, usually via activating the GtkListBase|list.activate-item action. This allows for a convenient way to handle activation in a columnview. See [method@Gtk.ListItem.set_activatable] for details on how to use this signal. position of item to activate `GtkColumnViewCell` is used by [class@Gtk.ColumnViewColumn] to represent items in a cell in [class@Gtk.ColumnView]. The `GtkColumnViewCell`s are managed by the columnview widget (with its factory) and cannot be created by applications, but they need to be populated by application code. This is done by calling [method@Gtk.ColumnViewCell.set_child]. `GtkColumnViewCell`s exist in 2 stages: 1. The unbound stage where the listitem is not currently connected to an item in the list. In that case, the [property@Gtk.ColumnViewCell:item] property is set to %NULL. 2. The bound stage where the listitem references an item from the list. The [property@Gtk.ColumnViewCell:item] property is not %NULL. Gets the child previously set via gtk_column_view_cell_set_child() or %NULL if none was set. The child a `GtkColumnViewCell` Checks if a list item has been set to be focusable via gtk_column_view_cell_set_focusable(). %TRUE if the item is focusable a `GtkColumnViewCell` Gets the model item that associated with @self. If @self is unbound, this function returns %NULL. The item displayed a `GtkColumnViewCell` Gets the position in the model that @self currently displays. If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. The position of this item a `GtkColumnViewCell` Checks if the item is displayed as selected. The selected state is maintained by the liste widget and its model and cannot be set otherwise. %TRUE if the item is selected. a `GtkColumnViewCell` Sets the child to be used for this listitem. This function is typically called by applications when setting up a listitem so that the widget can be reused when binding it multiple times. a `GtkColumnViewCell` The list item's child or %NULL to unset Sets @self to be focusable. If an item is focusable, it can be focused using the keyboard. This works similar to [method@Gtk.Widget.set_focusable]. Note that if items are not focusable, the keyboard cannot be used to activate them and selecting only works if one of the listitem's children is focusable. By default, list items are focusable. a `GtkColumnViewCell` if the item should be focusable Widget used for display. If the item can be focused with the keyboard. Displayed item. Position of the item. If the item is currently selected. `GtkColumnViewColumn` represents the columns being added to a `GtkColumnView`. The main ingredient for a `GtkColumnViewColumn` is the `GtkListItemFactory` that tells the columnview how to create cells for this column from items in the model. Columns have a title, and can optionally have a header menu set with [method@Gtk.ColumnViewColumn.set_header_menu]. A sorter can be associated with a column using [method@Gtk.ColumnViewColumn.set_sorter], to let users influence sorting by clicking on the column header. Creates a new `GtkColumnViewColumn` that uses the given @factory for mapping items to widgets. You most likely want to call [method@Gtk.ColumnView.append_column] next. The function takes ownership of the argument, so you can write code like: ```c column = gtk_column_view_column_new (_("Name"), gtk_builder_list_item_factory_new_from_resource ("/name.ui")); ``` a new `GtkColumnViewColumn` using the given @factory Title to use for this column The factory to populate items with Gets the column view that's currently displaying this column. If @self has not been added to a column view yet, %NULL is returned. The column view displaying @self. a `GtkColumnViewColumn` Returns whether this column should expand. %TRUE if this column expands a `GtkColumnViewColumn` Gets the factory that's currently used to populate list items for this column. The factory in use a `GtkColumnViewColumn` Gets the fixed width of the column. the fixed with of the column a `GtkColumnViewColumn` Gets the menu model that is used to create the context menu for the column header. the `GMenuModel` a `GtkColumnViewColumn` Returns the ID set with gtk_column_view_column_set_id(). The column's ID a `GtkColumnViewColumn` Returns whether this column is resizable. %TRUE if this column is resizable a `GtkColumnViewColumn` Returns the sorter that is associated with the column. the `GtkSorter` of @self a `GtkColumnViewColumn` Returns the title set with gtk_column_view_column_set_title(). The column's title a `GtkColumnViewColumn` Returns whether this column is visible. %TRUE if this column is visible a `GtkColumnViewColumn` Sets the column to take available extra space. The extra space is shared equally amongst all columns that have the expand set to %TRUE. a `GtkColumnViewColumn` %TRUE if this column should expand to fill available sace Sets the `GtkListItemFactory` to use for populating list items for this column. a `GtkColumnViewColumn` the factory to use If @fixed_width is not -1, sets the fixed width of @column; otherwise unsets it. Setting a fixed width overrides the automatically calculated width. Interactive resizing also sets the “fixed-width” property. a `GtkColumnViewColumn` the new fixed width, or -1 Sets the menu model that is used to create the context menu for the column header. a `GtkColumnViewColumn` a `GMenuModel` Sets the id of this column. GTK makes no use of this, but applications can use it when storing column view configuration. It is up to callers to ensure uniqueness of IDs. a `GtkColumnViewColumn` ID to use for this column Sets whether this column should be resizable by dragging. a `GtkColumnViewColumn` whether this column should be resizable Associates a sorter with the column. If @sorter is %NULL, the column will not let users change the sorting by clicking on its header. This sorter can be made active by clicking on the column header, or by calling [method@Gtk.ColumnView.sort_by_column]. See [method@Gtk.ColumnView.get_sorter] for the necessary steps for setting up customizable sorting for [class@Gtk.ColumnView]. a `GtkColumnViewColumn` the `GtkSorter` to associate with @column Sets the title of this column. The title is displayed in the header of a `GtkColumnView` for this column and is therefore user-facing text that should be translated. a `GtkColumnViewColumn` Title to use for this column Sets whether this column should be visible in views. a `GtkColumnViewColumn` whether this column should be visible The `GtkColumnView` this column is a part of. Column gets share of extra width allocated to the view. Factory for populating list items. The factory must be for configuring [class@Gtk.ColumnViewCell] objects. If not -1, this is the width that the column is allocated, regardless of the size of its content. Menu model used to create the context menu for the column header. An ID for the column. GTK is not currently using the ID for anything, but it can be used by applications when saving column view configurations. It is up to applications to ensure uniqueness of IDs. Whether this column is resizable. Sorter for sorting items according to this column. Title displayed in the header. Whether this column is visible. `GtkColumnViewRow` is used by [class@Gtk.ColumnView] to allow configuring how rows are displayed. It is not used to set the widgets displayed in the individual cells. For that see [method@GtkColumnViewColumn.set_factory] and [class@GtkColumnViewCell]. Gets the accessible description of @self. the accessible description a `GtkColumnViewRow` Gets the accessible label of @self. the accessible label a `GtkColumnViewRow` Checks if the row has been set to be activatable via gtk_column_view_row_set_activatable(). %TRUE if the row is activatable a `GtkColumnViewRow` Checks if a row item has been set to be focusable via gtk_column_view_row_set_focusable(). %TRUE if the row is focusable a `GtkColumnViewRow` Gets the model item that associated with @self. If @self is unbound, this function returns %NULL. The item displayed a `GtkColumnViewRow` Gets the position in the model that @self currently displays. If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. The position of this row a `GtkColumnViewRow` Checks if the row has been set to be selectable via gtk_column_view_row_set_selectable(). Do not confuse this function with [method@Gtk.ColumnViewRow.get_selected]. %TRUE if the row is selectable a `GtkColumnViewRow` Checks if the item is selected that this row corresponds to. The selected state is maintained by the list widget and its model and cannot be set otherwise. %TRUE if the item is selected. a `GtkColumnViewRow` Sets the accessible description for the row, which may be used by e.g. screen readers. a `GtkColumnViewRow` the description Sets the accessible label for the row, which may be used by e.g. screen readers. a `GtkColumnViewRow` the label Sets @self to be activatable. If a row is activatable, double-clicking on the row, using the Return key or calling gtk_widget_activate() will activate the row. Activating instructs the containing columnview to emit the [signal@Gtk.ColumnView::activate] signal. By default, row are activatable. a `GtkColumnViewRow` if the row should be activatable Sets @self to be focusable. If a row is focusable, it can be focused using the keyboard. This works similar to [method@Gtk.Widget.set_focusable]. Note that if row are not focusable, the contents of cells can still be focused if they are focusable. By default, rows are focusable. a `GtkColumnViewRow` if the row should be focusable Sets @self to be selectable. If a row is selectable, clicking on the row or using the keyboard will try to select or unselect the row. Whether this succeeds is up to the model to determine, as it is managing the selected state. Note that this means that making a row non-selectable has no influence on the selected state at all. A non-selectable row may still be selected. By default, rows are selectable. a `GtkColumnViewRow` if the row should be selectable The accessible description to set on the row. The accessible label to set on the row. If the row can be activated by the user. If the row can be focused with the keyboard. The item for this row. Position of the row. If the row can be selected by the user. If the item in the row is currently selected. `GtkColumnViewSorter` is a sorter implementation that is geared towards the needs of `GtkColumnView`. The sorter returned by [method@Gtk.ColumnView.get_sorter] is a `GtkColumnViewSorter`. In column views, sorting can be configured by associating sorters with columns, and users can invert sort order by clicking on column headers. The API of `GtkColumnViewSorter` is designed to allow saving and restoring this configuration. If you are only interested in the primary sort column (i.e. the column where a sort indicator is shown in the header), then you can just look at [property@Gtk.ColumnViewSorter:primary-sort-column] and [property@Gtk.ColumnViewSorter:primary-sort-order]. If you want to store the full sort configuration, including secondary sort columns that are used for tie breaking, then you can use [method@Gtk.ColumnViewSorter.get_nth_sort_column]. To get notified about changes, use [signal@Gtk.Sorter::changed]. To restore a saved sort configuration on a `GtkColumnView`, use code like: ``` sorter = gtk_column_view_get_sorter (view); for (i = gtk_column_view_sorter_get_n_sort_columns (sorter) - 1; i >= 0; i--) { column = gtk_column_view_sorter_get_nth_sort_column (sorter, i, &order); gtk_column_view_sort_by_column (view, column, order); } ``` Returns the number of columns by which the sorter sorts. If the sorter of the primary sort column does not determine a total order, then the secondary sorters are consulted to break the ties. Use the [signal@Gtk.Sorter::changed] signal to get notified when the number of sort columns changes. the number of sort columns a `GtkColumnViewSorter` Gets the @position'th sort column and its associated sort order. Use the [signal@Gtk.Sorter::changed] signal to get notified when sort columns change. the @positions sort column a `GtkColumnViewSorter` the position of the sort column to retrieve (0 for the primary sort column) return location for the sort order Returns the primary sort column. The primary sort column is the one that displays the triangle in a column view header. the primary sort column a `GtkColumnViewSorter` Returns the primary sort order. The primary sort order determines whether the triangle displayed in the column view header of the primary sort column points upwards or downwards. If there is no primary sort column, then this function returns `GTK_SORT_ASCENDING`. the primary sort order a `GtkColumnViewSorter` The primary sort column. The primary sort column is the one that displays the triangle in a column view header. The primary sort order. The primary sort order determines whether the triangle displayed in the column view header of the primary sort column points upwards or downwards. A `GtkComboBox` is a widget that allows the user to choose from a list of valid choices.  The `GtkComboBox` displays the selected choice; when activated, the `GtkComboBox` displays a popup which allows the user to make a new choice. The `GtkComboBox` uses the model-view pattern; the list of valid choices is specified in the form of a tree model, and the display of the choices can be adapted to the data in the model by using cell renderers, as you would in a tree view. This is possible since `GtkComboBox` implements the [iface@Gtk.CellLayout] interface. The tree model holding the valid choices is not restricted to a flat list, it can be a real tree, and the popup will reflect the tree structure. To allow the user to enter values not in the model, the [property@Gtk.ComboBox:has-entry] property allows the `GtkComboBox` to contain a [class@Gtk.Entry]. This entry can be accessed by calling [method@Gtk.ComboBox.get_child] on the combo box. For a simple list of textual choices, the model-view API of `GtkComboBox` can be a bit overwhelming. In this case, [class@Gtk.ComboBoxText] offers a simple alternative. Both `GtkComboBox` and `GtkComboBoxText` can contain an entry. ## CSS nodes ``` combobox ├── box.linked │ ╰── button.combo │ ╰── box │ ├── cellview │ ╰── arrow ╰── window.popup ``` A normal combobox contains a box with the .linked class, a button with the .combo class and inside those buttons, there are a cellview and an arrow. ``` combobox ├── box.linked │ ├── entry.combo │ ╰── button.combo │ ╰── box │ ╰── arrow ╰── window.popup ``` A `GtkComboBox` with an entry has a single CSS node with name combobox. It contains a box with the .linked class. That box contains an entry and a button, both with the .combo class added. The button also contains another node with name arrow. ## Accessibility `GtkComboBox` uses the %GTK_ACCESSIBLE_ROLE_COMBO_BOX role. Use [class@Gtk.DropDown] instead Creates a new empty `GtkComboBox`. Use [class@Gtk.DropDown] A new `GtkComboBox` Creates a new empty `GtkComboBox` with an entry. In order to use a combo box with entry, you need to tell it which column of the model contains the text for the entry by calling [method@Gtk.ComboBox.set_entry_text_column]. Use [class@Gtk.DropDown] A new `GtkComboBox` Creates a new `GtkComboBox` with a model. Use [class@Gtk.DropDown] A new `GtkComboBox` a `GtkTreeModel` Creates a new empty `GtkComboBox` with an entry and a model. See also [ctor@Gtk.ComboBox.new_with_entry]. Use [class@Gtk.DropDown] A new `GtkComboBox` A `GtkTreeModel` Signal is emitted when the active item is changed. Signal which allows you to change how the text displayed in a combo box’s entry is displayed. Returns the index of the currently active item. If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this function returns `gtk_tree_path_get_indices (path)[0]`, where `path` is the [struct@Gtk.TreePath] of the active item. Use [class@Gtk.DropDown] An integer which is the index of the currently active item, or -1 if there’s no active item A `GtkComboBox` Returns the ID of the active row of @combo_box. This value is taken from the active row and the column specified by the [property@Gtk.ComboBox:id-column] property of @combo_box (see [method@Gtk.ComboBox.set_id_column]). The returned value is an interned string which means that you can compare the pointer by value to other interned strings and that you must not free it. If the [property@Gtk.ComboBox:id-column] property of @combo_box is not set, or if no row is active, or if the active row has a %NULL ID value, then %NULL is returned. Use [class@Gtk.DropDown] the ID of the active row a `GtkComboBox` Sets @iter to point to the currently active item. If no item is active, @iter is left unchanged. Use [class@Gtk.DropDown] %TRUE if @iter was set, %FALSE otherwise A `GtkComboBox` A `GtkTreeIter` Returns whether the combo box sets the dropdown button sensitive or not when there are no items in the model. Use [class@Gtk.DropDown] %GTK_SENSITIVITY_ON if the dropdown button is sensitive when the model is empty, %GTK_SENSITIVITY_OFF if the button is always insensitive or %GTK_SENSITIVITY_AUTO if it is only sensitive as long as the model has one item to be selected. a `GtkComboBox` Gets the child widget of @combo_box. Use [class@Gtk.DropDown] the child widget of @combo_box a `GtkComboBox` Returns the column which @combo_box is using to get the strings from to display in the internal entry. Use [class@Gtk.DropDown] A column in the data source model of @combo_box. A `GtkComboBox` Returns whether the combo box has an entry. Use [class@Gtk.DropDown] whether there is an entry in @combo_box. a `GtkComboBox` Returns the column which @combo_box is using to get string IDs for values from. Use [class@Gtk.DropDown] A column in the data source model of @combo_box. A `GtkComboBox` Returns the `GtkTreeModel` of @combo_box. Use [class@Gtk.DropDown] A `GtkTreeModel` which was passed during construction. A `GtkComboBox` Gets whether the popup uses a fixed width. Use [class@Gtk.DropDown] %TRUE if the popup uses a fixed width a `GtkComboBox` Returns the current row separator function. Use [class@Gtk.DropDown] the current row separator function. a `GtkComboBox` Hides the menu or dropdown list of @combo_box. This function is mostly intended for use by accessibility technologies; applications should have little use for it. Use [class@Gtk.DropDown] a `GtkComboBox` Pops up the menu or dropdown list of @combo_box. This function is mostly intended for use by accessibility technologies; applications should have little use for it. Before calling this, @combo_box must be mapped, or nothing will happen. Use [class@Gtk.DropDown] a `GtkComboBox` Pops up the menu of @combo_box. Note that currently this does not do anything with the device, as it was previously only used for list-mode combo boxes, and those were removed in GTK 4. However, it is retained in case similar functionality is added back later. Use [class@Gtk.DropDown] a `GtkComboBox` a `GdkDevice` Sets the active item of @combo_box to be the item at @index. Use [class@Gtk.DropDown] a `GtkComboBox` An index in the model passed during construction, or -1 to have no active item Changes the active row of @combo_box to the one that has an ID equal to @active_id. If @active_id is %NULL, the active row is unset. Rows having a %NULL ID string cannot be made active by this function. If the [property@Gtk.ComboBox:id-column] property of @combo_box is unset or if no row has the given ID then the function does nothing and returns %FALSE. Use [class@Gtk.DropDown] %TRUE if a row with a matching ID was found. If a %NULL @active_id was given to unset the active row, the function always returns %TRUE. a `GtkComboBox` the ID of the row to select Sets the current active item to be the one referenced by @iter. If @iter is %NULL, the active item is unset. Use [class@Gtk.DropDown] A `GtkComboBox` The `GtkTreeIter` Sets whether the dropdown button of the combo box should update its sensitivity depending on the model contents. Use [class@Gtk.DropDown] a `GtkComboBox` specify the sensitivity of the dropdown button Sets the child widget of @combo_box. Use [class@Gtk.DropDown] a `GtkComboBox` the child widget Sets the model column which @combo_box should use to get strings from to be @text_column. For this column no separate [class@Gtk.CellRenderer] is needed. The column @text_column in the model of @combo_box must be of type %G_TYPE_STRING. This is only relevant if @combo_box has been created with [property@Gtk.ComboBox:has-entry] as %TRUE. Use [class@Gtk.DropDown] A `GtkComboBox` A column in @model to get the strings from for the internal entry Sets the model column which @combo_box should use to get string IDs for values from. The column @id_column in the model of @combo_box must be of type %G_TYPE_STRING. Use [class@Gtk.DropDown] A `GtkComboBox` A column in @model to get string IDs for values from Sets the model used by @combo_box to be @model. Will unset a previously set model (if applicable). If model is %NULL, then it will unset the model. Note that this function does not clear the cell renderers, you have to call [method@Gtk.CellLayout.clear] yourself if you need to set up different cell renderers for the new model. Use [class@Gtk.DropDown] A `GtkComboBox` A `GtkTreeModel` Specifies whether the popup’s width should be a fixed width. If @fixed is %TRUE, the popup's width is set to match the allocated width of the combo box. Use [class@Gtk.DropDown] a `GtkComboBox` whether to use a fixed popup width Sets the row separator function, which is used to determine whether a row should be drawn as a separator. If the row separator function is %NULL, no separators are drawn. This is the default value. Use [class@Gtk.DropDown] a `GtkComboBox` a `GtkTreeViewRowSeparatorFunc` user data to pass to @func destroy notifier for @data The item which is currently active. If the model is a non-flat treemodel, and the active item is not an immediate child of the root of the tree, this property has the value `gtk_tree_path_get_indices (path)[0]`, where `path` is the [struct@Gtk.TreePath] of the active item. The value of the ID column of the active row. Whether the dropdown button is sensitive when the model is empty. The child widget. The model column to associate with strings from the entry. This is property only relevant if the combo was created with [property@Gtk.ComboBox:has-entry] is %TRUE. Whether the combo box has an entry. The `has-frame` property controls whether a frame is drawn around the entry. The model column that provides string IDs for the values in the model, if != -1. The model from which the combo box takes its values. Whether the popup's width should be a fixed width matching the allocated width of the combo box. Whether the combo boxes dropdown is popped up. Note that this property is mainly useful, because it allows you to connect to notify::popup-shown. Emitted to when the combo box is activated. The `::activate` signal on `GtkComboBox` is an action signal and emitting it causes the combo box to pop up its dropdown. Emitted when the active item is changed. The can be due to the user selecting a different item from the list, or due to a call to [method@Gtk.ComboBox.set_active_iter]. It will also be emitted while typing into the entry of a combo box with an entry. Emitted to allow changing how the text in a combo box's entry is displayed. See [property@Gtk.ComboBox:has-entry]. Connect a signal handler which returns an allocated string representing @path. That string will then be used to set the text in the combo box's entry. The default signal handler uses the text from the [property@Gtk.ComboBox:entry-text-column] model column. Here's an example signal handler which fetches data from the model and displays it in the entry. ```c static char * format_entry_text_callback (GtkComboBox *combo, const char *path, gpointer user_data) { GtkTreeIter iter; GtkTreeModel model; double value; model = gtk_combo_box_get_model (combo); gtk_tree_model_get_iter_from_string (model, &iter, path); gtk_tree_model_get (model, &iter, THE_DOUBLE_VALUE_COLUMN, &value, -1); return g_strdup_printf ("%g", value); } ``` a newly allocated string representing @path for the current `GtkComboBox` model. the [struct@Gtk.TreePath] string from the combo box's current model to format text for Emitted to move the active selection. This is an [keybinding signal](class.SignalAction.html). a `GtkScrollType` Emitted to popdown the combo box list. This is an [keybinding signal](class.SignalAction.html). The default bindings for this signal are Alt+Up and Escape. whether the combo box was popped down Emitted to popup the combo box list. This is an [keybinding signal](class.SignalAction.html). The default binding for this signal is Alt+Down. The parent class. Signal is emitted when the active item is changed. Signal which allows you to change how the text displayed in a combo box’s entry is displayed. A `GtkComboBoxText` is a simple variant of `GtkComboBox` for text-only use cases.  `GtkComboBoxText` hides the model-view complexity of `GtkComboBox`. To create a `GtkComboBoxText`, use [ctor@Gtk.ComboBoxText.new] or [ctor@Gtk.ComboBoxText.new_with_entry]. You can add items to a `GtkComboBoxText` with [method@Gtk.ComboBoxText.append_text], [method@Gtk.ComboBoxText.insert_text] or [method@Gtk.ComboBoxText.prepend_text] and remove options with [method@Gtk.ComboBoxText.remove]. If the `GtkComboBoxText` contains an entry (via the [property@Gtk.ComboBox:has-entry] property), its contents can be retrieved using [method@Gtk.ComboBoxText.get_active_text]. You should not call [method@Gtk.ComboBox.set_model] or attempt to pack more cells into this combo box via its [iface@Gtk.CellLayout] interface. ## GtkComboBoxText as GtkBuildable The `GtkComboBoxText` implementation of the `GtkBuildable` interface supports adding items directly using the `<items>` element and specifying `<item>` elements for each item. Each `<item>` element can specify the “id” corresponding to the appended text and also supports the regular translation attributes “translatable”, “context” and “comments”. Here is a UI definition fragment specifying `GtkComboBoxText` items: ```xml <object class="GtkComboBoxText"> <items> <item translatable="yes" id="factory">Factory</item> <item translatable="yes" id="home">Home</item> <item translatable="yes" id="subway">Subway</item> </items> </object> ``` ## CSS nodes ``` combobox ╰── box.linked ├── entry.combo ├── button.combo ╰── window.popup ``` `GtkComboBoxText` has a single CSS node with name combobox. It adds the style class .combo to the main CSS nodes of its entry and button children, and the .linked class to the node of its internal box. Use [class@Gtk.DropDown] with a [class@Gtk.StringList] instead Creates a new `GtkComboBoxText`. Use [class@Gtk.DropDown] A new `GtkComboBoxText` Creates a new `GtkComboBoxText` with an entry. Use [class@Gtk.DropDown] a new `GtkComboBoxText` Appends @text to the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. This is the same as calling [method@Gtk.ComboBoxText.insert] with a position of -1. Use [class@Gtk.DropDown] A `GtkComboBoxText` a string ID for this value A string Appends @text to the list of strings stored in @combo_box. This is the same as calling [method@Gtk.ComboBoxText.insert_text] with a position of -1. Use [class@Gtk.DropDown] A `GtkComboBoxText` A string Returns the currently active string in @combo_box. If no row is currently selected, %NULL is returned. If @combo_box contains an entry, this function will return its contents (which will not necessarily be an item from the list). Use [class@Gtk.DropDown] a newly allocated string containing the currently active text. Must be freed with g_free(). A `GtkComboBoxText` Inserts @text at @position in the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. See [property@Gtk.ComboBox:id-column]. If @position is negative then @text is appended. Use [class@Gtk.DropDown] A `GtkComboBoxText` An index to insert @text a string ID for this value A string to display Inserts @text at @position in the list of strings stored in @combo_box. If @position is negative then @text is appended. This is the same as calling [method@Gtk.ComboBoxText.insert] with a %NULL ID string. Use [class@Gtk.DropDown] A `GtkComboBoxText` An index to insert @text A string Prepends @text to the list of strings stored in @combo_box. If @id is non-%NULL then it is used as the ID of the row. This is the same as calling [method@Gtk.ComboBoxText.insert] with a position of 0. Use [class@Gtk.DropDown] A `GtkComboBox` a string ID for this value a string Prepends @text to the list of strings stored in @combo_box. This is the same as calling [method@Gtk.ComboBoxText.insert_text] with a position of 0. Use [class@Gtk.DropDown] A `GtkComboBox` A string Removes the string at @position from @combo_box. Use [class@Gtk.DropDown] A `GtkComboBox` Index of the item to remove Removes all the text entries from the combo box. Use [class@Gtk.DropDown] A `GtkComboBoxText` A constant value in a `GtkExpression`. Creates a `GtkExpression` that evaluates to the object given by the arguments. a new `GtkExpression` The type of the object arguments to create the object from Creates an expression that always evaluates to the given `value`. a new `GtkExpression` a `GValue` Gets the value that a constant expression evaluates to. the value a constant `GtkExpression` `GtkConstraint` describes a constraint between attributes of two widgets, expressed as a linear equation. The typical equation for a constraint is: ``` target.target_attr = source.source_attr × multiplier + constant ``` Each `GtkConstraint` is part of a system that will be solved by a [class@Gtk.ConstraintLayout] in order to allocate and position each child widget or guide. The source and target, as well as their attributes, of a `GtkConstraint` instance are immutable after creation. Creates a new constraint representing a relation between a layout attribute on a source and a layout attribute on a target. the newly created constraint the target of the constraint the attribute of `target` to be set the relation equivalence between `target_attribute` and `source_attribute` the source of the constraint the attribute of `source` to be read a multiplication factor to be applied to `source_attribute` a constant factor to be added to `source_attribute` the strength of the constraint Creates a new constraint representing a relation between a layout attribute on a target and a constant value. the newly created constraint a the target of the constraint the attribute of `target` to be set the relation equivalence between `target_attribute` and `constant` a constant factor to be set on `target_attribute` the strength of the constraint Retrieves the constant factor added to the source attributes' value. a constant factor a `GtkConstraint` Retrieves the multiplication factor applied to the source attribute's value. a multiplication factor a `GtkConstraint` The order relation between the terms of the constraint. a relation type a `GtkConstraint` Retrieves the [iface@Gtk.ConstraintTarget] used as the source for the constraint. If the source is set to `NULL` at creation, the constraint will use the widget using the [class@Gtk.ConstraintLayout] as the source. the source of the constraint a `GtkConstraint` Retrieves the attribute of the source to be read by the constraint. the source's attribute a `GtkConstraint` Retrieves the strength of the constraint. the strength value a `GtkConstraint` Retrieves the [iface@Gtk.ConstraintTarget] used as the target for the constraint. If the targe is set to `NULL` at creation, the constraint will use the widget using the [class@Gtk.ConstraintLayout] as the target. a `GtkConstraintTarget` a `GtkConstraint` Retrieves the attribute of the target to be set by the constraint. the target's attribute a `GtkConstraint` Checks whether the constraint is attached to a [class@Gtk.ConstraintLayout], and it is contributing to the layout. `TRUE` if the constraint is attached a `GtkConstraint` Checks whether the constraint describes a relation between an attribute on the [property@Gtk.Constraint:target] and a constant value. `TRUE` if the constraint is a constant relation a `GtkConstraint` Checks whether the constraint is a required relation for solving the constraint layout. %TRUE if the constraint is required a `GtkConstraint` The constant value to be added to the [property@Gtk.Constraint:source-attribute]. The multiplication factor to be applied to the [property@Gtk.Constraint:source-attribute]. The order relation between the terms of the constraint. The source of the constraint. The constraint will set the [property@Gtk.Constraint:target-attribute] property of the target using the [property@Gtk.Constraint:source-attribute] property of the source. The attribute of the [property@Gtk.Constraint:source] read by the constraint. The strength of the constraint. The strength can be expressed either using one of the symbolic values of the [enum@Gtk.ConstraintStrength] enumeration, or any positive integer value. The target of the constraint. The constraint will set the [property@Gtk.Constraint:target-attribute] property of the target using the [property@Gtk.Constraint:source-attribute] property of the source widget. The attribute of the [property@Gtk.Constraint:target] set by the constraint. The widget attributes that can be used when creating a [class@Constraint]. No attribute, used for constant relations The left edge of a widget, regardless of text direction The right edge of a widget, regardless of text direction The top edge of a widget The bottom edge of a widget The leading edge of a widget, depending on text direction; equivalent to %GTK_CONSTRAINT_ATTRIBUTE_LEFT for LTR languages, and %GTK_CONSTRAINT_ATTRIBUTE_RIGHT for RTL ones The trailing edge of a widget, depending on text direction; equivalent to %GTK_CONSTRAINT_ATTRIBUTE_RIGHT for LTR languages, and %GTK_CONSTRAINT_ATTRIBUTE_LEFT for RTL ones The width of a widget The height of a widget The center of a widget, on the horizontal axis The center of a widget, on the vertical axis The baseline of a widget A `GtkConstraintGuide` is an invisible layout element in a `GtkConstraintLayout`. The `GtkConstraintLayout` treats guides like widgets. They can be used as the source or target of a `GtkConstraint`. Guides have a minimum, maximum and natural size. Depending on the constraints that are applied, they can act like a guideline that widgets can be aligned to, or like *flexible space*. Unlike a `GtkWidget`, a `GtkConstraintGuide` will not be drawn. Creates a new `GtkConstraintGuide` object. a new `GtkConstraintGuide` object. Gets the maximum size of @guide. a `GtkConstraintGuide` object return location for the maximum width return location for the maximum height Gets the minimum size of @guide. a `GtkConstraintGuide` object return location for the minimum width return location for the minimum height Retrieves the name set using gtk_constraint_guide_set_name(). the name of the guide a `GtkConstraintGuide` Gets the natural size of @guide. a `GtkConstraintGuide` object return location for the natural width return location for the natural height Retrieves the strength set using gtk_constraint_guide_set_strength(). the strength of the constraint on the natural size a `GtkConstraintGuide` Sets the maximum size of @guide. If @guide is attached to a `GtkConstraintLayout`, the constraints will be updated to reflect the new size. a `GtkConstraintGuide` object the new maximum width, or -1 to not change it the new maximum height, or -1 to not change it Sets the minimum size of @guide. If @guide is attached to a `GtkConstraintLayout`, the constraints will be updated to reflect the new size. a `GtkConstraintGuide` object the new minimum width, or -1 to not change it the new minimum height, or -1 to not change it Sets a name for the given `GtkConstraintGuide`. The name is useful for debugging purposes. a `GtkConstraintGuide` a name for the @guide Sets the natural size of @guide. If @guide is attached to a `GtkConstraintLayout`, the constraints will be updated to reflect the new size. a `GtkConstraintGuide` object the new natural width, or -1 to not change it the new natural height, or -1 to not change it Sets the strength of the constraint on the natural size of the given `GtkConstraintGuide`. a `GtkConstraintGuide` the strength of the constraint The maximum height of the guide. The maximum width of the guide. The minimum height of the guide. The minimum width of the guide. A name that identifies the `GtkConstraintGuide`, for debugging. The preferred, or natural, height of the guide. The preferred, or natural, width of the guide. The `GtkConstraintStrength` to be used for the constraint on the natural size of the guide. A layout manager using constraints to describe relations between widgets. `GtkConstraintLayout` is a layout manager that uses relations between widget attributes, expressed via [class@Gtk.Constraint] instances, to measure and allocate widgets. ### How do constraints work Constraints are objects defining the relationship between attributes of a widget; you can read the description of the [class@Gtk.Constraint] class to have a more in depth definition. By taking multiple constraints and applying them to the children of a widget using `GtkConstraintLayout`, it's possible to describe complex layout policies; each constraint applied to a child or to the parent widgets contributes to the full description of the layout, in terms of parameters for resolving the value of each attribute. It is important to note that a layout is defined by the totality of constraints; removing a child, or a constraint, from an existing layout without changing the remaining constraints may result in an unstable or unsolvable layout. Constraints have an implicit "reading order"; you should start describing each edge of each child, as well as their relationship with the parent container, from the top left (or top right, in RTL languages), horizontally first, and then vertically. A constraint-based layout with too few constraints can become "unstable", that is: have more than one solution. The behavior of an unstable layout is undefined. A constraint-based layout with conflicting constraints may be unsolvable, and lead to an unstable layout. You can use the [property@Gtk.Constraint:strength] property of [class@Gtk.Constraint] to "nudge" the layout towards a solution. ### GtkConstraintLayout as GtkBuildable `GtkConstraintLayout` implements the [iface@Gtk.Buildable] interface and has a custom "constraints" element which allows describing constraints in a [class@Gtk.Builder] UI file. An example of a UI definition fragment specifying a constraint: ```xml <object class="GtkConstraintLayout"> <constraints> <constraint target="button" target-attribute="start" relation="eq" source="super" source-attribute="start" constant="12" strength="required" /> <constraint target="button" target-attribute="width" relation="ge" constant="250" strength="strong" /> </constraints> </object> ``` The definition above will add two constraints to the GtkConstraintLayout: - a required constraint between the leading edge of "button" and the leading edge of the widget using the constraint layout, plus 12 pixels - a strong, constant constraint making the width of "button" greater than, or equal to 250 pixels The "target" and "target-attribute" attributes are required. The "source" and "source-attribute" attributes of the "constraint" element are optional; if they are not specified, the constraint is assumed to be a constant. The "relation" attribute is optional; if not specified, the constraint is assumed to be an equality. The "strength" attribute is optional; if not specified, the constraint is assumed to be required. The "source" and "target" attributes can be set to "super" to indicate that the constraint target is the widget using the GtkConstraintLayout. There can be "constant" and "multiplier" attributes. Additionally, the "constraints" element can also contain a description of the `GtkConstraintGuides` used by the layout: ```xml <constraints> <guide min-width="100" max-width="500" name="hspace"/> <guide min-height="64" nat-height="128" name="vspace" strength="strong"/> </constraints> ``` The "guide" element has the following optional attributes: - "min-width", "nat-width", and "max-width", describe the minimum, natural, and maximum width of the guide, respectively - "min-height", "nat-height", and "max-height", describe the minimum, natural, and maximum height of the guide, respectively - "strength" describes the strength of the constraint on the natural size of the guide; if not specified, the constraint is assumed to have a medium strength - "name" describes a name for the guide, useful when debugging ### Using the Visual Format Language Complex constraints can be described using a compact syntax called VFL, or *Visual Format Language*. The Visual Format Language describes all the constraints on a row or column, typically starting from the leading edge towards the trailing one. Each element of the layout is composed by "views", which identify a [iface@Gtk.ConstraintTarget]. For instance: ``` [button]-[textField] ``` Describes a constraint that binds the trailing edge of "button" to the leading edge of "textField", leaving a default space between the two. Using VFL is also possible to specify predicates that describe constraints on attributes like width and height: ``` // Width must be greater than, or equal to 50 [button(>=50)] // Width of button1 must be equal to width of button2 [button1(==button2)] ``` The default orientation for a VFL description is horizontal, unless otherwise specified: ``` // horizontal orientation, default attribute: width H:[button(>=150)] // vertical orientation, default attribute: height V:[button1(==button2)] ``` It's also possible to specify multiple predicates, as well as their strength: ``` // minimum width of button must be 150 // natural width of button can be 250 [button(>=150@required, ==250@medium)] ``` Finally, it's also possible to use simple arithmetic operators: ``` // width of button1 must be equal to width of button2 // divided by 2 plus 12 [button1(button2 / 2 + 12)] ``` Creates a new `GtkConstraintLayout` layout manager. the newly created `GtkConstraintLayout` Adds a constraint to the layout manager. The [property@Gtk.Constraint:source] and [property@Gtk.Constraint:target] properties of `constraint` can be: - set to `NULL` to indicate that the constraint refers to the widget using `layout` - set to the [class@Gtk.Widget] using `layout` - set to a child of the [class@Gtk.Widget] using `layout` - set to a [class@Gtk.ConstraintGuide] that is part of `layout` The @layout acquires the ownership of @constraint after calling this function. a `GtkConstraintLayout` a [class@Gtk.Constraint] Creates a list of constraints from a VFL description. This function is a convenience wrapper around [method@Gtk.ConstraintLayout.add_constraints_from_descriptionv], using variadic arguments to populate the view/target map. the list of [class@Gtk.Constraint]s that were added to the layout a `GtkConstraintLayout` an array of Visual Format Language lines defining a set of constraints the number of lines default horizontal spacing value, or -1 for the fallback value default vertical spacing value, or -1 for the fallback value return location for a `GError` the name of a view in the VFL description, followed by the [iface@Gtk.ConstraintTarget] to which it maps a `NULL`-terminated list of view names and [iface@Gtk.ConstraintTarget]s Creates a list of constraints from a VFL description. The Visual Format Language, VFL, is based on Apple's AutoLayout [VFL](https://developer.apple.com/library/content/documentation/UserExperience/Conceptual/AutolayoutPG/VisualFormatLanguage.html). The `views` dictionary is used to match [iface@Gtk.ConstraintTarget] instances to the symbolic view name inside the VFL. The VFL grammar is: ``` <visualFormatString> = (<orientation>)? (<superview><connection>)? <view>(<connection><view>)* (<connection><superview>)? <orientation> = 'H' | 'V' <superview> = '|' <connection> = '' | '-' <predicateList> '-' | '-' <predicateList> = <simplePredicate> | <predicateListWithParens> <simplePredicate> = <metricName> | <positiveNumber> <predicateListWithParens> = '(' <predicate> (',' <predicate>)* ')' <predicate> = (<relation>)? <objectOfPredicate> (<operatorList>)? ('@' <priority>)? <relation> = '==' | '<=' | '>=' <objectOfPredicate> = <constant> | <viewName> | ('.' <attributeName>)? <priority> = <positiveNumber> | 'required' | 'strong' | 'medium' | 'weak' <constant> = <number> <operatorList> = (<multiplyOperator>)? (<addOperator>)? <multiplyOperator> = [ '*' | '/' ] <positiveNumber> <addOperator> = [ '+' | '-' ] <positiveNumber> <viewName> = [A-Za-z_]([A-Za-z0-9_]*) // A C identifier <metricName> = [A-Za-z_]([A-Za-z0-9_]*) // A C identifier <attributeName> = 'top' | 'bottom' | 'left' | 'right' | 'width' | 'height' | 'start' | 'end' | 'centerX' | 'centerY' | 'baseline' <positiveNumber> // A positive real number parseable by g_ascii_strtod() <number> // A real number parseable by g_ascii_strtod() ``` **Note**: The VFL grammar used by GTK is slightly different than the one defined by Apple, as it can use symbolic values for the constraint's strength instead of numeric values; additionally, GTK allows adding simple arithmetic operations inside predicates. Examples of VFL descriptions are: ``` // Default spacing [button]-[textField] // Width constraint [button(>=50)] // Connection to super view |-50-[purpleBox]-50-| // Vertical layout V:[topField]-10-[bottomField] // Flush views [maroonView][blueView] // Priority [button(100@strong)] // Equal widths [button1(==button2)] // Multiple predicates [flexibleButton(>=70,<=100)] // A complete line of layout |-[find]-[findNext]-[findField(>=20)]-| // Operators [button1(button2 / 3 + 50)] // Named attributes [button1(==button2.height)] ``` the list of [class@Gtk.Constraint] instances that were added to the layout a `GtkConstraintLayout` an array of Visual Format Language lines defining a set of constraints the number of lines default horizontal spacing value, or -1 for the fallback value default vertical spacing value, or -1 for the fallback value a dictionary of `[ name, target ]` pairs; the `name` keys map to the view names in the VFL lines, while the `target` values map to children of the widget using a `GtkConstraintLayout`, or guides Adds a guide to `layout`. A guide can be used as the source or target of constraints, like a widget, but it is not visible. The `layout` acquires the ownership of `guide` after calling this function. a `GtkConstraintLayout` a [class@Gtk.ConstraintGuide] object Returns a `GListModel` to track the constraints that are part of the layout. Calling this function will enable extra internal bookkeeping to track constraints and emit signals on the returned listmodel. It may slow down operations a lot. Applications should try hard to avoid calling this function because of the slowdowns. a `GListModel` tracking the layout's constraints a `GtkConstraintLayout` Returns a `GListModel` to track the guides that are part of the layout. Calling this function will enable extra internal bookkeeping to track guides and emit signals on the returned listmodel. It may slow down operations a lot. Applications should try hard to avoid calling this function because of the slowdowns. a `GListModel` tracking the layout's guides a `GtkConstraintLayout` Removes all constraints from the layout manager. a `GtkConstraintLayout` Removes `constraint` from the layout manager, so that it no longer influences the layout. a `GtkConstraintLayout` a [class@Gtk.Constraint] Removes `guide` from the layout manager, so that it no longer influences the layout. a `GtkConstraintLayout` a [class@Gtk.ConstraintGuide] object `GtkLayoutChild` subclass for children in a `GtkConstraintLayout`. The relation between two terms of a constraint. Less than, or equal Equal Greater than, or equal The strength of a constraint, expressed as a symbolic constant. The strength of a [class@Constraint] can be expressed with any positive integer; the values of this enumeration can be used for readability. The constraint is required towards solving the layout A strong constraint A medium constraint A weak constraint The `GtkConstraintTarget` interface is implemented by objects that can be used as source or target in `GtkConstraint`s. Besides `GtkWidget`, it is also implemented by `GtkConstraintGuide`. Domain for VFL parsing errors. Invalid or unknown symbol Invalid or unknown attribute Invalid or unknown view Invalid or unknown metric Invalid or unknown priority Invalid or unknown relation Registers an error quark for VFL error parsing. the error quark Controls how a content should be made to fit inside an allocation. Make the content fill the entire allocation, without taking its aspect ratio in consideration. The resulting content will appear as stretched if its aspect ratio is different from the allocation aspect ratio. Scale the content to fit the allocation, while taking its aspect ratio in consideration. The resulting content will appear as letterboxed if its aspect ratio is different from the allocation aspect ratio. Cover the entire allocation, while taking the content aspect ratio in consideration. The resulting content will appear as clipped if its aspect ratio is different from the allocation aspect ratio. The content is scaled down to fit the allocation, if needed, otherwise its original size is used. Specifies which corner a child widget should be placed in when packed into a `GtkScrolledWindow.` This is effectively the opposite of where the scroll bars are placed. Place the scrollbars on the right and bottom of the widget (default behaviour). Place the scrollbars on the top and right of the widget. Place the scrollbars on the left and bottom of the widget. Place the scrollbars on the top and left of the widget. A description of a location inside a CSS stream. Errors that can occur while parsing CSS. These errors are unexpected and will cause parts of the given CSS to be ignored. Unknown failure. The given text does not form valid syntax Failed to import a resource The given name has not been defined The given value is not correct Warnings that can occur while parsing CSS. Unlike `GtkCssParserError`s, warnings do not cause the parser to skip any input, but they indicate issues that should be fixed. The given construct is deprecated and will be removed in a future version A syntax construct was used that should be avoided A feature is not implemented `GtkCssProvider` is an object implementing the `GtkStyleProvider` interface for CSS. It is able to parse CSS-like input in order to style widgets. An application can make GTK parse a specific CSS style sheet by calling [method@Gtk.CssProvider.load_from_file] or [method@Gtk.CssProvider.load_from_resource] and adding the provider with [method@Gtk.StyleContext.add_provider] or [func@Gtk.StyleContext.add_provider_for_display]. In addition, certain files will be read when GTK is initialized. First, the file `$XDG_CONFIG_HOME/gtk-4.0/gtk.css` is loaded if it exists. Then, GTK loads the first existing file among `XDG_DATA_HOME/themes/THEME/gtk-VERSION/gtk-VARIANT.css`, `$HOME/.themes/THEME/gtk-VERSION/gtk-VARIANT.css`, `$XDG_DATA_DIRS/themes/THEME/gtk-VERSION/gtk-VARIANT.css` and `DATADIR/share/themes/THEME/gtk-VERSION/gtk-VARIANT.css`, where `THEME` is the name of the current theme (see the [property@Gtk.Settings:gtk-theme-name] setting), `VARIANT` is the variant to load (see the [property@Gtk.Settings:gtk-application-prefer-dark-theme] setting), `DATADIR` is the prefix configured when GTK was compiled (unless overridden by the `GTK_DATA_PREFIX` environment variable), and `VERSION` is the GTK version number. If no file is found for the current version, GTK tries older versions all the way back to 4.0. To track errors while loading CSS, connect to the [signal@Gtk.CssProvider::parsing-error] signal. Returns a newly created `GtkCssProvider`. A new `GtkCssProvider` Loads @data into @css_provider. This clears any previously loaded information. a `GtkCssProvider` `GBytes` containing the data to load Loads @data into @css_provider. This clears any previously loaded information. Use [method@Gtk.CssProvider.load_from_string] or [method@Gtk.CssProvider.load_from_bytes] instead a `GtkCssProvider` CSS data to be parsed the length of @data in bytes, or -1 for NUL terminated strings Loads the data contained in @file into @css_provider. This clears any previously loaded information. a `GtkCssProvider` `GFile` pointing to a file to load Loads the data contained in @path into @css_provider. This clears any previously loaded information. a `GtkCssProvider` the path of a filename to load, in the GLib filename encoding Loads the data contained in the resource at @resource_path into the @css_provider. This clears any previously loaded information. a `GtkCssProvider` a `GResource` resource path Loads @string into @css_provider. This clears any previously loaded information. a `GtkCssProvider` the CSS to load Loads a theme from the usual theme paths. The actual process of finding the theme might change between releases, but it is guaranteed that this function uses the same mechanism to load the theme that GTK uses for loading its own theme. a `GtkCssProvider` A theme name variant to load, for example, "dark", or %NULL for the default Converts the @provider into a string representation in CSS format. Using [method@Gtk.CssProvider.load_from_string] with the return value from this function on a new provider created with [ctor@Gtk.CssProvider.new] will basically create a duplicate of this @provider. a new string representing the @provider. the provider to write to a string Signals that a parsing error occurred. The expected error values are in the [error@Gtk.CssParserError] and [enum@Gtk.CssParserWarning] enumerations. The @path, @line and @position describe the actual location of the error as accurately as possible. Parsing errors are never fatal, so the parsing will resume after the error. Errors may however cause parts of the given data or even all of it to not be parsed at all. So it is a useful idea to check that the parsing succeeds by connecting to this signal. Errors in the [enum@Gtk.CssParserWarning] enumeration should not be treated as fatal errors. Note that this signal may be emitted at any time as the css provider may opt to defer parsing parts or all of the input to a later time than when a loading function was called. section the error happened in The parsing error Defines a part of a CSS document. Because sections are nested into one another, you can use [method@CssSection.get_parent] to get the containing region. Creates a new `GtkCssSection` referring to the section in the given `file` from the `start` location to the `end` location. a new `GtkCssSection` The file this section refers to The start location The end location Creates a new `GtkCssSection` referring to the section in the given `file` or the given `bytes` from the `start` location to the `end` location. a new `GtkCssSection` The file this section refers to The bytes this sections refers to The start location The end location Gets the bytes that @section was parsed from. the `GBytes` from which the `section` was parsed the section Returns the location in the CSS document where this section ends. The end location of this section the section Gets the file that @section was parsed from. If no such file exists, for example because the CSS was loaded via [method@Gtk.CssProvider.load_from_data], then `NULL` is returned. the `GFile` from which the `section` was parsed the section Gets the parent section for the given `section`. The parent section is the section that contains this `section`. A special case are sections of type `GTK_CSS_SECTION_DOCUMEN`T. Their parent will either be `NULL` if they are the original CSS document that was loaded by [method@Gtk.CssProvider.load_from_file] or a section of type `GTK_CSS_SECTION_IMPORT` if it was loaded with an `@import` rule from a different file. the parent section the section Returns the location in the CSS document where this section starts. The start location of this section the section Prints the `section` into `string` in a human-readable form. This is a form like `gtk.css:32:1-23` to denote line 32, characters 1 to 23 in the file `gtk.css`. a section a `GString` to print to Increments the reference count on `section`. the CSS section itself. a `GtkCssSection` Prints the section into a human-readable text form using [method@Gtk.CssSection.print]. A new string. a `GtkCssSection` Decrements the reference count on `section`, freeing the structure if the reference count reaches 0. a `GtkCssSection` A CSS style change. A function to be used by `GtkCustomLayout` to allocate a widget. the widget to allocate the new width of the widget the new height of the widget the new baseline of the widget, or -1 `GtkCustomFilter` determines whether to include items with a callback. Creates a new filter using the given @match_func to filter items. If @match_func is %NULL, the filter matches all items. If the filter func changes its filtering behavior, gtk_filter_changed() needs to be called. a new `GtkCustomFilter` function to filter items user data to pass to @match_func destroy notify for @user_data Sets the function used for filtering items. If @match_func is %NULL, the filter matches all items. If the filter func changes its filtering behavior, gtk_filter_changed() needs to be called. If a previous function was set, its @user_destroy will be called now. a `GtkCustomFilter` function to filter items user data to pass to @match_func destroy notify for @user_data User function that is called to determine if the @item should be matched. If the filter matches the item, this function must return %TRUE. If the item should be filtered out, %FALSE must be returned. %TRUE to keep the item around The item to be matched user data `GtkCustomLayout` uses closures for size negotiation. A `GtkCustomLayout `uses closures matching to the old `GtkWidget` virtual functions for size negotiation, as a convenience API to ease the porting towards the corresponding `GtkLayoutManager virtual functions. Creates a new legacy layout manager. Legacy layout managers map to the old `GtkWidget` size negotiation virtual functions, and are meant to be used during the transition from layout containers to layout manager delegates. the newly created `GtkCustomLayout` a function to retrieve the `GtkSizeRequestMode` of the widget using the layout; the default request mode is %GTK_SIZE_REQUEST_CONSTANT_SIZE a function to measure the widget using the layout manager a function to allocate the children of the widget using the layout manager A function to be used by `GtkCustomLayout` to measure a widget. the widget to be measured the direction to be measured the size to be measured for the measured minimum size of the widget the measured natural size of the widget the measured minimum baseline of the widget the measured natural baseline of the widget Queries a widget for its preferred size request mode. the size request mode the widget to be queried `GtkCustomSorter` is a `GtkSorter` implementation that sorts via a callback function. Creates a new `GtkSorter` that works by calling @sort_func to compare items. If @sort_func is %NULL, all items are considered equal. a new `GtkCustomSorter` the `GCompareDataFunc` to use for sorting user data to pass to @sort_func destroy notify for @user_data Sets (or unsets) the function used for sorting items. If @sort_func is %NULL, all items are considered equal. If the sort func changes its sorting behavior, gtk_sorter_changed() needs to be called. If a previous function was set, its @user_destroy will be called now. a `GtkCustomSorter` function to sort items user data to pass to @match_func destroy notify for @user_data Whether the `type` debug flag is set. type to check Flags to use with gtk_set_debug_flags(). Settings these flags causes GTK to print out different types of debugging information. Some of these flags are only available when GTK has been configured with `-Ddebug=true`. Information about GtkTextView Information about GtkTreeView Information about keyboard shortcuts Information about modules and extensions Information about size allocation Information about icon themes Information about printing Trace GtkBuilder operation Information about size requests Disable the style property cache Open the GTK inspector Information about actions and menu models Information from layout managers Include debug render nodes in the generated snapshots Information from the constraints solver Log unused GtkBuilder objects Information about accessibility state changes Information about icon fallback. Inverts the default text-direction. Information about deprecated CSS features. Passed to various keybinding signals for deleting text. Delete characters. Delete only the portion of the word to the left/right of cursor if we’re in the middle of a word. Delete words. Delete display-lines. Display-lines refers to the visible lines, with respect to the current line breaks. As opposed to paragraphs, which are defined by line breaks in the input. Delete only the portion of the display-line to the left/right of cursor. Delete to the end of the paragraph. Like C-k in Emacs (or its reverse). Delete entire line. Like C-k in pico. Delete only whitespace. Like M-\ in Emacs. Dialogs are a convenient way to prompt the user for a small amount of input.  Typical uses are to display a message, ask a question, or anything else that does not require extensive effort on the user’s part. The main area of a `GtkDialog` is called the "content area", and is yours to populate with widgets such a `GtkLabel` or `GtkEntry`, to present your information, questions, or tasks to the user. In addition, dialogs allow you to add "action widgets". Most commonly, action widgets are buttons. Depending on the platform, action widgets may be presented in the header bar at the top of the window, or at the bottom of the window. To add action widgets, create your `GtkDialog` using [ctor@Gtk.Dialog.new_with_buttons], or use [method@Gtk.Dialog.add_button], [method@Gtk.Dialog.add_buttons], or [method@Gtk.Dialog.add_action_widget]. `GtkDialogs` uses some heuristics to decide whether to add a close button to the window decorations. If any of the action buttons use the response ID %GTK_RESPONSE_CLOSE or %GTK_RESPONSE_CANCEL, the close button is omitted. Clicking a button that was added as an action widget will emit the [signal@Gtk.Dialog::response] signal with a response ID that you specified. GTK will never assign a meaning to positive response IDs; these are entirely user-defined. But for convenience, you can use the response IDs in the [enum@Gtk.ResponseType] enumeration (these all have values less than zero). If a dialog receives a delete event, the [signal@Gtk.Dialog::response] signal will be emitted with the %GTK_RESPONSE_DELETE_EVENT response ID. Dialogs are created with a call to [ctor@Gtk.Dialog.new] or [ctor@Gtk.Dialog.new_with_buttons]. The latter is recommended; it allows you to set the dialog title, some convenient flags, and add buttons. A “modal” dialog (that is, one which freezes the rest of the application from user input), can be created by calling [method@Gtk.Window.set_modal] on the dialog. When using [ctor@Gtk.Dialog.new_with_buttons], you can also pass the %GTK_DIALOG_MODAL flag to make a dialog modal. For the simple dialog in the following example, a [class@Gtk.MessageDialog] would save some effort. But you’d need to create the dialog contents manually if you had more than a simple message in the dialog. An example for simple `GtkDialog` usage: ```c // Function to open a dialog box with a message void quick_message (GtkWindow *parent, char *message) { GtkWidget *dialog, *label, *content_area; GtkDialogFlags flags; // Create the widgets flags = GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_dialog_new_with_buttons ("Message", parent, flags, _("_OK"), GTK_RESPONSE_NONE, NULL); content_area = gtk_dialog_get_content_area (GTK_DIALOG (dialog)); label = gtk_label_new (message); // Ensure that the dialog box is destroyed when the user responds g_signal_connect_swapped (dialog, "response", G_CALLBACK (gtk_window_destroy), dialog); // Add the label, and show everything we’ve added gtk_box_append (GTK_BOX (content_area), label); gtk_widget_show (dialog); } ``` # GtkDialog as GtkBuildable The `GtkDialog` implementation of the `GtkBuildable` interface exposes the @content_area as an internal child with the name “content_area”. `GtkDialog` supports a custom `<action-widgets>` element, which can contain multiple `<action-widget>` elements. The “response” attribute specifies a numeric response, and the content of the element is the id of widget (which should be a child of the dialogs @action_area). To mark a response as default, set the “default” attribute of the `<action-widget>` element to true. `GtkDialog` supports adding action widgets by specifying “action” as the “type” attribute of a `<child>` element. The widget will be added either to the action area or the headerbar of the dialog, depending on the “use-header-bar” property. The response id has to be associated with the action widget using the `<action-widgets>` element. An example of a `GtkDialog` UI definition fragment: ```xml <object class="GtkDialog" id="dialog1"> <child type="action"> <object class="GtkButton" id="button_cancel"/> </child> <child type="action"> <object class="GtkButton" id="button_ok"> </object> </child> <action-widgets> <action-widget response="cancel">button_cancel</action-widget> <action-widget response="ok" default="true">button_ok</action-widget> </action-widgets> </object> ``` # Accessibility `GtkDialog` uses the %GTK_ACCESSIBLE_ROLE_DIALOG role. Use [class@Gtk.Window] instead Creates a new dialog box. Widgets should not be packed into the `GtkWindow` directly, but into the @content_area and @action_area, as described above. Use [class@Gtk.Window] instead the new dialog as a `GtkWidget` Creates a new `GtkDialog` with the given title and transient parent. The @flags argument can be used to make the dialog modal, have it destroyed along with its transient parent, or make it use a headerbar. Button text/response ID pairs should be listed in pairs, with a %NULL pointer ending the list. Button text can be arbitrary text. A response ID can be any positive number, or one of the values in the [enum@Gtk.ResponseType] enumeration. If the user clicks one of these buttons, `GtkDialog` will emit the [signal@Gtk.Dialog::response] signal with the corresponding response ID. If a `GtkDialog` receives a delete event, it will emit ::response with a response ID of %GTK_RESPONSE_DELETE_EVENT. However, destroying a dialog does not emit the ::response signal; so be careful relying on ::response when using the %GTK_DIALOG_DESTROY_WITH_PARENT flag. Here’s a simple example: ```c GtkWindow *main_app_window; // Window the dialog should show up on GtkWidget *dialog; GtkDialogFlags flags = GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_dialog_new_with_buttons ("My dialog", main_app_window, flags, _("_OK"), GTK_RESPONSE_ACCEPT, _("_Cancel"), GTK_RESPONSE_REJECT, NULL); ``` Use [class@Gtk.Window] instead a new `GtkDialog` Title of the dialog Transient parent of the dialog from `GtkDialogFlags` text to go in first button response ID for first button, then additional buttons, ending with %NULL Signal emitted when the user uses a keybinding to close the dialog. Emits the ::response signal with the given response ID. Used to indicate that the user has responded to the dialog in some way. Use [class@Gtk.Window] instead a `GtkDialog` response ID Adds an activatable widget to the action area of a `GtkDialog`. GTK connects a signal handler that will emit the [signal@Gtk.Dialog::response] signal on the dialog when the widget is activated. The widget is appended to the end of the dialog’s action area. If you want to add a non-activatable widget, simply pack it into the @action_area field of the `GtkDialog` struct. Use [class@Gtk.Window] instead a `GtkDialog` an activatable widget response ID for @child Adds a button with the given text. GTK arranges things so that clicking the button will emit the [signal@Gtk.Dialog::response] signal with the given @response_id. The button is appended to the end of the dialog’s action area. The button widget is returned, but usually you don’t need it. Use [class@Gtk.Window] instead the `GtkButton` widget that was added a `GtkDialog` text of button response ID for the button Adds multiple buttons. This is the same as calling [method@Gtk.Dialog.add_button] repeatedly. The variable argument list should be %NULL-terminated as with [ctor@Gtk.Dialog.new_with_buttons]. Each button must have both text and response ID. Use [class@Gtk.Window] instead a `GtkDialog` button text response ID for first button, then more text-response_id pairs Returns the content area of @dialog. Use [class@Gtk.Window] instead the content area `GtkBox`. a `GtkDialog` Returns the header bar of @dialog. Note that the headerbar is only used by the dialog if the [property@Gtk.Dialog:use-header-bar] property is %TRUE. Use [class@Gtk.Window] instead the header bar a `GtkDialog` Gets the response id of a widget in the action area of a dialog. Use [class@Gtk.Window] instead the response id of @widget, or %GTK_RESPONSE_NONE if @widget doesn’t have a response id set. a `GtkDialog` a widget in the action area of @dialog Gets the widget button that uses the given response ID in the action area of a dialog. Use [class@Gtk.Window] instead the @widget button that uses the given @response_id a `GtkDialog` the response ID used by the @dialog widget Emits the ::response signal with the given response ID. Used to indicate that the user has responded to the dialog in some way. Use [class@Gtk.Window] instead a `GtkDialog` response ID Sets the default widget for the dialog based on the response ID. Pressing “Enter” normally activates the default widget. Use [class@Gtk.Window] instead a `GtkDialog` a response ID A convenient way to sensitize/desensitize dialog buttons. Calls `gtk_widget_set_sensitive (widget, @setting)` for each widget in the dialog’s action area with the given @response_id. Use [class@Gtk.Window] instead a `GtkDialog` a response ID %TRUE for sensitive %TRUE if the dialog 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. ## Creating a dialog with headerbar Builtin `GtkDialog` subclasses such as [class@Gtk.ColorChooserDialog] set this property according to platform conventions (using the [property@Gtk.Settings:gtk-dialogs-use-header] setting). Here is how you can achieve the same: ```c g_object_get (settings, "gtk-dialogs-use-header", &header, NULL); dialog = g_object_new (GTK_TYPE_DIALOG, header, TRUE, NULL); ``` Use [class@Gtk.Window] instead Emitted when the user uses a keybinding to close the dialog. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is the Escape key. Use [class@Gtk.Window] instead Emitted when an action widget is clicked. The signal is also emitted when the dialog receives a delete event, and when [method@Gtk.Dialog.response] is called. On a delete event, the response ID is %GTK_RESPONSE_DELETE_EVENT. Otherwise, it depends on which action widget was clicked. Use [class@Gtk.Window] instead the response ID The parent class. Signal emitted when an action widget is activated. a `GtkDialog` response ID Signal emitted when the user uses a keybinding to close the dialog. Error codes in the `GTK_DIALOG_ERROR` domain that can be returned by async dialog functions. Generic error condition for when an operation fails and no more specific code is applicable The async function call was cancelled via its `GCancellable` The operation was cancelled by the user (via a Cancel or Close button) Registers an error quark for an operation that requires a dialog if necessary. the error quark Flags used to influence dialog construction. Make the constructed dialog modal Destroy the dialog when its parent is destroyed Create dialog with actions in header bar instead of action area Focus movement types. Move forward. Move backward. Move up. Move down. Move left. Move right. `GtkDirectoryList` is a list model that wraps g_file_enumerate_children_async(). It presents a `GListModel` and fills it asynchronously with the `GFileInfo`s returned from that function. Enumeration will start automatically when the [property@Gtk.DirectoryList:file] property is set. While the `GtkDirectoryList` is being filled, the [property@Gtk.DirectoryList:loading] property will be set to %TRUE. You can listen to that property if you want to show information like a `GtkSpinner` or a "Loading..." text. If loading fails at any point, the [property@Gtk.DirectoryList:error] property will be set to give more indication about the failure. The `GFileInfo`s returned from a `GtkDirectoryList` have the "standard::file" attribute set to the `GFile` they refer to. This way you can get at the file that is referred to in the same way you would via g_file_enumerator_get_child(). This means you do not need access to the `GtkDirectoryList`, but can access the `GFile` directly from the `GFileInfo` when operating with a `GtkListView` or similar. Creates a new `GtkDirectoryList`. The `GtkDirectoryList` is querying the given @file with the given @attributes. a new `GtkDirectoryList` The attributes to query with The file to query Gets the attributes queried on the children. The queried attributes a `GtkDirectoryList` Gets the loading error, if any. If an error occurs during the loading process, the loading process will finish and this property allows querying the error that happened. This error will persist until a file is loaded again. An error being set does not mean that no files were loaded, and all successfully queried files will remain in the list. The loading error or %NULL if loading finished successfully a `GtkDirectoryList` Gets the file whose children are currently enumerated. The file whose children are enumerated a `GtkDirectoryList` Gets the IO priority set via gtk_directory_list_set_io_priority(). The IO priority. a `GtkDirectoryList` Returns whether the directory list is monitoring the directory for changes. %TRUE if the directory is monitored a `GtkDirectoryList` Returns %TRUE if the children enumeration is currently in progress. Files will be added to @self from time to time while loading is going on. The order in which are added is undefined and may change in between runs. %TRUE if @self is loading a `GtkDirectoryList` Sets the @attributes to be enumerated and starts the enumeration. If @attributes is %NULL, the list of file infos will still be created, it will just not contain any extra attributes. a `GtkDirectoryList` the attributes to enumerate Sets the @file to be enumerated and starts the enumeration. If @file is %NULL, the result will be an empty list. a `GtkDirectoryList` the `GFile` to be enumerated Sets the IO priority to use while loading directories. Setting the priority while @self is loading will reprioritize the ongoing load as soon as possible. The default IO priority is %G_PRIORITY_DEFAULT, which is higher than the GTK redraw priority. If you are loading a lot of directories in parallel, lowering it to something like %G_PRIORITY_DEFAULT_IDLE may increase responsiveness. a `GtkDirectoryList` IO priority to use Sets whether the directory list will monitor the directory for changes. If monitoring is enabled, the ::items-changed signal will be emitted when the directory contents change. When monitoring is turned on after the initial creation of the directory list, the directory is reloaded to avoid missing files that appeared between the initial loading and when monitoring was turned on. a `GtkDirectoryList` %TRUE to monitor the directory for changes The attributes to query. Error encountered while loading files. File to query. Priority used when loading. The type of items. See [method@Gio.ListModel.get_item_type]. %TRUE if files are being loaded. %TRUE if the directory is monitored for changed. The number of items. See [method@Gio.ListModel.get_n_items]. `GtkDragIcon` is a `GtkRoot` implementation for drag icons. A drag icon moves with the pointer during a Drag-and-Drop operation and is destroyed when the drag ends. To set up a drag icon and associate it with an ongoing drag operation, use [ctor@Gtk.DragIcon.get_for_drag] to get the icon for a drag. You can then use it like any other widget and use [method@Gtk.DragIcon.set_child] to set whatever widget should be used for the drag icon. Keep in mind that drag icons do not allow user input. Gets the `GtkDragIcon` in use with @drag. If no drag icon exists yet, a new one will be created and shown. the `GtkDragIcon` a `GdkDrag` Creates a widget that can be used as a drag icon for the given @value. Supported types include strings, `GdkRGBA` and `GtkTextBuffer`. If GTK does not know how to create a widget for a given value, it will return %NULL. This method is used to set the default drag icon on drag-and-drop operations started by `GtkDragSource`, so you don't need to set a drag icon using this function there. A new `GtkWidget` for displaying @value as a drag icon. a `GValue` Creates a `GtkDragIcon` that shows @paintable, and associates it with the drag operation. The hotspot position on the paintable is aligned with the hotspot of the cursor. a `GdkDrag` a `GdkPaintable` to display X coordinate of the hotspot Y coordinate of the hotspot Gets the widget currently used as drag icon. The drag icon a `GtkDragIcon` Sets the widget to display as the drag icon. a `GtkDragIcon` a `GtkWidget` The widget to display as drag icon. `GtkDragSource` is an event controller to initiate Drag-And-Drop operations. `GtkDragSource` can be set up with the necessary ingredients for a DND operation ahead of time. This includes the source for the data that is being transferred, in the form of a [class@Gdk.ContentProvider], the desired action, and the icon to use during the drag operation. After setting it up, the drag source must be added to a widget as an event controller, using [method@Gtk.Widget.add_controller]. ```c static void my_widget_init (MyWidget *self) { GtkDragSource *drag_source = gtk_drag_source_new (); g_signal_connect (drag_source, "prepare", G_CALLBACK (on_drag_prepare), self); g_signal_connect (drag_source, "drag-begin", G_CALLBACK (on_drag_begin), self); gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (drag_source)); } ``` Setting up the content provider and icon ahead of time only makes sense when the data does not change. More commonly, you will want to set them up just in time. To do so, `GtkDragSource` has [signal@Gtk.DragSource::prepare] and [signal@Gtk.DragSource::drag-begin] signals. The ::prepare signal is emitted before a drag is started, and can be used to set the content provider and actions that the drag should be started with. ```c static GdkContentProvider * on_drag_prepare (GtkDragSource *source, double x, double y, MyWidget *self) { // This widget supports two types of content: GFile objects // and GdkPixbuf objects; GTK will handle the serialization // of these types automatically GFile *file = my_widget_get_file (self); GdkPixbuf *pixbuf = my_widget_get_pixbuf (self); return gdk_content_provider_new_union ((GdkContentProvider *[2]) { gdk_content_provider_new_typed (G_TYPE_FILE, file), gdk_content_provider_new_typed (GDK_TYPE_PIXBUF, pixbuf), }, 2); } ``` The ::drag-begin signal is emitted after the `GdkDrag` object has been created, and can be used to set up the drag icon. ```c static void on_drag_begin (GtkDragSource *source, GdkDrag *drag, MyWidget *self) { // Set the widget as the drag icon GdkPaintable *paintable = gtk_widget_paintable_new (GTK_WIDGET (self)); gtk_drag_source_set_icon (source, paintable, 0, 0); g_object_unref (paintable); } ``` During the DND operation, `GtkDragSource` emits signals that can be used to obtain updates about the status of the operation, but it is not normally necessary to connect to any signals, except for one case: when the supported actions include %GDK_ACTION_MOVE, you need to listen for the [signal@Gtk.DragSource::drag-end] signal and delete the data after it has been transferred. Creates a new `GtkDragSource` object. the new `GtkDragSource` Cancels a currently ongoing drag operation. a `GtkDragSource` Gets the actions that are currently set on the `GtkDragSource`. the actions set on @source a `GtkDragSource` Gets the current content provider of a `GtkDragSource`. the `GdkContentProvider` of @source a `GtkDragSource` Returns the underlying `GdkDrag` object for an ongoing drag. the `GdkDrag` of the current drag operation a `GtkDragSource` Sets the actions on the `GtkDragSource`. During a DND operation, the actions are offered to potential drop targets. If @actions include %GDK_ACTION_MOVE, you need to listen to the [signal@Gtk.DragSource::drag-end] signal and handle @delete_data being %TRUE. This function can be called before a drag is started, or in a handler for the [signal@Gtk.DragSource::prepare] signal. a `GtkDragSource` the actions to offer Sets a content provider on a `GtkDragSource`. When the data is requested in the cause of a DND operation, it will be obtained from the content provider. This function can be called before a drag is started, or in a handler for the [signal@Gtk.DragSource::prepare] signal. You may consider setting the content provider back to %NULL in a [signal@Gtk.DragSource::drag-end] signal handler. a `GtkDragSource` a `GdkContentProvider` Sets a paintable to use as icon during DND operations. The hotspot coordinates determine the point on the icon that gets aligned with the hotspot of the cursor. If @paintable is %NULL, a default icon is used. This function can be called before a drag is started, or in a [signal@Gtk.DragSource::prepare] or [signal@Gtk.DragSource::drag-begin] signal handler. a `GtkDragSource` the `GdkPaintable` to use as icon the hotspot X coordinate on the icon the hotspot Y coordinate on the icon The actions that are supported by drag operations from the source. Note that you must handle the [signal@Gtk.DragSource::drag-end] signal if the actions include %GDK_ACTION_MOVE. The data that is offered by drag operations from this source. Emitted on the drag source when a drag is started. It can be used to e.g. set a custom drag icon with [method@Gtk.DragSource.set_icon]. the `GdkDrag` object Emitted on the drag source when a drag has failed. The signal handler may handle a failed drag operation based on the type of error. It should return %TRUE if the failure has been handled and the default "drag operation failed" animation should not be shown. %TRUE if the failed drag operation has been already handled the `GdkDrag` object information on why the drag failed Emitted on the drag source when a drag is finished. A typical reason to connect to this signal is to undo things done in [signal@Gtk.DragSource::prepare] or [signal@Gtk.DragSource::drag-begin] handlers. the `GdkDrag` object %TRUE if the drag was performing %GDK_ACTION_MOVE, and the data should be deleted Emitted when a drag is about to be initiated. It returns the `GdkContentProvider` to use for the drag that is about to start. The default handler for this signal returns the value of the [property@Gtk.DragSource:content] property, so if you set up that property ahead of time, you don't need to connect to this signal. a `GdkContentProvider` the X coordinate of the drag starting point the Y coordinate of the drag starting point `GtkDrawingArea` is a widget that allows drawing with cairo.  It’s essentially a blank widget; you can draw on it. After creating a drawing area, the application may want to connect to: - The [signal@Gtk.Widget::realize] signal to take any necessary actions when the widget is instantiated on a particular display. (Create GDK resources in response to this signal.) - The [signal@Gtk.DrawingArea::resize] signal to take any necessary actions when the widget changes size. - Call [method@Gtk.DrawingArea.set_draw_func] to handle redrawing the contents of the widget. The following code portion demonstrates using a drawing area to display a circle in the normal widget foreground color. ## Simple GtkDrawingArea usage ```c static void draw_function (GtkDrawingArea *area, cairo_t *cr, int width, int height, gpointer data) { GdkRGBA color; cairo_arc (cr, width / 2.0, height / 2.0, MIN (width, height) / 2.0, 0, 2 * G_PI); gtk_widget_get_color (GTK_WIDGET (area), &color); gdk_cairo_set_source_rgba (cr, &color); cairo_fill (cr); } int main (int argc, char **argv) { gtk_init (); GtkWidget *area = gtk_drawing_area_new (); gtk_drawing_area_set_content_width (GTK_DRAWING_AREA (area), 100); gtk_drawing_area_set_content_height (GTK_DRAWING_AREA (area), 100); gtk_drawing_area_set_draw_func (GTK_DRAWING_AREA (area), draw_function, NULL, NULL); return 0; } ``` The draw function is normally called when a drawing area first comes onscreen, or when it’s covered by another window and then uncovered. You can also force a redraw by adding to the “damage region” of the drawing area’s window using [method@Gtk.Widget.queue_draw]. This will cause the drawing area to call the draw function again. The available routines for drawing are documented in the [Cairo documentation](https://www.cairographics.org/manual/); GDK offers additional API to integrate with Cairo, like [func@Gdk.cairo_set_source_rgba] or [func@Gdk.cairo_set_source_pixbuf]. To receive mouse events on a drawing area, you will need to use event controllers. To receive keyboard events, you will need to set the “can-focus” property on the drawing area, and you should probably draw some user-visible indication that the drawing area is focused. If you need more complex control over your widget, you should consider creating your own `GtkWidget` subclass. Creates a new drawing area. a new `GtkDrawingArea` Retrieves the content height of the `GtkDrawingArea`. The height requested for content of the drawing area a `GtkDrawingArea` Retrieves the content width of the `GtkDrawingArea`. The width requested for content of the drawing area a `GtkDrawingArea` Sets the desired height of the contents of the drawing area. Note that because widgets may be allocated larger sizes than they requested, it is possible that the actual height passed to your draw function is larger than the height set here. You can use [method@Gtk.Widget.set_valign] to avoid that. If the height is set to 0 (the default), the drawing area may disappear. a `GtkDrawingArea` the height of contents Sets the desired width of the contents of the drawing area. Note that because widgets may be allocated larger sizes than they requested, it is possible that the actual width passed to your draw function is larger than the width set here. You can use [method@Gtk.Widget.set_halign] to avoid that. If the width is set to 0 (the default), the drawing area may disappear. a `GtkDrawingArea` the width of contents Setting a draw function is the main thing you want to do when using a drawing area. The draw function is called whenever GTK needs to draw the contents of the drawing area to the screen. The draw function will be called during the drawing stage of GTK. In the drawing stage it is not allowed to change properties of any GTK widgets or call any functions that would cause any properties to be changed. You should restrict yourself exclusively to drawing your contents in the draw function. If what you are drawing does change, call [method@Gtk.Widget.queue_draw] on the drawing area. This will cause a redraw and will call @draw_func again. a `GtkDrawingArea` callback that lets you draw the drawing area's contents user data passed to @draw_func destroy notifier for @user_data The content height. The content width. Emitted once when the widget is realized, and then each time the widget is changed while realized. This is useful in order to keep state up to date with the widget size, like for instance a backing surface. the width of the viewport the height of the viewport Whenever @drawing_area needs to redraw, this function will be called. This function should exclusively redraw the contents of the drawing area and must not call any widget functions that cause changes. the `GtkDrawingArea` to redraw the context to draw to the actual width of the contents. This value will be at least as wide as GtkDrawingArea:width. the actual height of the contents. This value will be at least as wide as GtkDrawingArea:height. user data `GtkDropControllerMotion` is an event controller tracking the pointer during Drag-and-Drop operations. It is modeled after [class@Gtk.EventControllerMotion] so if you have used that, this should feel really familiar. This controller is not able to accept drops, use [class@Gtk.DropTarget] for that purpose. Creates a new event controller that will handle pointer motion events during drag and drop. a new `GtkDropControllerMotion` Returns if a Drag-and-Drop operation is within the widget @self or one of its children. %TRUE if a dragging pointer is within @self or one of its children. a `GtkDropControllerMotion` Returns the `GdkDrop` of a current Drag-and-Drop operation over the widget of @self. The `GdkDrop` currently happening within @self a `GtkDropControllerMotion` Returns if a Drag-and-Drop operation is within the widget @self, not one of its children. %TRUE if a dragging pointer is within @self but not one of its children a `GtkDropControllerMotion` Whether the pointer of a Drag-and-Drop operation is in the controller's widget or a descendant. See also [property@Gtk.DropControllerMotion:is-pointer]. When handling crossing events, this property is updated before [signal@Gtk.DropControllerMotion::enter], but after [signal@Gtk.DropControllerMotion::leave] is emitted. The ongoing drop operation over the controller's widget or its descendant. If no drop operation is going on, this property returns %NULL. The event controller should not modify the @drop, but it might want to query its properties. When handling crossing events, this property is updated before [signal@Gtk.DropControllerMotion::enter], but after [signal@Gtk.DropControllerMotion::leave] is emitted. Whether the pointer is in the controllers widget itself, as opposed to in a descendent widget. See also [property@Gtk.DropControllerMotion:contains-pointer]. When handling crossing events, this property is updated before [signal@Gtk.DropControllerMotion::enter], but after [signal@Gtk.DropControllerMotion::leave] is emitted. Signals that the pointer has entered the widget. coordinates of pointer location coordinates of pointer location Signals that the pointer has left the widget. Emitted when the pointer moves inside the widget. the x coordinate the y coordinate `GtkDropDown` is a widget that allows the user to choose an item from a list of options.  The `GtkDropDown` displays the [selected][property@Gtk.DropDown:selected] choice. The options are given to `GtkDropDown` in the form of `GListModel` and how the individual options are represented is determined by a [class@Gtk.ListItemFactory]. The default factory displays simple strings, and adds a checkmark to the selected item in the popup. To set your own factory, use [method@Gtk.DropDown.set_factory]. It is possible to use a separate factory for the items in the popup, with [method@Gtk.DropDown.set_list_factory]. `GtkDropDown` knows how to obtain strings from the items in a [class@Gtk.StringList]; for other models, you have to provide an expression to find the strings via [method@Gtk.DropDown.set_expression]. `GtkDropDown` can optionally allow search in the popup, which is useful if the list of options is long. To enable the search entry, use [method@Gtk.DropDown.set_enable_search]. Here is a UI definition example for `GtkDropDown` with a simple model: ```xml <object class="GtkDropDown"> <property name="model"> <object class="GtkStringList"> <items> <item translatable="yes">Factory</item> <item translatable="yes">Home</item> <item translatable="yes">Subway</item> </items> </object> </property> </object> ``` If a `GtkDropDown` is created in this manner, or with [ctor@Gtk.DropDown.new_from_strings], for instance, the object returned from [method@Gtk.DropDown.get_selected_item] will be a [class@Gtk.StringObject]. To learn more about the list widget framework, see the [overview](section-list-widget.html). ## CSS nodes `GtkDropDown` has a single CSS node with name dropdown, with the button and popover nodes as children. ## Accessibility `GtkDropDown` uses the %GTK_ACCESSIBLE_ROLE_COMBO_BOX role. Creates a new `GtkDropDown`. You may want to call [method@Gtk.DropDown.set_factory] to set up a way to map its items to widgets. a new `GtkDropDown` the model to use the expression to use Creates a new `GtkDropDown` that is populated with the strings. a new `GtkDropDown` The strings to put in the dropdown Returns whether search is enabled. %TRUE if the popup includes a search entry a `GtkDropDown` Gets the expression set that is used to obtain strings from items. See [method@Gtk.DropDown.set_expression]. a `GtkExpression` a `GtkDropDown` Gets the factory that's currently used to populate list items. The factory returned by this function is always used for the item in the button. It is also used for items in the popup if [property@Gtk.DropDown:list-factory] is not set. The factory in use a `GtkDropDown` Gets the factory that's currently used to create header widgets for the popup. The factory in use a `GtkDropDown` Gets the factory that's currently used to populate list items in the popup. The factory in use a `GtkDropDown` Gets the model that provides the displayed items. The model in use a `GtkDropDown` Returns the match mode that the search filter is using. the match mode of the search filter a `GtkDropDown` Gets the position of the selected item. the position of the selected item, or %GTK_INVALID_LIST_POSITION if not item is selected a `GtkDropDown` Gets the selected item. If no item is selected, %NULL is returned. The selected item a `GtkDropDown` Returns whether to show an arrow within the widget. %TRUE if an arrow will be shown. a `GtkDropDown` Sets whether a search entry will be shown in the popup that allows to search for items in the list. Note that [property@Gtk.DropDown:expression] must be set for search to work. a `GtkDropDown` whether to enable search Sets the expression that gets evaluated to obtain strings from items. This is used for search in the popup. The expression must have a value type of %G_TYPE_STRING. a `GtkDropDown` a `GtkExpression` Sets the `GtkListItemFactory` to use for populating list items. a `GtkDropDown` the factory to use Sets the `GtkListItemFactory` to use for creating header widgets for the popup. a `GtkDropDown` the factory to use Sets the `GtkListItemFactory` to use for populating list items in the popup. a `GtkDropDown` the factory to use Sets the `GListModel` to use. a `GtkDropDown` the model to use Sets the match mode for the search filter. a `GtkDropDown` the new match mode Selects the item at the given position. a `GtkDropDown` the position of the item to select, or %GTK_INVALID_LIST_POSITION Sets whether an arrow will be displayed within the widget. a `GtkDropDown` whether to show an arrow within the widget Whether to show a search entry in the popup. Note that search requires [property@Gtk.DropDown:expression] to be set. An expression to evaluate to obtain strings to match against the search term. See [property@Gtk.DropDown:enable-search] for how to enable search. If [property@Gtk.DropDown:factory] is not set, the expression is also used to bind strings to labels produced by a default factory. Factory for populating list items. The factory for creating header widgets for the popup. The factory for populating list items in the popup. If this is not set, [property@Gtk.DropDown:factory] is used. Model for the displayed items. The match mode for the search filter. The position of the selected item. If no item is selected, the property has the value %GTK_INVALID_LIST_POSITION. The selected item. Whether to show an arrow within the GtkDropDown widget. Emitted to when the drop down is activated. The `::activate` signal on `GtkDropDown` is an action signal and emitting it causes the drop down to pop up its dropdown. `GtkDropTarget` is an event controller to receive Drag-and-Drop operations. The most basic way to use a `GtkDropTarget` to receive drops on a widget is to create it via [ctor@Gtk.DropTarget.new], passing in the `GType` of the data you want to receive and connect to the [signal@Gtk.DropTarget::drop] signal to receive the data: ```c static gboolean on_drop (GtkDropTarget *target, const GValue *value, double x, double y, gpointer data) { MyWidget *self = data; // Call the appropriate setter depending on the type of data // that we received if (G_VALUE_HOLDS (value, G_TYPE_FILE)) my_widget_set_file (self, g_value_get_object (value)); else if (G_VALUE_HOLDS (value, GDK_TYPE_PIXBUF)) my_widget_set_pixbuf (self, g_value_get_object (value)); else return FALSE; return TRUE; } static void my_widget_init (MyWidget *self) { GtkDropTarget *target = gtk_drop_target_new (G_TYPE_INVALID, GDK_ACTION_COPY); // This widget accepts two types of drop types: GFile objects // and GdkPixbuf objects gtk_drop_target_set_gtypes (target, (GType [2]) { G_TYPE_FILE, GDK_TYPE_PIXBUF, }, 2); g_signal_connect (target, "drop", G_CALLBACK (on_drop), self); gtk_widget_add_controller (GTK_WIDGET (self), GTK_EVENT_CONTROLLER (target)); } ``` `GtkDropTarget` supports more options, such as: * rejecting potential drops via the [signal@Gtk.DropTarget::accept] signal and the [method@Gtk.DropTarget.reject] function to let other drop targets handle the drop * tracking an ongoing drag operation before the drop via the [signal@Gtk.DropTarget::enter], [signal@Gtk.DropTarget::motion] and [signal@Gtk.DropTarget::leave] signals * configuring how to receive data by setting the [property@Gtk.DropTarget:preload] property and listening for its availability via the [property@Gtk.DropTarget:value] property However, `GtkDropTarget` is ultimately modeled in a synchronous way and only supports data transferred via `GType`. If you want full control over an ongoing drop, the [class@Gtk.DropTargetAsync] object gives you this ability. While a pointer is dragged over the drop target's widget and the drop has not been rejected, that widget will receive the %GTK_STATE_FLAG_DROP_ACTIVE state, which can be used to style the widget. If you are not interested in receiving the drop, but just want to update UI state during a Drag-and-Drop operation (e.g. switching tabs), you can use [class@Gtk.DropControllerMotion]. Creates a new `GtkDropTarget` object. If the drop target should support more than 1 type, pass %G_TYPE_INVALID for @type and then call [method@Gtk.DropTarget.set_gtypes]. the new `GtkDropTarget` The supported type or %G_TYPE_INVALID the supported actions Gets the actions that this drop target supports. the actions that this drop target supports a `GtkDropTarget` Gets the currently handled drop operation. If no drop operation is going on, %NULL is returned. The current drop a `GtkDropTarget` Gets the currently handled drop operation. If no drop operation is going on, %NULL is returned. Use [method@Gtk.DropTarget.get_current_drop] instead The current drop a `GtkDropTarget` Gets the data formats that this drop target accepts. If the result is %NULL, all formats are expected to be supported. the supported data formats a `GtkDropTarget` Gets the list of supported `GType`s that can be dropped on the target. If no types have been set, `NULL` will be returned. the `G_TYPE_INVALID`-terminated array of types included in formats a `GtkDropTarget` the number of `GType`s contained in the return value Gets whether data should be preloaded on hover. %TRUE if drop data should be preloaded a `GtkDropTarget` Gets the current drop data, as a `GValue`. The current drop data a `GtkDropTarget` Rejects the ongoing drop operation. If no drop operation is ongoing, i.e when [property@Gtk.DropTarget:current-drop] is %NULL, this function does nothing. This function should be used when delaying the decision on whether to accept a drag or not until after reading the data. a `GtkDropTarget` Sets the actions that this drop target supports. a `GtkDropTarget` the supported actions Sets the supported `GType`s for this drop target. a `GtkDropTarget` all supported `GType`s that can be dropped on the target number of @types Sets whether data should be preloaded on hover. a `GtkDropTarget` %TRUE to preload drop data The `GdkDragActions` that this drop target supports. The `GdkDrop` that is currently being performed. The `GdkDrop` that is currently being performed. Use [property@Gtk.DropTarget:current-drop] instead The `GdkContentFormats` that determine the supported data formats. Whether the drop data should be preloaded when the pointer is only hovering over the widget but has not been released. Setting this property allows finer grained reaction to an ongoing drop at the cost of loading more data. The default value for this property is %FALSE to avoid downloading huge amounts of data by accident. For example, if somebody drags a full document of gigabytes of text from a text editor across a widget with a preloading drop target, this data will be downloaded, even if the data is ultimately dropped elsewhere. For a lot of data formats, the amount of data is very small (like %GDK_TYPE_RGBA), so enabling this property does not hurt at all. And for local-only Drag-and-Drop operations, no data transfer is done, so enabling it there is free. The value for this drop operation. This is %NULL if the data has not been loaded yet or no drop operation is going on. Data may be available before the [signal@Gtk.DropTarget::drop] signal gets emitted - for example when the [property@Gtk.DropTarget:preload] property is set. You can use the ::notify signal to be notified of available data. Emitted on the drop site when a drop operation is about to begin. If the drop is not accepted, %FALSE will be returned and the drop target will ignore the drop. If %TRUE is returned, the drop is accepted for now but may be rejected later via a call to [method@Gtk.DropTarget.reject] or ultimately by returning %FALSE from a [signal@Gtk.DropTarget::drop] handler. The default handler for this signal decides whether to accept the drop based on the formats provided by the @drop. If the decision whether the drop will be accepted or rejected depends on the data, this function should return %TRUE, the [property@Gtk.DropTarget:preload] property should be set and the value should be inspected via the ::notify:value signal, calling [method@Gtk.DropTarget.reject] if required. %TRUE if @drop is accepted the `GdkDrop` Emitted on the drop site when the user drops the data onto the widget. The signal handler must determine whether the pointer position is in a drop zone or not. If it is not in a drop zone, it returns %FALSE and no further processing is necessary. Otherwise, the handler returns %TRUE. In this case, this handler will accept the drop. The handler is responsible for using the given @value and performing the drop operation. whether the drop was accepted at the given pointer position the `GValue` being dropped the x coordinate of the current pointer position the y coordinate of the current pointer position Emitted on the drop site when the pointer enters the widget. It can be used to set up custom highlighting. Preferred action for this drag operation or 0 if dropping is not supported at the current @x,@y location. the x coordinate of the current pointer position the y coordinate of the current pointer position Emitted on the drop site when the pointer leaves the widget. Its main purpose it to undo things done in [signal@Gtk.DropTarget::enter]. Emitted while the pointer is moving over the drop target. Preferred action for this drag operation or 0 if dropping is not supported at the current @x,@y location. the x coordinate of the current pointer position the y coordinate of the current pointer position `GtkDropTargetAsync` is an event controller to receive Drag-and-Drop operations, asynchronously. It is the more complete but also more complex method of handling drop operations compared to [class@Gtk.DropTarget], and you should only use it if `GtkDropTarget` doesn't provide all the features you need. To use a `GtkDropTargetAsync` to receive drops on a widget, you create a `GtkDropTargetAsync` object, configure which data formats and actions you support, connect to its signals, and then attach it to the widget with [method@Gtk.Widget.add_controller]. During a drag operation, the first signal that a `GtkDropTargetAsync` emits is [signal@Gtk.DropTargetAsync::accept], which is meant to determine whether the target is a possible drop site for the ongoing drop. The default handler for the ::accept signal accepts the drop if it finds a compatible data format and an action that is supported on both sides. If it is, and the widget becomes a target, you will receive a [signal@Gtk.DropTargetAsync::drag-enter] signal, followed by [signal@Gtk.DropTargetAsync::drag-motion] signals as the pointer moves, optionally a [signal@Gtk.DropTargetAsync::drop] signal when a drop happens, and finally a [signal@Gtk.DropTargetAsync::drag-leave] signal when the pointer moves off the widget. The ::drag-enter and ::drag-motion handler return a `GdkDragAction` to update the status of the ongoing operation. The ::drop handler should decide if it ultimately accepts the drop and if it does, it should initiate the data transfer and finish the operation by calling [method@Gdk.Drop.finish]. Between the ::drag-enter and ::drag-leave signals the widget is a current drop target, and will receive the %GTK_STATE_FLAG_DROP_ACTIVE state, which can be used by themes to style the widget as a drop target. Creates a new `GtkDropTargetAsync` object. the new `GtkDropTargetAsync` the supported data formats the supported actions Gets the actions that this drop target supports. the actions that this drop target supports a `GtkDropTargetAsync` Gets the data formats that this drop target accepts. If the result is %NULL, all formats are expected to be supported. the supported data formats a `GtkDropTargetAsync` Sets the @drop as not accepted on this drag site. This function should be used when delaying the decision on whether to accept a drag or not until after reading the data. a `GtkDropTargetAsync` the `GdkDrop` of an ongoing drag operation Sets the actions that this drop target supports. a `GtkDropTargetAsync` the supported actions Sets the data formats that this drop target will accept. a `GtkDropTargetAsync` the supported data formats or %NULL for any format The `GdkDragActions` that this drop target supports. The `GdkContentFormats` that determines the supported data formats. Emitted on the drop site when a drop operation is about to begin. If the drop is not accepted, %FALSE will be returned and the drop target will ignore the drop. If %TRUE is returned, the drop is accepted for now but may be rejected later via a call to [method@Gtk.DropTargetAsync.reject_drop] or ultimately by returning %FALSE from a [signal@Gtk.DropTargetAsync::drop] handler. The default handler for this signal decides whether to accept the drop based on the formats provided by the @drop. If the decision whether the drop will be accepted or rejected needs further processing, such as inspecting the data, this function should return %TRUE and proceed as is @drop was accepted and if it decides to reject the drop later, it should call [method@Gtk.DropTargetAsync.reject_drop]. %TRUE if @drop is accepted the `GdkDrop` Emitted on the drop site when the pointer enters the widget. It can be used to set up custom highlighting. Preferred action for this drag operation. the `GdkDrop` the x coordinate of the current pointer position the y coordinate of the current pointer position Emitted on the drop site when the pointer leaves the widget. Its main purpose it to undo things done in `GtkDropTargetAsync`::drag-enter. the `GdkDrop` Emitted while the pointer is moving over the drop target. Preferred action for this drag operation. the `GdkDrop` the x coordinate of the current pointer position the y coordinate of the current pointer position Emitted on the drop site when the user drops the data onto the widget. The signal handler must determine whether the pointer position is in a drop zone or not. If it is not in a drop zone, it returns %FALSE and no further processing is necessary. Otherwise, the handler returns %TRUE. In this case, this handler will accept the drop. The handler must ensure that [method@Gdk.Drop.finish] is called to let the source know that the drop is done. The call to [method@Gdk.Drop.finish] must only be done when all data has been received. To receive the data, use one of the read functions provided by [class@Gdk.Drop] such as [method@Gdk.Drop.read_async] or [method@Gdk.Drop.read_value_async]. whether the drop is accepted at the given pointer position the `GdkDrop` the x coordinate of the current pointer position the y coordinate of the current pointer position `GtkEditable` is an interface for text editing widgets. Typical examples of editable widgets are [class@Gtk.Entry] and [class@Gtk.SpinButton]. It contains functions for generically manipulating an editable widget, a large number of action signals used for key bindings, and several signals that an application can connect to modify the behavior of a widget. As an example of the latter usage, by connecting the following handler to [signal@Gtk.Editable::insert-text], an application can convert all entry into a widget into uppercase. ## Forcing entry to uppercase. ```c #include <ctype.h> void insert_text_handler (GtkEditable *editable, const char *text, int length, int *position, gpointer data) { char *result = g_utf8_strup (text, length); g_signal_handlers_block_by_func (editable, (gpointer) insert_text_handler, data); gtk_editable_insert_text (editable, result, length, position); g_signal_handlers_unblock_by_func (editable, (gpointer) insert_text_handler, data); g_signal_stop_emission_by_name (editable, "insert_text"); g_free (result); } ``` ## Implementing GtkEditable The most likely scenario for implementing `GtkEditable` on your own widget is that you will embed a `GtkText` inside a complex widget, and want to delegate the editable functionality to that text widget. `GtkEditable` provides some utility functions to make this easy. In your class_init function, call [func@Gtk.Editable.install_properties], passing the first available property ID: ```c static void my_class_init (MyClass *class) { ... g_object_class_install_properties (object_class, NUM_PROPERTIES, props); gtk_editable_install_properties (object_clas, NUM_PROPERTIES); ... } ``` In your interface_init function for the `GtkEditable` interface, provide an implementation for the get_delegate vfunc that returns your text widget: ```c GtkEditable * get_editable_delegate (GtkEditable *editable) { return GTK_EDITABLE (MY_WIDGET (editable)->text_widget); } static void my_editable_init (GtkEditableInterface *iface) { iface->get_delegate = get_editable_delegate; } ``` You don't need to provide any other vfuncs. The default implementations work by forwarding to the delegate that the GtkEditableInterface.get_delegate() vfunc returns. In your instance_init function, create your text widget, and then call [method@Gtk.Editable.init_delegate]: ```c static void my_widget_init (MyWidget *self) { ... self->text_widget = gtk_text_new (); gtk_editable_init_delegate (GTK_EDITABLE (self)); ... } ``` In your dispose function, call [method@Gtk.Editable.finish_delegate] before destroying your text widget: ```c static void my_widget_dispose (GObject *object) { ... gtk_editable_finish_delegate (GTK_EDITABLE (self)); g_clear_pointer (&self->text_widget, gtk_widget_unparent); ... } ``` Finally, use [func@Gtk.Editable.delegate_set_property] in your `set_property` function (and similar for `get_property`), to set the editable properties: ```c ... if (gtk_editable_delegate_set_property (object, prop_id, value, pspec)) return; switch (prop_id) ... ``` It is important to note that if you create a `GtkEditable` that uses a delegate, the low level [signal@Gtk.Editable::insert-text] and [signal@Gtk.Editable::delete-text] signals will be propagated from the "wrapper" editable to the delegate, but they will not be propagated from the delegate to the "wrapper" editable, as they would cause an infinite recursion. If you wish to connect to the [signal@Gtk.Editable::insert-text] and [signal@Gtk.Editable::delete-text] signals, you will need to connect to them on the delegate obtained via [method@Gtk.Editable.get_delegate]. Gets a property of the `GtkEditable` delegate for @object. This is helper function that should be called in the `get_property` function of your `GtkEditable` implementation, before handling your own properties. %TRUE if the property was found a `GObject` a property ID value to set the `GParamSpec` for the property Sets a property on the `GtkEditable` delegate for @object. This is a helper function that should be called in the `set_property` function of your `GtkEditable` implementation, before handling your own properties. %TRUE if the property was found a `GObject` a property ID value to set the `GParamSpec` for the property Overrides the `GtkEditable` properties for @class. This is a helper function that should be called in class_init, after installing your own properties. Note that your class must have "text", "cursor-position", "selection-bound", "editable", "width-chars", "max-width-chars", "xalign" and "enable-undo" properties for this function to work. To handle the properties in your set_property and get_property functions, you can either use [func@Gtk.Editable.delegate_set_property] and [func@Gtk.Editable.delegate_get_property] (if you are using a delegate), or remember the @first_prop offset and add it to the values in the [enum@Gtk.EditableProperties] enumeration to get the property IDs for these properties. the number of properties that were installed a `GObjectClass` property ID to use for the first property Deletes a sequence of characters. The characters that are deleted are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters deleted are those from @start_pos to the end of the text. Note that the positions are specified in characters, not bytes. a `GtkEditable` start position end position Deletes a sequence of characters. The characters that are deleted are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters deleted are those from @start_pos to the end of the text. Note that the positions are specified in characters, not bytes. a `GtkEditable` start position end position Inserts @length bytes of @text into the contents of the widget, at position @position. Note that the position is in characters, not in bytes. The function updates @position to point after the newly inserted text. a `GtkEditable` the text to insert the length of the text in bytes, or -1 location of the position text will be inserted at Gets the `GtkEditable` that @editable is delegating its implementation to. Typically, the delegate is a [class@Gtk.Text] widget. the delegate `GtkEditable` a `GtkEditable` Retrieves the selection bound of the editable. @start_pos will be filled with the start of the selection and @end_pos with end. If no text was selected both will be identical and %FALSE will be returned. Note that positions are specified in characters, not bytes. %TRUE if there is a non-empty selection, %FALSE otherwise a `GtkEditable` location to store the starting position location to store the end position Retrieves the contents of @editable. The returned string is owned by GTK and must not be modified or freed. a pointer to the contents of the editable a `GtkEditable` Inserts @length bytes of @text into the contents of the widget, at position @position. Note that the position is in characters, not in bytes. The function updates @position to point after the newly inserted text. a `GtkEditable` the text to insert the length of the text in bytes, or -1 location of the position text will be inserted at Selects a region of text. The characters that are selected are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters selected are those characters from @start_pos to the end of the text. Note that positions are specified in characters, not bytes. a `GtkEditable` start of region end of region Retrieves the accessible platform state from the editable delegate. This is an helper function to retrieve the accessible state for `GtkEditable` interface implementations using a delegate pattern. You should call this function in your editable widget implementation of the [vfunc@Gtk.Accessible.get_platform_state] virtual function, for instance: ```c static void accessible_interface_init (GtkAccessibleInterface *iface) { iface->get_platform_state = your_editable_get_accessible_platform_state; } static gboolean your_editable_get_accessible_platform_state (GtkAccessible *accessible, GtkAccessiblePlatformState state) { return gtk_editable_delegate_get_accessible_platform_state (GTK_EDITABLE (accessible), state); } ``` Note that the widget which is the delegate *must* be a direct child of this widget, otherwise your implementation of [vfunc@Gtk.Accessible.get_platform_state] might not even be called, as the platform change will originate from the parent of the delegate, and, as a result, will not work properly. So, if you can't ensure the direct child condition, you should give the delegate the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role, or you can change your tree to allow this function to work. the accessible platform state of the delegate a `GtkEditable` implementation what kind of accessible state to retrieve Deletes the currently selected text of the editable. This call doesn’t do anything if there is no selected text. a `GtkEditable` Deletes a sequence of characters. The characters that are deleted are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters deleted are those from @start_pos to the end of the text. Note that the positions are specified in characters, not bytes. a `GtkEditable` start position end position Undoes the setup done by [method@Gtk.Editable.init_delegate]. This is a helper function that should be called from dispose, before removing the delegate object. a `GtkEditable` Gets the alignment of the editable. the alignment a `GtkEditable` Retrieves a sequence of characters. The characters that are retrieved are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters retrieved are those characters from @start_pos to the end of the text. Note that positions are specified in characters, not bytes. a pointer to the contents of the widget as a string. This string is allocated by the `GtkEditable` implementation and should be freed by the caller. a `GtkEditable` start of text end of text Gets the `GtkEditable` that @editable is delegating its implementation to. Typically, the delegate is a [class@Gtk.Text] widget. the delegate `GtkEditable` a `GtkEditable` Retrieves whether @editable is editable. %TRUE if @editable is editable. a `GtkEditable` Gets if undo/redo actions are enabled for @editable %TRUE if undo is enabled a `GtkEditable` Retrieves the desired maximum width of @editable, in characters. the maximum width of the entry, in characters a `GtkEditable` Retrieves the current position of the cursor relative to the start of the content of the editable. Note that this position is in characters, not in bytes. the cursor position a `GtkEditable` Retrieves the selection bound of the editable. @start_pos will be filled with the start of the selection and @end_pos with end. If no text was selected both will be identical and %FALSE will be returned. Note that positions are specified in characters, not bytes. %TRUE if there is a non-empty selection, %FALSE otherwise a `GtkEditable` location to store the starting position location to store the end position Retrieves the contents of @editable. The returned string is owned by GTK and must not be modified or freed. a pointer to the contents of the editable a `GtkEditable` Gets the number of characters of space reserved for the contents of the editable. number of chars to request space for, or negative if unset a `GtkEditable` Sets up a delegate for `GtkEditable`. This is assuming that the get_delegate vfunc in the `GtkEditable` interface has been set up for the @editable's type. This is a helper function that should be called in instance init, after creating the delegate object. a `GtkEditable` Inserts @length bytes of @text into the contents of the widget, at position @position. Note that the position is in characters, not in bytes. The function updates @position to point after the newly inserted text. a `GtkEditable` the text to insert the length of the text in bytes, or -1 location of the position text will be inserted at Selects a region of text. The characters that are selected are those characters at positions from @start_pos up to, but not including @end_pos. If @end_pos is negative, then the characters selected are those characters from @start_pos to the end of the text. Note that positions are specified in characters, not bytes. a `GtkEditable` start of region end of region Sets the alignment for the contents of the editable. This controls the horizontal positioning of the contents when the displayed text is shorter than the width of the editable. a `GtkEditable` The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts Determines if the user can edit the text in the editable widget. a `GtkEditable` %TRUE if the user is allowed to edit the text in the widget If enabled, changes to @editable will be saved for undo/redo actions. This results in an additional copy of text changes and are not stored in secure memory. As such, undo is forcefully disabled when [property@Gtk.Text:visibility] is set to %FALSE. a `GtkEditable` if undo/redo should be enabled Sets the desired maximum width in characters of @editable. a `GtkEditable` the new desired maximum width, in characters Sets the cursor position in the editable to the given value. The cursor is displayed before the character with the given (base 0) index in the contents of the editable. The value must be less than or equal to the number of characters in the editable. A value of -1 indicates that the position should be set after the last character of the editable. Note that @position is in characters, not in bytes. a `GtkEditable` the position of the cursor Sets the text in the editable to the given value. This is replacing the current contents. a `GtkEditable` the text to set Changes the size request of the editable to be about the right size for @n_chars characters. Note that it changes the size request, the size can still be affected by how you pack the widget into containers. If @n_chars is -1, the size reverts to the default size. a `GtkEditable` width in chars The current position of the insertion cursor in chars. Whether the entry contents can be edited. If undo/redo should be enabled for the editable. The desired maximum width of the entry, in characters. The position of the opposite end of the selection from the cursor in chars. The contents of the entry. Number of characters to leave space for in the entry. The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts. Emitted at the end of a single user-visible operation on the contents. E.g., a paste operation that replaces the contents of the selection will cause only one signal emission (even though it is implemented by first deleting the selection, then inserting the new content, and may cause multiple ::notify::text signals to be emitted). Emitted when text is deleted from the widget by the user. The default handler for this signal will normally be responsible for deleting the text, so by connecting to this signal and then stopping the signal with g_signal_stop_emission(), it is possible to modify the range of deleted text, or prevent it from being deleted entirely. The @start_pos and @end_pos parameters are interpreted as for [method@Gtk.Editable.delete_text]. the starting position the end position Emitted when text is inserted into the widget by the user. The default handler for this signal will normally be responsible for inserting the text, so by connecting to this signal and then stopping the signal with g_signal_stop_emission(), it is possible to modify the inserted text, or prevent it from being inserted entirely. the new text to insert the length of the new text, in bytes, or -1 if new_text is nul-terminated the position, in characters, at which to insert the new text. this is an in-out parameter. After the signal emission is finished, it should point after the newly inserted text. a `GtkEditable` the text to insert the length of the text in bytes, or -1 location of the position text will be inserted at a `GtkEditable` start position end position a pointer to the contents of the editable a `GtkEditable` a `GtkEditable` the text to insert the length of the text in bytes, or -1 location of the position text will be inserted at a `GtkEditable` start position end position %TRUE if there is a non-empty selection, %FALSE otherwise a `GtkEditable` location to store the starting position location to store the end position a `GtkEditable` start of region end of region the delegate `GtkEditable` a `GtkEditable` A `GtkEditableLabel` is a label that allows users to edit the text by switching to an “edit mode”.  `GtkEditableLabel` does not have API of its own, but it implements the [iface@Gtk.Editable] interface. The default bindings for activating the edit mode is to click or press the Enter key. The default bindings for leaving the edit mode are the Enter key (to save the results) or the Escape key (to cancel the editing). # Shortcuts and Gestures `GtkEditableLabel` supports the following keyboard shortcuts: - <kbd>Enter</kbd> starts editing. - <kbd>Escape</kbd> stops editing. # Actions `GtkEditableLabel` defines a set of built-in actions: - `editing.starts` switches the widget into editing mode. - `editing.stop` switches the widget out of editing mode. # CSS nodes ``` editablelabel[.editing] ╰── stack ├── label ╰── text ``` `GtkEditableLabel` has a main node with the name editablelabel. When the entry is in editing mode, it gets the .editing style class. For all the subnodes added to the text node in various situations, see [class@Gtk.Text]. Creates a new `GtkEditableLabel` widget. the new `GtkEditableLabel` the text for the label Returns whether the label is currently in “editing mode”. %TRUE if @self is currently in editing mode a `GtkEditableLabel` Switches the label into “editing mode”. a `GtkEditableLabel` Switches the label out of “editing mode”. If @commit is %TRUE, the resulting text is kept as the [property@Gtk.Editable:text] property value, otherwise the resulting text is discarded and the label will keep its previous [property@Gtk.Editable:text] property value. a `GtkEditableLabel` whether to set the edited text on the label This property is %TRUE while the widget is in edit mode. The identifiers for [iface@Gtk.Editable] properties. See [func@Gtk.Editable.install_properties] for details on how to implement the `GtkEditable` interface. the property id for [property@Gtk.Editable:text] the property id for [property@Gtk.Editable:cursor-position] the property id for [property@Gtk.Editable:selection-bound] the property id for [property@Gtk.Editable:editable] the property id for [property@Gtk.Editable:width-chars] the property id for [property@Gtk.Editable:max-width-chars] the property id for [property@Gtk.Editable:xalign] the property id for [property@Gtk.Editable:enable-undo] the number of properties The `GtkEmojiChooser` is used by text widgets such as `GtkEntry` or `GtkTextView` to let users insert Emoji characters.  `GtkEmojiChooser` emits the [signal@Gtk.EmojiChooser::emoji-picked] signal when an Emoji is selected. # Shortcuts and Gestures `GtkEmojiChooser` supports the following keyboard shortcuts: - <kbd>Ctrl</kbd>+<kbd>N</kbd> scrolls th the next section. - <kbd>Ctrl</kbd>+<kbd>P</kbd> scrolls th the previous section. # Actions `GtkEmojiChooser` defines a set of built-in actions: - `scroll.section` scrolls to the next or previous section. # CSS nodes ``` popover ├── box.emoji-searchbar │ ╰── entry.search ╰── box.emoji-toolbar ├── button.image-button.emoji-section ├── ... ╰── button.image-button.emoji-section ``` Every `GtkEmojiChooser` consists of a main node called popover. The contents of the popover are largely implementation defined and supposed to inherit general styles. The top searchbar used to search emoji and gets the .emoji-searchbar style class itself. The bottom toolbar used to switch between different emoji categories consists of buttons with the .emoji-section style class and gets the .emoji-toolbar style class itself. Creates a new `GtkEmojiChooser`. a new `GtkEmojiChooser` Emitted when the user selects an Emoji. the Unicode sequence for the picked Emoji, in UTF-8 `GtkEntry` is a single line text entry widget.  A fairly large set of key bindings are supported by default. If the entered text is longer than the allocation of the widget, the widget will scroll so that the cursor position is visible. When using an entry for passwords and other sensitive information, it can be put into “password mode” using [method@Gtk.Entry.set_visibility]. In this mode, entered text is displayed using a “invisible” character. By default, GTK picks the best invisible character that is available in the current font, but it can be changed with [method@Gtk.Entry.set_invisible_char]. `GtkEntry` has the ability to display progress or activity information behind the text. To make an entry display such information, use [method@Gtk.Entry.set_progress_fraction] or [method@Gtk.Entry.set_progress_pulse_step]. Additionally, `GtkEntry` can show icons at either side of the entry. These icons can be activatable by clicking, can be set up as drag source and can have tooltips. To add an icon, use [method@Gtk.Entry.set_icon_from_gicon] or one of the various other functions that set an icon from an icon name or a paintable. To trigger an action when the user clicks an icon, connect to the [signal@Gtk.Entry::icon-press] signal. To allow DND operations from an icon, use [method@Gtk.Entry.set_icon_drag_source]. To set a tooltip on an icon, use [method@Gtk.Entry.set_icon_tooltip_text] or the corresponding function for markup. Note that functionality or information that is only available by clicking on an icon in an entry may not be accessible at all to users which are not able to use a mouse or other pointing device. It is therefore recommended that any such functionality should also be available by other means, e.g. via the context menu of the entry. # CSS nodes ``` entry[.flat][.warning][.error] ├── text[.readonly] ├── image.left ├── image.right ╰── [progress[.pulse]] ``` `GtkEntry` has a main node with the name entry. Depending on the properties of the entry, the style classes .read-only and .flat may appear. The style classes .warning and .error may also be used with entries. When the entry shows icons, it adds subnodes with the name image and the style class .left or .right, depending on where the icon appears. When the entry shows progress, it adds a subnode with the name progress. The node has the style class .pulse when the shown progress is pulsing. For all the subnodes added to the text node in various situations, see [class@Gtk.Text]. # GtkEntry as GtkBuildable The `GtkEntry` implementation of the `GtkBuildable` interface supports a custom `<attributes>` element, which supports any number of `<attribute>` elements. The `<attribute>` element has attributes named “name“, “value“, “start“ and “end“ and allows you to specify `PangoAttribute` values for this label. An example of a UI definition fragment specifying Pango attributes: ```xml <object class="GtkEntry"> <attributes> <attribute name="weight" value="PANGO_WEIGHT_BOLD"/> <attribute name="background" value="red" start="5" end="10"/> </attributes> </object> ``` The start and end attributes specify the range of characters to which the Pango attribute applies. If start and end are not specified, the attribute is applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup embedded in the translatable content instead. # Accessibility `GtkEntry` uses the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role. Creates a new entry. a new `GtkEntry`. Creates a new entry with the specified text buffer. a new `GtkEntry` The buffer to use for the new `GtkEntry`. Class handler for the `GtkEntry::activate` signal. The default implementation activates the gtk.activate-default action. Retrieves the value set by gtk_entry_set_activates_default(). %TRUE if the entry will activate the default widget a `GtkEntry` Gets the value set by gtk_entry_set_alignment(). See also: [property@Gtk.Editable:xalign] the alignment a `GtkEntry` Gets the attribute list of the `GtkEntry`. See [method@Gtk.Entry.set_attributes]. the attribute list a `GtkEntry` Get the `GtkEntryBuffer` object which holds the text for this widget. A `GtkEntryBuffer` object. a `GtkEntry` Returns the auxiliary completion object currently in use by @entry. GtkEntryCompletion will be removed in GTK 5. The auxiliary completion object currently in use by @entry A `GtkEntry` Returns the index of the icon which is the source of the current DND operation, or -1. index of the icon which is the source of the current DND operation, or -1. a `GtkEntry` Gets the menu model set with gtk_entry_set_extra_menu(). the menu model a `GtkEntry` Gets the value set by gtk_entry_set_has_frame(). whether the entry has a beveled frame a `GtkEntry` Returns whether the icon is activatable. %TRUE if the icon is activatable. a `GtkEntry` Icon position Gets the area where entry’s icon at @icon_pos is drawn. This function is useful when drawing something to the entry in a draw callback. If the entry is not realized or has no icon at the given position, @icon_area is filled with zeros. Otherwise, @icon_area will be filled with the icon's allocation, relative to @entry's allocation. A `GtkEntry` Icon position Return location for the icon’s area Finds the icon at the given position and return its index. The position’s coordinates are relative to the @entry’s top left corner. If @x, @y doesn’t lie inside an icon, -1 is returned. This function is intended for use in a [signal@Gtk.Widget::query-tooltip] signal handler. the index of the icon at the given position, or -1 a `GtkEntry` the x coordinate of the position to find, relative to @entry the y coordinate of the position to find, relative to @entry Retrieves the `GIcon` used for the icon. %NULL will be returned if there is no icon or if the icon was set by some other method (e.g., by `GdkPaintable` or icon name). A `GIcon` A `GtkEntry` Icon position Retrieves the icon name used for the icon. %NULL is returned if there is no icon or if the icon was set by some other method (e.g., by `GdkPaintable` or gicon). An icon name A `GtkEntry` Icon position Retrieves the `GdkPaintable` used for the icon. If no `GdkPaintable` was used for the icon, %NULL is returned. A `GdkPaintable` if no icon is set for this position or the icon set is not a `GdkPaintable`. A `GtkEntry` Icon position Returns whether the icon appears sensitive or insensitive. %TRUE if the icon is sensitive. a `GtkEntry` Icon position Gets the type of representation being used by the icon to store image data. If the icon has no image data, the return value will be %GTK_IMAGE_EMPTY. image representation being used a `GtkEntry` Icon position Gets the contents of the tooltip on the icon at the specified position in @entry. the tooltip text a `GtkEntry` the icon position Gets the contents of the tooltip on the icon at the specified position in @entry. the tooltip text a `GtkEntry` the icon position Gets the input hints of this `GtkEntry`. the input hints a `GtkEntry` Gets the input purpose of the `GtkEntry`. the input purpose a `GtkEntry` Retrieves the character displayed in place of the actual text in “password mode”. the current invisible char, or 0, if the entry does not show invisible text at all. a `GtkEntry` Retrieves the maximum allowed length of the text in @entry. See [method@Gtk.Entry.set_max_length]. the maximum allowed number of characters in `GtkEntry`, or 0 if there is no maximum. a `GtkEntry` Gets whether the `GtkEntry` is in overwrite mode. whether the text is overwritten when typing. a `GtkEntry` Retrieves the text that will be displayed when @entry is empty and unfocused a pointer to the placeholder text as a string. This string points to internally allocated storage in the widget and must not be freed, modified or stored. If no placeholder text has been set, %NULL will be returned. a `GtkEntry` Returns the current fraction of the task that’s been completed. See [method@Gtk.Entry.set_progress_fraction]. a fraction from 0.0 to 1.0 a `GtkEntry` Retrieves the pulse step set with gtk_entry_set_progress_pulse_step(). a fraction from 0.0 to 1.0 a `GtkEntry` Gets the tabstops of the `GtkEntry`. See [method@Gtk.Entry.set_tabs]. the tabstops a `GtkEntry` Retrieves the current length of the text in @entry. This is equivalent to getting @entry's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.get_length] on it. the current number of characters in `GtkEntry`, or 0 if there are none. a `GtkEntry` Retrieves whether the text in @entry is visible. See [method@Gtk.Entry.set_visibility]. %TRUE if the text is currently visible a `GtkEntry` Causes @entry to have keyboard focus. It behaves like [method@Gtk.Widget.grab_focus], except that it doesn't select the contents of the entry. You only want to call this on some special entries which the user usually doesn't want to replace all text in, such as search-as-you-type entries. %TRUE if focus is now inside @self a `GtkEntry` Indicates that some progress is made, but you don’t know how much. Causes the entry’s progress indicator to enter “activity mode”, where a block bounces back and forth. Each call to gtk_entry_progress_pulse() causes the block to move by a little bit (the amount of movement per pulse is determined by [method@Gtk.Entry.set_progress_pulse_step]). a `GtkEntry` Reset the input method context of the entry if needed. This can be necessary in the case where modifying the buffer would confuse on-going input method behavior. a `GtkEntry` Sets whether pressing Enter in the @entry will activate the default widget for the window containing the entry. This usually means that the dialog containing the entry will be closed, since the default widget is usually one of the dialog buttons. a `GtkEntry` %TRUE to activate window’s default widget on Enter keypress Sets the alignment for the contents of the entry. This controls the horizontal positioning of the contents when the displayed text is shorter than the width of the entry. See also: [property@Gtk.Editable:xalign] a `GtkEntry` The horizontal alignment, from 0 (left) to 1 (right). Reversed for RTL layouts Sets a `PangoAttrList`. The attributes in the list are applied to the entry text. Since the attributes will be applied to text that changes as the user types, it makes most sense to use attributes with unlimited extent. a `GtkEntry` a `PangoAttrList` Set the `GtkEntryBuffer` object which holds the text for this widget. a `GtkEntry` a `GtkEntryBuffer` Sets @completion to be the auxiliary completion object to use with @entry. All further configuration of the completion mechanism is done on @completion using the `GtkEntryCompletion` API. Completion is disabled if @completion is set to %NULL. GtkEntryCompletion will be removed in GTK 5. A `GtkEntry` The `GtkEntryCompletion` Sets a menu model to add when constructing the context menu for @entry. a `GtkEntry` a `GMenuModel` Sets whether the entry has a beveled frame around it. a `GtkEntry` new value Sets whether the icon is activatable. A `GtkEntry` Icon position %TRUE if the icon should be activatable Sets up the icon at the given position as drag source. This makes it so that GTK will start a drag operation when the user clicks and drags the icon. a `GtkEntry` icon position a `GdkContentProvider` a bitmask of the allowed drag actions Sets the icon shown in the entry at the specified position from the current icon theme. If the icon isn’t known, a “broken image” icon will be displayed instead. If @icon is %NULL, no icon will be shown in the specified position. A `GtkEntry` The position at which to set the icon The icon to set Sets the icon shown in the entry at the specified position from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If @icon_name is %NULL, no icon will be shown in the specified position. A `GtkEntry` The position at which to set the icon An icon name Sets the icon shown in the specified position using a `GdkPaintable`. If @paintable is %NULL, no icon will be shown in the specified position. a `GtkEntry` Icon position A `GdkPaintable` Sets the sensitivity for the specified icon. A `GtkEntry` Icon position Specifies whether the icon should appear sensitive or insensitive Sets @tooltip as the contents of the tooltip for the icon at the specified position. @tooltip is assumed to be marked up with Pango Markup. Use %NULL for @tooltip to remove an existing tooltip. See also [method@Gtk.Widget.set_tooltip_markup] and [method@Gtk.Entry.set_icon_tooltip_text]. a `GtkEntry` the icon position the contents of the tooltip for the icon Sets @tooltip as the contents of the tooltip for the icon at the specified position. Use %NULL for @tooltip to remove an existing tooltip. See also [method@Gtk.Widget.set_tooltip_text] and [method@Gtk.Entry.set_icon_tooltip_markup]. If you unset the widget tooltip via [method@Gtk.Widget.set_tooltip_text] or [method@Gtk.Widget.set_tooltip_markup], this sets [property@Gtk.Widget:has-tooltip] to %FALSE, which suppresses icon tooltips too. You can resolve this by then calling [method@Gtk.Widget.set_has_tooltip] to set [property@Gtk.Widget:has-tooltip] back to %TRUE, or setting at least one non-empty tooltip on any icon achieves the same result. a `GtkEntry` the icon position the contents of the tooltip for the icon Set additional hints which allow input methods to fine-tune their behavior. a `GtkEntry` the hints Sets the input purpose which can be used by input methods to adjust their behavior. a `GtkEntry` the purpose Sets the character to use in place of the actual text in “password mode”. See [method@Gtk.Entry.set_visibility] for how to enable “password mode”. By default, GTK picks the best invisible char available in the current font. If you set the invisible char to 0, then the user will get no feedback at all; there will be no text on the screen as they type. a `GtkEntry` a Unicode character Sets the maximum allowed length of the contents of the widget. If the current contents are longer than the given length, then they will be truncated to fit. The length is in characters. This is equivalent to getting @entry's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.set_max_length] on it. a `GtkEntry` the maximum length of the entry, or 0 for no maximum. (other than the maximum length of entries.) The value passed in will be clamped to the range 0-65536. Sets whether the text is overwritten when typing in the `GtkEntry`. a `GtkEntry` new value Sets text to be displayed in @entry when it is empty. This can be used to give a visual hint of the expected contents of the `GtkEntry`. a `GtkEntry` a string to be displayed when @entry is empty and unfocused Causes the entry’s progress indicator to “fill in” the given fraction of the bar. The fraction should be between 0.0 and 1.0, inclusive. a `GtkEntry` fraction of the task that’s been completed Sets the fraction of total entry width to move the progress bouncing block for each pulse. Use [method@Gtk.Entry.progress_pulse] to pulse the progress. a `GtkEntry` fraction between 0.0 and 1.0 Sets a `PangoTabArray`. The tabstops in the array are applied to the entry text. a `GtkEntry` a `PangoTabArray` Sets whether the contents of the entry are visible or not. When visibility is set to %FALSE, characters are displayed as the invisible char, and will also appear that way when the text in the entry widget is copied elsewhere. By default, GTK picks the best invisible character available in the current font, but it can be changed with [method@Gtk.Entry.set_invisible_char]. Note that you probably want to set [property@Gtk.Entry:input-purpose] to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN to inform input methods about the purpose of this entry, in addition to setting visibility to %FALSE. a `GtkEntry` %TRUE if the contents of the entry are displayed as plaintext Unsets the invisible char, so that the default invisible char is used again. See [method@Gtk.Entry.set_invisible_char]. a `GtkEntry` Whether to activate the default widget when Enter is pressed. A list of Pango attributes to apply to the text of the entry. This is mainly useful to change the size or weight of the text. The `PangoAttribute`'s @start_index and @end_index must refer to the [class@Gtk.EntryBuffer] text, i.e. without the preedit string. The buffer object which actually stores the text. The auxiliary completion object to use with the entry. GtkEntryCompletion will be removed in GTK 5. Whether to suggest Emoji replacements for :-delimited names like `:heart:`. A menu model whose contents will be appended to the context menu. Whether the entry should draw a frame. Which IM (input method) module should be used for this entry. See [class@Gtk.IMContext]. Setting this to a non-%NULL value overrides the system-wide IM module setting. See the GtkSettings [property@Gtk.Settings:gtk-im-module] property. Additional hints that allow input methods to fine-tune their behavior. Also see [property@Gtk.Entry:input-purpose] The purpose of this text field. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN is independent from setting [property@Gtk.Entry:visibility]. The character to use when masking entry contents (“password mode”). Whether the invisible char has been set for the `GtkEntry`. Maximum number of characters for this entry. If text is overwritten when typing in the `GtkEntry`. The text that will be displayed in the `GtkEntry` when it is empty and unfocused. Whether the primary icon is activatable. GTK emits the [signal@Gtk.Entry::icon-press] and [signal@Gtk.Entry::icon-release] signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes. The `GIcon` to use for the primary icon for the entry. The icon name to use for the primary icon for the entry. A `GdkPaintable` to use as the primary icon for the entry. Whether the primary icon is sensitive. An insensitive icon appears grayed out. GTK does not emit the [signal@Gtk.Entry::icon-press] and [signal@Gtk.Entry::icon-release] signals and does not allow DND from insensitive icons. An icon should be set insensitive if the action that would trigger when clicked is currently not available. The representation which is used for the primary icon of the entry. The contents of the tooltip on the primary icon, with markup. Also see [method@Gtk.Entry.set_icon_tooltip_markup]. The contents of the tooltip on the primary icon. Also see [method@Gtk.Entry.set_icon_tooltip_text]. The current fraction of the task that's been completed. The fraction of total entry width to move the progress bouncing block for each pulse. See [method@Gtk.Entry.progress_pulse]. Number of pixels of the entry scrolled off the screen to the left. Whether the secondary icon is activatable. GTK emits the [signal@Gtk.Entry::icon-press] and [signal@Gtk.Entry::icon-release] signals only on sensitive, activatable icons. Sensitive, but non-activatable icons can be used for purely informational purposes. The `GIcon` to use for the secondary icon for the entry. The icon name to use for the secondary icon for the entry. A `GdkPaintable` to use as the secondary icon for the entry. Whether the secondary icon is sensitive. An insensitive icon appears grayed out. GTK does not emit the [signal@Gtk.Entry::icon-press[ and [signal@Gtk.Entry::icon-release] signals and does not allow DND from insensitive icons. An icon should be set insensitive if the action that would trigger when clicked is currently not available. The representation which is used for the secondary icon of the entry. The contents of the tooltip on the secondary icon, with markup. Also see [method@Gtk.Entry.set_icon_tooltip_markup]. The contents of the tooltip on the secondary icon. Also see [method@Gtk.Entry.set_icon_tooltip_text]. Whether the entry will show an Emoji icon in the secondary icon position to open the Emoji chooser. A list of tabstops to apply to the text of the entry. The length of the text in the `GtkEntry`. When %TRUE, pasted multi-line text is truncated to the first line. Whether the entry should show the “invisible char” instead of the actual text (“password mode”). Emitted when the entry is activated. The keybindings for this signal are all forms of the Enter key. Emitted when an activatable icon is clicked. The position of the clicked icon Emitted on the button release from a mouse click over an activatable icon. The position of the clicked icon A `GtkEntryBuffer` hold the text displayed in a `GtkText` widget. A single `GtkEntryBuffer` object can be shared by multiple widgets which will then share the same text content, but not the cursor position, visibility attributes, icon etc. `GtkEntryBuffer` may be derived from. Such a derived class might allow text to be stored in an alternate location, such as non-pageable memory, useful in the case of important passwords. Or a derived class could integrate with an application’s concept of undo/redo. Create a new `GtkEntryBuffer` object. Optionally, specify initial text to set in the buffer. A new `GtkEntryBuffer` object. initial buffer text number of characters in @initial_chars, or -1 Deletes a sequence of characters from the buffer. @n_chars characters are deleted starting at @position. If @n_chars is negative, then all characters until the end of the text are deleted. If @position or @n_chars are out of bounds, then they are coerced to sane values. Note that the positions are specified in characters, not bytes. The number of characters deleted. a `GtkEntryBuffer` position at which to delete text number of characters to delete Retrieves the length in characters of the buffer. The number of characters in the buffer. a `GtkEntryBuffer` Inserts @n_chars characters of @chars into the contents of the buffer, at position @position. If @n_chars is negative, then characters from chars will be inserted until a null-terminator is found. If @position or @n_chars are out of bounds, or the maximum buffer text length is exceeded, then they are coerced to sane values. Note that the position and length are in characters, not in bytes. The number of characters actually inserted. a `GtkEntryBuffer` the position at which to insert text. the text to insert into the buffer. the length of the text in characters, or -1 Deletes a sequence of characters from the buffer. @n_chars characters are deleted starting at @position. If @n_chars is negative, then all characters until the end of the text are deleted. If @position or @n_chars are out of bounds, then they are coerced to sane values. Note that the positions are specified in characters, not bytes. The number of characters deleted. a `GtkEntryBuffer` position at which to delete text number of characters to delete Used when subclassing `GtkEntryBuffer`. a `GtkEntryBuffer` position at which text was deleted number of characters deleted Used when subclassing `GtkEntryBuffer`. a `GtkEntryBuffer` position at which text was inserted text that was inserted number of characters inserted Retrieves the length in bytes of the buffer. See [method@Gtk.EntryBuffer.get_length]. The byte length of the buffer. a `GtkEntryBuffer` Retrieves the length in characters of the buffer. The number of characters in the buffer. a `GtkEntryBuffer` Retrieves the maximum allowed length of the text in @buffer. the maximum allowed number of characters in `GtkEntryBuffer`, or 0 if there is no maximum. a `GtkEntryBuffer` Retrieves the contents of the buffer. The memory pointer returned by this call will not change unless this object emits a signal, or is finalized. a pointer to the contents of the widget as a string. This string points to internally allocated storage in the buffer and must not be freed, modified or stored. a `GtkEntryBuffer` Inserts @n_chars characters of @chars into the contents of the buffer, at position @position. If @n_chars is negative, then characters from chars will be inserted until a null-terminator is found. If @position or @n_chars are out of bounds, or the maximum buffer text length is exceeded, then they are coerced to sane values. Note that the position and length are in characters, not in bytes. The number of characters actually inserted. a `GtkEntryBuffer` the position at which to insert text. the text to insert into the buffer. the length of the text in characters, or -1 Sets the maximum allowed length of the contents of the buffer. If the current contents are longer than the given length, then they will be truncated to fit. a `GtkEntryBuffer` the maximum length of the entry buffer, or 0 for no maximum. (other than the maximum length of entries.) The value passed in will be clamped to the range 0-65536. Sets the text in the buffer. This is roughly equivalent to calling [method@Gtk.EntryBuffer.delete_text] and [method@Gtk.EntryBuffer.insert_text]. Note that @n_chars is in characters, not in bytes. a `GtkEntryBuffer` the new text the number of characters in @text, or -1 The length (in characters) of the text in buffer. The maximum length (in characters) of the text in the buffer. The contents of the buffer. The text is altered in the default handler for this signal. If you want access to the text after the text has been modified, use %G_CONNECT_AFTER. the position the text was deleted at. The number of characters that were deleted. This signal is emitted after text is inserted into the buffer. the position the text was inserted at. The text that was inserted. The number of characters that were inserted. The number of characters in the buffer. a `GtkEntryBuffer` The number of characters actually inserted. a `GtkEntryBuffer` the position at which to insert text. the text to insert into the buffer. the length of the text in characters, or -1 The number of characters deleted. a `GtkEntryBuffer` position at which to delete text number of characters to delete Class structure for `GtkEntry`. All virtual functions have a default implementation. Derived classes may set the virtual function pointers for the signal handlers to %NULL, but must keep @get_text_area_size and @get_frame_size non-%NULL; either use the default implementation, or provide a custom one. The parent class. Class handler for the `GtkEntry::activate` signal. The default implementation activates the gtk.activate-default action. `GtkEntryCompletion` is an auxiliary object to provide completion functionality for `GtkEntry`. It implements the [iface@Gtk.CellLayout] interface, to allow the user to add extra cells to the `GtkTreeView` with completion matches. “Completion functionality” means that when the user modifies the text in the entry, `GtkEntryCompletion` checks which rows in the model match the current content of the entry, and displays a list of matches. By default, the matching is done by comparing the entry text case-insensitively against the text column of the model (see [method@Gtk.EntryCompletion.set_text_column]), but this can be overridden with a custom match function (see [method@Gtk.EntryCompletion.set_match_func]). When the user selects a completion, the content of the entry is updated. By default, the content of the entry is replaced by the text column of the model, but this can be overridden by connecting to the [signal@Gtk.EntryCompletion::match-selected] signal and updating the entry in the signal handler. Note that you should return %TRUE from the signal handler to suppress the default behaviour. To add completion functionality to an entry, use [method@Gtk.Entry.set_completion]. `GtkEntryCompletion` uses a [class@Gtk.TreeModelFilter] model to represent the subset of the entire model that is currently matching. While the `GtkEntryCompletion` signals [signal@Gtk.EntryCompletion::match-selected] and [signal@Gtk.EntryCompletion::cursor-on-match] take the original model and an iter pointing to that model as arguments, other callbacks and signals (such as `GtkCellLayoutDataFunc` or [signal@Gtk.CellArea::apply-attributes)] will generally take the filter model as argument. As long as you are only calling [method@Gtk.TreeModel.get], this will make no difference to you. If for some reason, you need the original model, use [method@Gtk.TreeModelFilter.get_model]. Don’t forget to use [method@Gtk.TreeModelFilter.convert_iter_to_child_iter] to obtain a matching iter. Creates a new `GtkEntryCompletion` object. GtkEntryCompletion will be removed in GTK 5. A newly created `GtkEntryCompletion` object Creates a new `GtkEntryCompletion` object using the specified @area. The `GtkCellArea` is used to layout cells in the underlying `GtkTreeViewColumn` for the drop-down menu. GtkEntryCompletion will be removed in GTK 5. A newly created `GtkEntryCompletion` object the `GtkCellArea` used to layout cells Requests a completion operation, or in other words a refiltering of the current list with completions, using the current key. The completion list view will be updated accordingly. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` Computes the common prefix that is shared by all rows in @completion that start with @key. If no row matches @key, %NULL will be returned. Note that a text column must have been set for this function to work, see [method@Gtk.EntryCompletion.set_text_column] for details. GtkEntryCompletion will be removed in GTK 5. The common prefix all rows starting with @key the entry completion The text to complete for Get the original text entered by the user that triggered the completion or %NULL if there’s no completion ongoing. GtkEntryCompletion will be removed in GTK 5. the prefix for the current completion a `GtkEntryCompletion` Gets the entry @completion has been attached to. GtkEntryCompletion will be removed in GTK 5. The entry @completion has been attached to a `GtkEntryCompletion` Returns whether the common prefix of the possible completions should be automatically inserted in the entry. GtkEntryCompletion will be removed in GTK 5. %TRUE if inline completion is turned on a `GtkEntryCompletion` Returns %TRUE if inline-selection mode is turned on. GtkEntryCompletion will be removed in GTK 5. %TRUE if inline-selection mode is on a `GtkEntryCompletion` Returns the minimum key length as set for @completion. GtkEntryCompletion will be removed in GTK 5. The currently used minimum key length a `GtkEntryCompletion` Returns the model the `GtkEntryCompletion` is using as data source. Returns %NULL if the model is unset. GtkEntryCompletion will be removed in GTK 5. A `GtkTreeModel` a `GtkEntryCompletion` Returns whether the completions should be presented in a popup window. GtkEntryCompletion will be removed in GTK 5. %TRUE if popup completion is turned on a `GtkEntryCompletion` Returns whether the completion popup window will be resized to the width of the entry. GtkEntryCompletion will be removed in GTK 5. %TRUE if the popup window will be resized to the width of the entry a `GtkEntryCompletion` Returns whether the completion popup window will appear even if there is only a single match. GtkEntryCompletion will be removed in GTK 5. %TRUE if the popup window will appear regardless of the number of matches a `GtkEntryCompletion` Returns the column in the model of @completion to get strings from. GtkEntryCompletion will be removed in GTK 5. the column containing the strings a `GtkEntryCompletion` Requests a prefix insertion. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` Sets whether the common prefix of the possible completions should be automatically inserted in the entry. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` %TRUE to do inline completion Sets whether it is possible to cycle through the possible completions inside the entry. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` %TRUE to do inline selection Sets the match function for @completion to be @func. The match function is used to determine if a row should or should not be in the completion list. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` the `GtkEntryCompletion`MatchFunc to use user data for @func destroy notify for @func_data. Requires the length of the search key for @completion to be at least @length. This is useful for long lists, where completing using a small key takes a lot of time and will come up with meaningless results anyway (ie, a too large dataset). GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` the minimum length of the key in order to start completing Sets the model for a `GtkEntryCompletion`. If @completion already has a model set, it will remove it before setting the new model. If model is %NULL, then it will unset the model. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` the `GtkTreeModel` Sets whether the completions should be presented in a popup window. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` %TRUE to do popup completion Sets whether the completion popup window will be resized to be the same width as the entry. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` %TRUE to make the width of the popup the same as the entry Sets whether the completion popup window will appear even if there is only a single match. You may want to set this to %FALSE if you are using [property@Gtk.EntryCompletion:inline-completion]. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` %TRUE if the popup should appear even for a single match Convenience function for setting up the most used case of this code: a completion list with just strings. This function will set up @completion to have a list displaying all (and just) strings in the completion list, and to get those strings from @column in the model of @completion. This functions creates and adds a `GtkCellRendererText` for the selected column. If you need to set the text column, but don't want the cell renderer, use g_object_set() to set the [property@Gtk.EntryCompletion:text-column] property directly. GtkEntryCompletion will be removed in GTK 5. a `GtkEntryCompletion` the column in the model of @completion to get strings from The `GtkCellArea` used to layout cell renderers in the treeview column. If no area is specified when creating the entry completion with [ctor@Gtk.EntryCompletion.new_with_area], a horizontally oriented [class@Gtk.CellAreaBox] will be used. Determines whether the common prefix of the possible completions should be inserted automatically in the entry. Note that this requires text-column to be set, even if you are using a custom match function. Determines whether the possible completions on the popup will appear in the entry as you navigate through them. The minimum key length as set for completion. The model used as data source. Determines whether the possible completions should be shown in a popup window. Determines whether the completions popup window will be resized to the width of the entry. Determines whether the completions popup window will shown for a single possible completion. You probably want to set this to %FALSE if you are using [property@Gtk.EntryCompletion:inline-completion]. The column of the model containing the strings. Note that the strings must be UTF-8. Emitted when a match from the cursor is on a match of the list. The default behaviour is to replace the contents of the entry with the contents of the text column in the row pointed to by @iter. Note that @model is the model that was passed to [method@Gtk.EntryCompletion.set_model]. %TRUE if the signal has been handled the `GtkTreeModel` containing the matches a `GtkTreeIter` positioned at the selected match Emitted when the inline autocompletion is triggered. The default behaviour is to make the entry display the whole prefix and select the newly inserted part. Applications may connect to this signal in order to insert only a smaller part of the @prefix into the entry - e.g. the entry used in the `GtkFileChooser` inserts only the part of the prefix up to the next '/'. %TRUE if the signal has been handled the common prefix of all possible completions Emitted when a match from the list is selected. The default behaviour is to replace the contents of the entry with the contents of the text column in the row pointed to by @iter. Note that @model is the model that was passed to [method@Gtk.EntryCompletion.set_model]. %TRUE if the signal has been handled the `GtkTreeModel` containing the matches a `GtkTreeIter` positioned at the selected match Emitted when the filter model has zero number of rows in completion_complete method. In other words when `GtkEntryCompletion` is out of suggestions. A function which decides whether the row indicated by @iter matches a given @key, and should be displayed as a possible completion for @key. Note that @key is normalized and case-folded (see g_utf8_normalize() and g_utf8_casefold()). If this is not appropriate, match functions have access to the unmodified key via `gtk_editable_get_text (GTK_EDITABLE (gtk_entry_completion_get_entry ()))`. %TRUE if @iter should be displayed as a possible completion for @key the `GtkEntryCompletion` the string to match, normalized and case-folded a `GtkTreeIter` indicating the row to match user data given to gtk_entry_completion_set_match_func() Specifies the side of the entry at which an icon is placed. At the beginning of the entry (depending on the text direction). At the end of the entry (depending on the text direction). `GtkEventController` is the base class for event controllers. These are ancillary objects associated to widgets, which react to `GdkEvents`, and possibly trigger actions as a consequence. Event controllers are added to a widget with [method@Gtk.Widget.add_controller]. It is rarely necessary to explicitly remove a controller with [method@Gtk.Widget.remove_controller]. See the chapter on [input handling](input-handling.html) for an overview of the basic concepts, such as the capture and bubble phases of event propagation. Returns the event that is currently being handled by the controller. At other times, %NULL is returned. the event that is currently handled by @controller a `GtkEventController` Returns the device of the event that is currently being handled by the controller. At other times, %NULL is returned. device of the event is currently handled by @controller a `GtkEventController` Returns the modifier state of the event that is currently being handled by the controller. At other times, 0 is returned. modifier state of the event is currently handled by @controller a `GtkEventController` Returns the timestamp of the event that is currently being handled by the controller. At other times, 0 is returned. timestamp of the event is currently handled by @controller a `GtkEventController` Gets the name of @controller. The controller name a `GtkEventController` Gets the propagation limit of the event controller. the propagation limit a `GtkEventController` Gets the propagation phase at which @controller handles events. the propagation phase a `GtkEventController` Returns the `GtkWidget` this controller relates to. a `GtkWidget` a `GtkEventController` Resets the @controller to a clean state. a `GtkEventController` Sets a name on the controller that can be used for debugging. a `GtkEventController` a name for @controller Sets the event propagation limit on the event controller. If the limit is set to %GTK_LIMIT_SAME_NATIVE, the controller won't handle events that are targeted at widgets on a different surface, such as popovers. a `GtkEventController` the propagation limit Sets the propagation phase at which a controller handles events. If @phase is %GTK_PHASE_NONE, no automatic event handling will be performed, but other additional gesture maintenance will. a `GtkEventController` a propagation phase Sets a name on the controller that can be used for debugging. a `GtkEventController` a name for @controller, must be a static string The name for this controller, typically used for debugging purposes. The limit for which events this controller will handle. The propagation phase at which this controller will handle events. The widget receiving the `GdkEvents` that the controller will handle. `GtkEventControllerFocus` is an event controller to keep track of keyboard focus. The event controller offers [signal@Gtk.EventControllerFocus::enter] and [signal@Gtk.EventControllerFocus::leave] signals, as well as [property@Gtk.EventControllerFocus:is-focus] and [property@Gtk.EventControllerFocus:contains-focus] properties which are updated to reflect focus changes inside the widget hierarchy that is rooted at the controllers widget. Creates a new event controller that will handle focus events. a new `GtkEventControllerFocus` Returns %TRUE if focus is within @self or one of its children. %TRUE if focus is within @self or one of its children a `GtkEventControllerFocus` Returns %TRUE if focus is within @self, but not one of its children. %TRUE if focus is within @self, but not one of its children a `GtkEventControllerFocus` %TRUE if focus is contained in the controllers widget. See [property@Gtk.EventControllerFocus:is-focus] for whether the focus is in the widget itself or inside a descendent. When handling focus events, this property is updated before [signal@Gtk.EventControllerFocus::enter] or [signal@Gtk.EventControllerFocus::leave] are emitted. %TRUE if focus is in the controllers widget itself, as opposed to in a descendent widget. See also [property@Gtk.EventControllerFocus:contains-focus]. When handling focus events, this property is updated before [signal@Gtk.EventControllerFocus::enter] or [signal@Gtk.EventControllerFocus::leave] are emitted. Emitted whenever the focus enters into the widget or one of its descendents. Note that this means you may not get an ::enter signal even though the widget becomes the focus location, in certain cases (such as when the focus moves from a descendent of the widget to the widget itself). If you are interested in these cases, you can monitor the [property@Gtk.EventControllerFocus:is-focus] property for changes. Emitted whenever the focus leaves the widget hierarchy that is rooted at the widget that the controller is attached to. Note that this means you may not get a ::leave signal even though the focus moves away from the widget, in certain cases (such as when the focus moves from the widget to a descendent). If you are interested in these cases, you can monitor the [property@Gtk.EventControllerFocus:is-focus] property for changes. `GtkEventControllerKey` is an event controller that provides access to key events. Creates a new event controller that will handle key events. a new `GtkEventControllerKey` Forwards the current event of this @controller to a @widget. This function can only be used in handlers for the [signal@Gtk.EventControllerKey::key-pressed], [signal@Gtk.EventControllerKey::key-released] or [signal@Gtk.EventControllerKey::modifiers] signals. whether the @widget handled the event a `GtkEventControllerKey` a `GtkWidget` Gets the key group of the current event of this @controller. See [method@Gdk.KeyEvent.get_layout]. the key group a `GtkEventControllerKey` Gets the input method context of the key @controller. the `GtkIMContext` a `GtkEventControllerKey` Sets the input method context of the key @controller. a `GtkEventControllerKey` a `GtkIMContext` Emitted whenever the input method context filters away a keypress and prevents the @controller receiving it. See [method@Gtk.EventControllerKey.set_im_context] and [method@Gtk.IMContext.filter_keypress]. Emitted whenever a key is pressed. %TRUE if the key press was handled, %FALSE otherwise. the pressed key. the raw code of the pressed key. the bitmask, representing the state of modifier keys and pointer buttons. Emitted whenever a key is released. the released key. the raw code of the released key. the bitmask, representing the state of modifier keys and pointer buttons. Emitted whenever the state of modifier keys and pointer buttons change. whether to ignore modifiers the bitmask, representing the new state of modifier keys and pointer buttons. `GtkEventControllerLegacy` is an event controller that provides raw access to the event stream. It should only be used as a last resort if none of the other event controllers or gestures do the job. Creates a new legacy event controller. the newly created event controller. Emitted for each GDK event delivered to @controller. %TRUE to stop other handlers from being invoked for the event and the emission of this signal. %FALSE to propagate the event further. the `GdkEvent` which triggered this signal `GtkEventControllerMotion` is an event controller tracking the pointer position. The event controller offers [signal@Gtk.EventControllerMotion::enter] and [signal@Gtk.EventControllerMotion::leave] signals, as well as [property@Gtk.EventControllerMotion:is-pointer] and [property@Gtk.EventControllerMotion:contains-pointer] properties which are updated to reflect changes in the pointer position as it moves over the widget. Creates a new event controller that will handle motion events. a new `GtkEventControllerMotion` Returns if a pointer is within @self or one of its children. %TRUE if a pointer is within @self or one of its children a `GtkEventControllerMotion` Returns if a pointer is within @self, but not one of its children. %TRUE if a pointer is within @self but not one of its children a `GtkEventControllerMotion` Whether the pointer is in the controllers widget or a descendant. See also [property@Gtk.EventControllerMotion:is-pointer]. When handling crossing events, this property is updated before [signal@Gtk.EventControllerMotion::enter], but after [signal@Gtk.EventControllerMotion::leave] is emitted. Whether the pointer is in the controllers widget itself, as opposed to in a descendent widget. See also [property@Gtk.EventControllerMotion:contains-pointer]. When handling crossing events, this property is updated before [signal@Gtk.EventControllerMotion::enter], but after [signal@Gtk.EventControllerMotion::leave] is emitted. Signals that the pointer has entered the widget. coordinates of pointer location coordinates of pointer location Signals that the pointer has left the widget. Emitted when the pointer moves inside the widget. the x coordinate the y coordinate `GtkEventControllerScroll` is an event controller that handles scroll events. It is capable of handling both discrete and continuous scroll events from mice or touchpads, abstracting them both with the [signal@Gtk.EventControllerScroll::scroll] signal. Deltas in the discrete case are multiples of 1. In the case of continuous scroll events, `GtkEventControllerScroll` encloses all [signal@Gtk.EventControllerScroll::scroll] emissions between two [signal@Gtk.EventControllerScroll::scroll-begin] and [signal@Gtk.EventControllerScroll::scroll-end] signals. The behavior of the event controller can be modified by the flags given at creation time, or modified at a later point through [method@Gtk.EventControllerScroll.set_flags] (e.g. because the scrolling conditions of the widget changed). The controller can be set up to emit motion for either/both vertical and horizontal scroll events through %GTK_EVENT_CONTROLLER_SCROLL_VERTICAL, %GTK_EVENT_CONTROLLER_SCROLL_HORIZONTAL and %GTK_EVENT_CONTROLLER_SCROLL_BOTH_AXES. If any axis is disabled, the respective [signal@Gtk.EventControllerScroll::scroll] delta will be 0. Vertical scroll events will be translated to horizontal motion for the devices incapable of horizontal scrolling. The event controller can also be forced to emit discrete events on all devices through %GTK_EVENT_CONTROLLER_SCROLL_DISCRETE. This can be used to implement discrete actions triggered through scroll events (e.g. switching across combobox options). The %GTK_EVENT_CONTROLLER_SCROLL_KINETIC flag toggles the emission of the [signal@Gtk.EventControllerScroll::decelerate] signal, emitted at the end of scrolling with two X/Y velocity arguments that are consistent with the motion that was received. Creates a new event controller that will handle scroll events. a new `GtkEventControllerScroll` flags affecting the controller behavior Gets the flags conditioning the scroll controller behavior. the controller flags. a `GtkEventControllerScroll` Gets the scroll unit of the last [signal@Gtk.EventControllerScroll::scroll] signal received. Always returns %GDK_SCROLL_UNIT_WHEEL if the %GTK_EVENT_CONTROLLER_SCROLL_DISCRETE flag is set. the scroll unit. a `GtkEventControllerScroll`. Sets the flags conditioning scroll controller behavior. a `GtkEventControllerScroll` flags affecting the controller behavior The flags affecting event controller behavior. Emitted after scroll is finished if the %GTK_EVENT_CONTROLLER_SCROLL_KINETIC flag is set. @vel_x and @vel_y express the initial velocity that was imprinted by the scroll events. @vel_x and @vel_y are expressed in pixels/ms. X velocity Y velocity Signals that the widget should scroll by the amount specified by @dx and @dy. For the representation unit of the deltas, see [method@Gtk.EventControllerScroll.get_unit]. %TRUE if the scroll event was handled, %FALSE otherwise. X delta Y delta Signals that a new scrolling operation has begun. It will only be emitted on devices capable of it. Signals that a scrolling operation has finished. It will only be emitted on devices capable of it. Describes the behavior of a `GtkEventControllerScroll`. Don't emit scroll. Emit scroll with vertical deltas. Emit scroll with horizontal deltas. Only emit deltas that are multiples of 1. Emit ::decelerate after continuous scroll finishes. Emit scroll on both axes. Describes the state of a [struct@Gdk.EventSequence] in a [class@Gesture]. The sequence is handled, but not grabbed. The sequence is handled and grabbed. The sequence is denied. `GtkEveryFilter` matches an item when each of its filters matches. To add filters to a `GtkEveryFilter`, use [method@Gtk.MultiFilter.append]. Creates a new empty "every" filter. Use [method@Gtk.MultiFilter.append] to add filters to it. This filter matches an item if each of the filters added to it matches the item. In particular, this means that if no filter has been added to it, the filter matches every item. a new `GtkEveryFilter` `GtkExpander` allows the user to reveal its child by clicking on an expander triangle.  This is similar to the triangles used in a `GtkTreeView`. Normally you use an expander as you would use a frame; you create the child widget and use [method@Gtk.Expander.set_child] to add it to the expander. When the expander is toggled, it will take care of showing and hiding the child automatically. # Special Usage There are situations in which you may prefer to show and hide the expanded widget yourself, such as when you want to actually create the widget at expansion time. In this case, create a `GtkExpander` but do not add a child to it. The expander widget has an [property@Gtk.Expander:expanded] property which can be used to monitor its expansion state. You should watch this property with a signal connection as follows: ```c static void expander_callback (GObject *object, GParamSpec *param_spec, gpointer user_data) { GtkExpander *expander; expander = GTK_EXPANDER (object); if (gtk_expander_get_expanded (expander)) { // Show or create widgets } else { // Hide or destroy widgets } } static void create_expander (void) { GtkWidget *expander = gtk_expander_new_with_mnemonic ("_More Options"); g_signal_connect (expander, "notify::expanded", G_CALLBACK (expander_callback), NULL); // ... } ``` # GtkExpander as GtkBuildable The `GtkExpander` implementation of the `GtkBuildable` interface supports placing a child in the label position by specifying “label” as the “type” attribute of a `<child>` element. A normal content child can be specified without specifying a `<child>` type attribute. An example of a UI definition fragment with GtkExpander: ```xml <object class="GtkExpander"> <child type="label"> <object class="GtkLabel" id="expander-label"/> </child> <child> <object class="GtkEntry" id="expander-content"/> </child> </object> ``` # CSS nodes ``` expander-widget ╰── box ├── title │ ├── expander │ ╰── <label widget> ╰── <child> ``` `GtkExpander` has a main node `expander-widget`, and subnode `box` containing the title and child widget. The box subnode `title` contains node `expander`, i.e. the expand/collapse arrow; then the label widget if any. The arrow of an expander that is showing its child gets the `:checked` pseudoclass set on it. # Accessibility `GtkExpander` uses the %GTK_ACCESSIBLE_ROLE_BUTTON role. Creates a new expander using @label as the text of the label. a new `GtkExpander` widget. the text of the label Creates a new expander using @label as the text of the label. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key activates the button. a new `GtkExpander` widget. the text of the label with an underscore in front of the mnemonic character Gets the child widget of @expander. the child widget of @expander a `GtkExpander` Queries a `GtkExpander` and returns its current state. Returns %TRUE if the child widget is revealed. the current state of the expander a `GtkExpander` Fetches the text from a label widget. This is including any embedded underlines indicating mnemonics and Pango markup, as set by [method@Gtk.Expander.set_label]. If the label text has not been set the return value will be %NULL. This will be the case if you create an empty button with gtk_button_new() to use as a container. The text of the label widget. This string is owned by the widget and must not be modified or freed. a `GtkExpander` Retrieves the label widget for the frame. the label widget a `GtkExpander` Returns whether the expander will resize the toplevel widget containing the expander upon resizing and collapsing. the “resize toplevel” setting. a `GtkExpander` Returns whether the label’s text is interpreted as Pango markup. %TRUE if the label’s text will be parsed for markup a `GtkExpander` Returns whether an underline in the text indicates a mnemonic. %TRUE if an embedded underline in the expander label indicates the mnemonic accelerator keys a `GtkExpander` Sets the child widget of @expander. a `GtkExpander` the child widget Sets the state of the expander. Set to %TRUE, if you want the child widget to be revealed, and %FALSE if you want the child widget to be hidden. a `GtkExpander` whether the child widget is revealed Sets the text of the label of the expander to @label. This will also clear any previously set labels. a `GtkExpander` a string Set the label widget for the expander. This is the widget that will appear embedded alongside the expander arrow. a `GtkExpander` the new label widget Sets whether the expander will resize the toplevel widget containing the expander upon resizing and collapsing. a `GtkExpander` whether to resize the toplevel Sets whether the text of the label contains Pango markup. a `GtkExpander` %TRUE if the label’s text should be parsed for markup If true, an underline in the text indicates a mnemonic. a `GtkExpander` %TRUE if underlines in the text indicate mnemonics The child widget. Whether the expander has been opened to reveal the child. The text of the expanders label. A widget to display instead of the usual expander label. When this property is %TRUE, the expander will resize the toplevel widget containing the expander upon expanding and collapsing. Whether the text in the label is Pango markup. Whether an underline in the text indicates a mnemonic. Activates the `GtkExpander`. `GtkExpression` provides a way to describe references to values. An important aspect of expressions is that the value can be obtained from a source that is several steps away. For example, an expression may describe ‘the value of property A of `object1`, which is itself the value of a property of `object2`’. And `object1` may not even exist yet at the time that the expression is created. This is contrast to `GObject` property bindings, which can only create direct connections between the properties of two objects that must both exist for the duration of the binding. An expression needs to be "evaluated" to obtain the value that it currently refers to. An evaluation always happens in the context of a current object called `this` (it mirrors the behavior of object-oriented languages), which may or may not influence the result of the evaluation. Use [method@Gtk.Expression.evaluate] for evaluating an expression. Various methods for defining expressions exist, from simple constants via [ctor@Gtk.ConstantExpression.new] to looking up properties in a `GObject` (even recursively) via [ctor@Gtk.PropertyExpression.new] or providing custom functions to transform and combine expressions via [ctor@Gtk.ClosureExpression.new]. Here is an example of a complex expression: ```c color_expr = gtk_property_expression_new (GTK_TYPE_LIST_ITEM, NULL, "item"); expression = gtk_property_expression_new (GTK_TYPE_COLOR, color_expr, "name"); ``` when evaluated with `this` being a `GtkListItem`, it will obtain the "item" property from the `GtkListItem`, and then obtain the "name" property from the resulting object (which is assumed to be of type `GTK_TYPE_COLOR`). A more concise way to describe this would be ``` this->item->name ``` The most likely place where you will encounter expressions is in the context of list models and list widgets using them. For example, `GtkDropDown` is evaluating a `GtkExpression` to obtain strings from the items in its model that it can then use to match against the contents of its search entry. `GtkStringFilter` is using a `GtkExpression` for similar reasons. By default, expressions are not paying attention to changes and evaluation is just a snapshot of the current state at a given time. To get informed about changes, an expression needs to be "watched" via a [struct@Gtk.ExpressionWatch], which will cause a callback to be called whenever the value of the expression may have changed; [method@Gtk.Expression.watch] starts watching an expression, and [method@Gtk.ExpressionWatch.unwatch] stops. Watches can be created for automatically updating the property of an object, similar to GObject's `GBinding` mechanism, by using [method@Gtk.Expression.bind]. ## GtkExpression in GObject properties In order to use a `GtkExpression` as a `GObject` property, you must use the [func@Gtk.param_spec_expression] when creating a `GParamSpec` to install in the `GObject` class being defined; for instance: ```c obj_props[PROP_EXPRESSION] = gtk_param_spec_expression ("expression", "Expression", "The expression used by the widget", G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS | G_PARAM_EXPLICIT_NOTIFY); ``` When implementing the `GObjectClass.set_property` and `GObjectClass.get_property` virtual functions, you must use [func@Gtk.value_get_expression], to retrieve the stored `GtkExpression` from the `GValue` container, and [func@Gtk.value_set_expression], to store the `GtkExpression` into the `GValue`; for instance: ```c // in set_property()... case PROP_EXPRESSION: foo_widget_set_expression (foo, gtk_value_get_expression (value)); break; // in get_property()... case PROP_EXPRESSION: gtk_value_set_expression (value, foo->expression); break; ``` ## GtkExpression in .ui files `GtkBuilder` has support for creating expressions. The syntax here can be used where a `GtkExpression` object is needed like in a `<property>` tag for an expression property, or in a `<binding name="property">` tag to bind a property to an expression. To create a property expression, use the `<lookup>` element. It can have a `type` attribute to specify the object type, and a `name` attribute to specify the property to look up. The content of `<lookup>` can either be an element specifying the expression to use the object, or a string that specifies the name of the object to use. Example: ```xml <lookup name='search'>string_filter</lookup> ``` Since the `<lookup>` element creates an expression and its element content can itself be an expression, this means that `<lookup>` tags can also be nested. This is a common idiom when dealing with `GtkListItem`s. See [class@Gtk.BuilderListItemFactory] for an example of this technique. To create a constant expression, use the `<constant>` element. If the type attribute is specified, the element content is interpreted as a value of that type. Otherwise, it is assumed to be an object. For instance: ```xml <constant>string_filter</constant> <constant type='gchararray'>Hello, world</constant> ``` To create a closure expression, use the `<closure>` element. The `function` attribute specifies what function to use for the closure, and the `type` attribute specifies its return type. The content of the element contains the expressions for the parameters. For instance: ```xml <closure type='gchararray' function='combine_args_somehow'> <constant type='gchararray'>File size:</constant> <lookup type='GFile' name='size'>myfile</lookup> </closure> ``` To create a property binding, use the `<binding>` element in place of where a `<property>` tag would ordinarily be used. The `name` and `object` attributes are supported. The `name` attribute is required, and pertains to the applicable property name. The `object` attribute is optional. If provided, it will use the specified object as the `this` object when the expression is evaluated. Here is an example in which the `label` property of a `GtkLabel` is bound to the `string` property of another arbitrary object: ```xml <object class='GtkLabel'> <binding name='label'> <lookup name='string'>some_other_object</lookup> </binding> </object> ``` Bind `target`'s property named `property` to `self`. The value that `self` evaluates to is set via `g_object_set()` on `target`. This is repeated whenever `self` changes to ensure that the object's property stays synchronized with `self`. If `self`'s evaluation fails, `target`'s `property` is not updated. You can ensure that this doesn't happen by using a fallback expression. Note that this function takes ownership of `self`. If you want to keep it around, you should [method@Gtk.Expression.ref] it beforehand. a `GtkExpressionWatch` a `GtkExpression` the target object to bind to name of the property on `target` to bind to the this argument for the evaluation of `self` Evaluates the given expression and on success stores the result in @value. The `GType` of `value` will be the type given by [method@Gtk.Expression.get_value_type]. It is possible that expressions cannot be evaluated - for example when the expression references objects that have been destroyed or set to `NULL`. In that case `value` will remain empty and `FALSE` will be returned. `TRUE` if the expression could be evaluated a `GtkExpression` the this argument for the evaluation an empty `GValue` Gets the `GType` that this expression evaluates to. This type is constant and will not change over the lifetime of this expression. The type returned from [method@Gtk.Expression.evaluate] a `GtkExpression` Checks if the expression is static. A static expression will never change its result when [method@Gtk.Expression.evaluate] is called on it with the same arguments. That means a call to [method@Gtk.Expression.watch] is not necessary because it will never trigger a notify. `TRUE` if the expression is static a `GtkExpression` Acquires a reference on the given `GtkExpression`. the `GtkExpression` with an additional reference a `GtkExpression` Releases a reference on the given `GtkExpression`. If the reference was the last, the resources associated to the `self` are freed. a `GtkExpression` Watch the given `expression` for changes. The @notify function will be called whenever the evaluation of `self` may have changed. GTK cannot guarantee that the evaluation did indeed change when the @notify gets invoked, but it guarantees the opposite: When it did in fact change, the @notify will be invoked. The newly installed watch. Note that the only reference held to the watch will be released when the watch is unwatched which can happen automatically, and not just via [method@Gtk.ExpressionWatch.unwatch]. You should call [method@Gtk.ExpressionWatch.ref] if you want to keep the watch around. a `GtkExpression` the `this` argument to watch callback to invoke when the expression changes user data to pass to the `notify` callback destroy notify for `user_data` Callback called by gtk_expression_watch() when the expression value changes. data passed to gtk_expression_watch() An opaque structure representing a watched `GtkExpression`. The contents of `GtkExpressionWatch` should only be accessed through the provided API. Evaluates the watched expression and on success stores the result in `value`. This is equivalent to calling [method@Gtk.Expression.evaluate] with the expression and this pointer originally used to create `watch`. `TRUE` if the expression could be evaluated and `value` was set a `GtkExpressionWatch` an empty `GValue` to be set Acquires a reference on the given `GtkExpressionWatch`. the `GtkExpressionWatch` with an additional reference a `GtkExpressionWatch` Releases a reference on the given `GtkExpressionWatch`. If the reference was the last, the resources associated to `self` are freed. a `GtkExpressionWatch` Stops watching an expression. See [method@Gtk.Expression.watch] for how the watch was established. watch to release `GtkFileChooser` is an interface that can be implemented by file selection widgets. In GTK, the main objects that implement this interface are [class@Gtk.FileChooserWidget] and [class@Gtk.FileChooserDialog]. You do not need to write an object that implements the `GtkFileChooser` interface unless you are trying to adapt an existing file selector to expose a standard programming interface. `GtkFileChooser` allows for shortcuts to various places in the filesystem. In the default implementation these are displayed in the left pane. It may be a bit confusing at first that these shortcuts come from various sources and in various flavours, so lets explain the terminology here: - Bookmarks: are created by the user, by dragging folders from the right pane to the left pane, or by using the “Add”. Bookmarks can be renamed and deleted by the user. - Shortcuts: can be provided by the application. For example, a Paint program may want to add a shortcut for a Clipart folder. Shortcuts cannot be modified by the user. - Volumes: are provided by the underlying filesystem abstraction. They are the “roots” of the filesystem. # File Names and Encodings When the user is finished selecting files in a `GtkFileChooser`, your program can get the selected filenames as `GFile`s. # Adding options You can add extra widgets to a file chooser to provide options that are not present in the default design, by using [method@Gtk.FileChooser.add_choice]. Each choice has an identifier and a user visible label; additionally, each choice can have multiple options. If a choice has no option, it will be rendered as a check button with the given label; if a choice has options, it will be rendered as a combo box. Use [class@Gtk.FileDialog] instead Adds a 'choice' to the file chooser. This is typically implemented as a combobox or, for boolean choices, as a checkbutton. You can select a value using [method@Gtk.FileChooser.set_choice] before the dialog is shown, and you can obtain the user-selected value in the [signal@Gtk.Dialog::response] signal handler using [method@Gtk.FileChooser.get_choice]. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` id for the added choice user-visible label for the added choice ids for the options of the choice, or %NULL for a boolean choice user-visible labels for the options, must be the same length as @options Adds @filter to the list of filters that the user can select between. When a filter is selected, only files that are passed by that filter are displayed. Note that the @chooser takes ownership of the filter if it is floating, so you have to ref and sink it if you want to keep a reference. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` a `GtkFileFilter` Adds a folder to be displayed with the shortcut folders in a file chooser. Use [class@Gtk.FileDialog] instead %TRUE if the folder could be added successfully, %FALSE otherwise. a `GtkFileChooser` a `GFile` for the folder to add Gets the type of operation that the file chooser is performing. Use [class@Gtk.FileDialog] instead the action that the file selector is performing a `GtkFileChooser` Gets the currently selected option in the 'choice' with the given ID. Use [class@Gtk.FileDialog] instead the ID of the currently selected option a `GtkFileChooser` the ID of the choice to get Gets whether file chooser will offer to create new folders. Use [class@Gtk.FileDialog] instead %TRUE if the Create Folder button should be displayed. a `GtkFileChooser` Gets the current folder of @chooser as `GFile`. Use [class@Gtk.FileDialog] instead the `GFile` for the current folder. a `GtkFileChooser` Gets the current name in the file selector, as entered by the user. This is meant to be used in save dialogs, to get the currently typed filename when the file itself does not exist yet. Use [class@Gtk.FileDialog] instead The raw text from the file chooser’s “Name” entry. Free with g_free(). Note that this string is not a full pathname or URI; it is whatever the contents of the entry are. Note also that this string is in UTF-8 encoding, which is not necessarily the system’s encoding for filenames. a `GtkFileChooser` Gets the `GFile` for the currently selected file in the file selector. If multiple files are selected, one of the files will be returned at random. If the file chooser is in folder mode, this function returns the selected folder. Use [class@Gtk.FileDialog] instead a selected `GFile`. You own the returned file; use g_object_unref() to release it. a `GtkFileChooser` Lists all the selected files and subfolders in the current folder of @chooser as `GFile`. Use [class@Gtk.FileDialog] instead a list model containing a `GFile` for each selected file and subfolder in the current folder. Free the returned list with g_object_unref(). a `GtkFileChooser` Gets the current filter. Use [class@Gtk.FileDialog] instead the current filter a `GtkFileChooser` Gets the current set of user-selectable filters, as a list model. See [method@Gtk.FileChooser.add_filter] and [method@Gtk.FileChooser.remove_filter] for changing individual filters. You should not modify the returned list model. Future changes to @chooser may or may not affect the returned model. Use [class@Gtk.FileDialog] instead a `GListModel` containing the current set of user-selectable filters. a `GtkFileChooser` Gets whether multiple files can be selected in the file chooser. Use [class@Gtk.FileDialog] instead %TRUE if multiple files can be selected. a `GtkFileChooser` Queries the list of shortcut folders in the file chooser. You should not modify the returned list model. Future changes to @chooser may or may not affect the returned model. Use [class@Gtk.FileDialog] instead A list model of `GFile`s a `GtkFileChooser` Removes a 'choice' that has been added with gtk_file_chooser_add_choice(). Use [class@Gtk.FileDialog] instead a `GtkFileChooser` the ID of the choice to remove Removes @filter from the list of filters that the user can select between. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` a `GtkFileFilter` Removes a folder from the shortcut folders in a file chooser. Use [class@Gtk.FileDialog] instead %TRUE if the folder could be removed successfully, %FALSE otherwise. a `GtkFileChooser` a `GFile` for the folder to remove Sets the type of operation that the chooser is performing. The user interface is adapted to suit the selected action. For example, an option to create a new folder might be shown if the action is %GTK_FILE_CHOOSER_ACTION_SAVE but not if the action is %GTK_FILE_CHOOSER_ACTION_OPEN. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` the action that the file selector is performing Selects an option in a 'choice' that has been added with gtk_file_chooser_add_choice(). For a boolean choice, the possible options are "true" and "false". Use [class@Gtk.FileDialog] instead a `GtkFileChooser` the ID of the choice to set the ID of the option to select Sets whether file chooser will offer to create new folders. This is only relevant if the action is not set to be %GTK_FILE_CHOOSER_ACTION_OPEN. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` %TRUE if the Create Folder button should be displayed Sets the current folder for @chooser from a `GFile`. Use [class@Gtk.FileDialog] instead %TRUE if the folder could be changed successfully, %FALSE otherwise. a `GtkFileChooser` the `GFile` for the new folder Sets the current name in the file selector, as if entered by the user. Note that the name passed in here is a UTF-8 string rather than a filename. This function is meant for such uses as a suggested name in a “Save As...” dialog. You can pass “Untitled.doc” or a similarly suitable suggestion for the @name. If you want to preselect a particular existing file, you should use [method@Gtk.FileChooser.set_file] instead. Please see the documentation for those functions for an example of using [method@Gtk.FileChooser.set_current_name] as well. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` the filename to use, as a UTF-8 string Sets @file as the current filename for the file chooser. This includes changing to the file’s parent folder and actually selecting the file in list. If the @chooser is in %GTK_FILE_CHOOSER_ACTION_SAVE mode, the file’s base name will also appear in the dialog’s file name entry. If the file name isn’t in the current folder of @chooser, then the current folder of @chooser will be changed to the folder containing @file. Note that the file must exist, or nothing will be done except for the directory change. If you are implementing a save dialog, you should use this function if you already have a file name to which the user may save; for example, when the user opens an existing file and then does “Save As…”. If you don’t have a file name already — for example, if the user just created a new file and is saving it for the first time, do not call this function. Instead, use something similar to this: ```c static void prepare_file_chooser (GtkFileChooser *chooser, GFile *existing_file) { gboolean document_is_new = (existing_file == NULL); if (document_is_new) { GFile *default_file_for_saving = g_file_new_for_path ("./out.txt"); // the user just created a new document gtk_file_chooser_set_current_folder (chooser, default_file_for_saving, NULL); gtk_file_chooser_set_current_name (chooser, "Untitled document"); g_object_unref (default_file_for_saving); } else { // the user edited an existing document gtk_file_chooser_set_file (chooser, existing_file, NULL); } } ``` Use [class@Gtk.FileDialog] instead Not useful a `GtkFileChooser` the `GFile` to set as current Sets the current filter. Only the files that pass the filter will be displayed. If the user-selectable list of filters is non-empty, then the filter should be one of the filters in that list. Setting the current filter when the list of filters is empty is useful if you want to restrict the displayed set of files without letting the user change it. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` a `GtkFileFilter` Sets whether multiple files can be selected in the file chooser. This is only relevant if the action is set to be %GTK_FILE_CHOOSER_ACTION_OPEN or %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. Use [class@Gtk.FileDialog] instead a `GtkFileChooser` %TRUE if multiple files can be selected. The type of operation that the file chooser is performing. Use [class@Gtk.FileDialog] instead Whether a file chooser not in %GTK_FILE_CHOOSER_ACTION_OPEN mode will offer the user to create new folders. Use [class@Gtk.FileDialog] instead The current filter for selecting files that are displayed. Use [class@Gtk.FileDialog] instead A `GListModel` containing the filters that have been added with gtk_file_chooser_add_filter(). The returned object should not be modified. It may or may not be updated for later changes. Use [class@Gtk.FileDialog] instead Whether to allow multiple files to be selected. Use [class@Gtk.FileDialog] instead A `GListModel` containing the shortcut folders that have been added with gtk_file_chooser_add_shortcut_folder(). The returned object should not be modified. It may or may not be updated for later changes. Use [class@Gtk.FileDialog] instead Describes whether a `GtkFileChooser` is being used to open existing files or to save to a possibly new file. Indicates open mode. The file chooser will only let the user pick an existing file. Indicates save mode. The file chooser will let the user pick an existing file, or type in a new filename. Indicates an Open mode for selecting folders. The file chooser will let the user pick an existing folder. `GtkFileChooserDialog` is a dialog suitable for use with “File Open” or “File Save” commands.  This widget works by putting a [class@Gtk.FileChooserWidget] inside a [class@Gtk.Dialog]. It exposes the [iface@Gtk.FileChooser] interface, so you can use all of the [iface@Gtk.FileChooser] functions on the file chooser dialog as well as those for [class@Gtk.Dialog]. Note that `GtkFileChooserDialog` does not have any methods of its own. Instead, you should use the functions that work on a [iface@Gtk.FileChooser]. If you want to integrate well with the platform you should use the [class@Gtk.FileChooserNative] API, which will use a platform-specific dialog if available and fall back to `GtkFileChooserDialog` otherwise. ## Typical usage In the simplest of cases, you can the following code to use `GtkFileChooserDialog` to select a file for opening: ```c static void on_open_response (GtkDialog *dialog, int response) { if (response == GTK_RESPONSE_ACCEPT) { GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog); g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser); open_file (file); } gtk_window_destroy (GTK_WINDOW (dialog)); } // ... GtkWidget *dialog; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN; dialog = gtk_file_chooser_dialog_new ("Open File", parent_window, action, _("_Cancel"), GTK_RESPONSE_CANCEL, _("_Open"), GTK_RESPONSE_ACCEPT, NULL); gtk_window_present (GTK_WINDOW (dialog)); g_signal_connect (dialog, "response", G_CALLBACK (on_open_response), NULL); ``` To use a dialog for saving, you can use this: ```c static void on_save_response (GtkDialog *dialog, int response) { if (response == GTK_RESPONSE_ACCEPT) { GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog); g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser); save_to_file (file); } gtk_window_destroy (GTK_WINDOW (dialog)); } // ... GtkWidget *dialog; GtkFileChooser *chooser; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE; dialog = gtk_file_chooser_dialog_new ("Save File", parent_window, action, _("_Cancel"), GTK_RESPONSE_CANCEL, _("_Save"), GTK_RESPONSE_ACCEPT, NULL); chooser = GTK_FILE_CHOOSER (dialog); if (user_edited_a_new_document) gtk_file_chooser_set_current_name (chooser, _("Untitled document")); else gtk_file_chooser_set_file (chooser, existing_filename); gtk_window_present (GTK_WINDOW (dialog)); g_signal_connect (dialog, "response", G_CALLBACK (on_save_response), NULL); ``` ## Setting up a file chooser dialog There are various cases in which you may need to use a `GtkFileChooserDialog`: - To select a file for opening, use %GTK_FILE_CHOOSER_ACTION_OPEN. - To save a file for the first time, use %GTK_FILE_CHOOSER_ACTION_SAVE, and suggest a name such as “Untitled” with [method@Gtk.FileChooser.set_current_name]. - To save a file under a different name, use %GTK_FILE_CHOOSER_ACTION_SAVE, and set the existing file with [method@Gtk.FileChooser.set_file]. - To choose a folder instead of a filem use %GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER. In general, you should only cause the file chooser to show a specific folder when it is appropriate to use [method@Gtk.FileChooser.set_file], i.e. when you are doing a “Save As” command and you already have a file saved somewhere. ## Response Codes `GtkFileChooserDialog` inherits from [class@Gtk.Dialog], so buttons that go in its action area have response codes such as %GTK_RESPONSE_ACCEPT and %GTK_RESPONSE_CANCEL. For example, you could call [ctor@Gtk.FileChooserDialog.new] as follows: ```c GtkWidget *dialog; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN; dialog = gtk_file_chooser_dialog_new ("Open File", parent_window, action, _("_Cancel"), GTK_RESPONSE_CANCEL, _("_Open"), GTK_RESPONSE_ACCEPT, NULL); ``` This will create buttons for “Cancel” and “Open” that use predefined response identifiers from [enum@Gtk.ResponseType]. For most dialog boxes you can use your own custom response codes rather than the ones in [enum@Gtk.ResponseType], but `GtkFileChooserDialog` assumes that its “accept”-type action, e.g. an “Open” or “Save” button, will have one of the following response codes: - %GTK_RESPONSE_ACCEPT - %GTK_RESPONSE_OK - %GTK_RESPONSE_YES - %GTK_RESPONSE_APPLY This is because `GtkFileChooserDialog` must intercept responses and switch to folders if appropriate, rather than letting the dialog terminate — the implementation uses these known response codes to know which responses can be blocked if appropriate. To summarize, make sure you use a predefined response code when you use `GtkFileChooserDialog` to ensure proper operation. ## CSS nodes `GtkFileChooserDialog` has a single CSS node with the name `window` and style class `.filechooser`. Use [class@Gtk.FileDialog] instead Creates a new `GtkFileChooserDialog`. This function is analogous to [ctor@Gtk.Dialog.new_with_buttons]. Use [class@Gtk.FileDialog] instead a new `GtkFileChooserDialog` Title of the dialog Transient parent of the dialog Open or save mode for the dialog text to go in the first button response ID for the first button, then additional (button, id) pairs, ending with %NULL These identify the various errors that can occur while calling `GtkFileChooser` functions. Indicates that a file does not exist. Indicates a malformed filename. Indicates a duplicate path (e.g. when adding a bookmark). Indicates an incomplete hostname (e.g. "http://foo" without a slash after that). Registers an error quark for `GtkFileChooser` errors. The error quark used for `GtkFileChooser` errors. `GtkFileChooserNative` is an abstraction of a dialog suitable for use with “File Open” or “File Save as” commands. By default, this just uses a `GtkFileChooserDialog` to implement the actual dialog. However, on some platforms, such as Windows and macOS, the native platform file chooser is used instead. When the application is running in a sandboxed environment without direct filesystem access (such as Flatpak), `GtkFileChooserNative` may call the proper APIs (portals) to let the user choose a file and make it available to the application. While the API of `GtkFileChooserNative` closely mirrors `GtkFileChooserDialog`, the main difference is that there is no access to any `GtkWindow` or `GtkWidget` for the dialog. This is required, as there may not be one in the case of a platform native dialog. Showing, hiding and running the dialog is handled by the [class@Gtk.NativeDialog] functions. Note that unlike `GtkFileChooserDialog`, `GtkFileChooserNative` objects are not toplevel widgets, and GTK does not keep them alive. It is your responsibility to keep a reference until you are done with the object. ## Typical usage In the simplest of cases, you can the following code to use `GtkFileChooserNative` to select a file for opening: ```c static void on_response (GtkNativeDialog *native, int response) { if (response == GTK_RESPONSE_ACCEPT) { GtkFileChooser *chooser = GTK_FILE_CHOOSER (native); GFile *file = gtk_file_chooser_get_file (chooser); open_file (file); g_object_unref (file); } g_object_unref (native); } // ... GtkFileChooserNative *native; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN; native = gtk_file_chooser_native_new ("Open File", parent_window, action, "_Open", "_Cancel"); g_signal_connect (native, "response", G_CALLBACK (on_response), NULL); gtk_native_dialog_show (GTK_NATIVE_DIALOG (native)); ``` To use a `GtkFileChooserNative` for saving, you can use this: ```c static void on_response (GtkNativeDialog *native, int response) { if (response == GTK_RESPONSE_ACCEPT) { GtkFileChooser *chooser = GTK_FILE_CHOOSER (native); GFile *file = gtk_file_chooser_get_file (chooser); save_to_file (file); g_object_unref (file); } g_object_unref (native); } // ... GtkFileChooserNative *native; GtkFileChooser *chooser; GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE; native = gtk_file_chooser_native_new ("Save File", parent_window, action, "_Save", "_Cancel"); chooser = GTK_FILE_CHOOSER (native); if (user_edited_a_new_document) gtk_file_chooser_set_current_name (chooser, _("Untitled document")); else gtk_file_chooser_set_file (chooser, existing_file, NULL); g_signal_connect (native, "response", G_CALLBACK (on_response), NULL); gtk_native_dialog_show (GTK_NATIVE_DIALOG (native)); ``` For more information on how to best set up a file dialog, see the [class@Gtk.FileChooserDialog] documentation. ## Response Codes `GtkFileChooserNative` inherits from [class@Gtk.NativeDialog], which means it will return %GTK_RESPONSE_ACCEPT if the user accepted, and %GTK_RESPONSE_CANCEL if he pressed cancel. It can also return %GTK_RESPONSE_DELETE_EVENT if the window was unexpectedly closed. ## Differences from `GtkFileChooserDialog` There are a few things in the [iface@Gtk.FileChooser] interface that are not possible to use with `GtkFileChooserNative`, as such use would prohibit the use of a native dialog. No operations that change the dialog work while the dialog is visible. Set all the properties that are required before showing the dialog. ## Win32 details On windows the `IFileDialog` implementation (added in Windows Vista) is used. It supports many of the features that `GtkFileChooser` has, but there are some things it does not handle: * Any [class@Gtk.FileFilter] added using a mimetype If any of these features are used the regular `GtkFileChooserDialog` will be used in place of the native one. ## Portal details When the `org.freedesktop.portal.FileChooser` portal is available on the session bus, it is used to bring up an out-of-process file chooser. Depending on the kind of session the application is running in, this may or may not be a GTK file chooser. ## macOS details On macOS the `NSSavePanel` and `NSOpenPanel` classes are used to provide native file chooser dialogs. Some features provided by `GtkFileChooser` are not supported: * Shortcut folders. Use [class@Gtk.FileDialog] instead Creates a new `GtkFileChooserNative`. Use [class@Gtk.FileDialog] instead a new `GtkFileChooserNative` Title of the native Transient parent of the native Open or save mode for the dialog text to go in the accept button, or %NULL for the default text to go in the cancel button, or %NULL for the default Retrieves the custom label text for the accept button. Use [class@Gtk.FileDialog] instead The custom label a `GtkFileChooserNative` Retrieves the custom label text for the cancel button. Use [class@Gtk.FileDialog] instead The custom label a `GtkFileChooserNative` Sets the custom label text for the accept button. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key should activate the button. Use [class@Gtk.FileDialog] instead a `GtkFileChooserNative` custom label Sets the custom label text for the cancel button. If characters in @label are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use “__” (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. Pressing Alt and that key should activate the button. Use [class@Gtk.FileDialog] instead a `GtkFileChooserNative` custom label The text used for the label on the accept button in the dialog, or %NULL to use the default text. The text used for the label on the cancel button in the dialog, or %NULL to use the default text. `GtkFileChooserWidget` is a widget for choosing files. It exposes the [iface@Gtk.FileChooser] interface, and you should use the methods of this interface to interact with the widget. # Shortcuts and Gestures `GtkFileChooserWidget` supports the following keyboard shortcuts: - <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. The following signals have default keybindings: - [signal@Gtk.FileChooserWidget::desktop-folder] - [signal@Gtk.FileChooserWidget::down-folder] - [signal@Gtk.FileChooserWidget::home-folder] - [signal@Gtk.FileChooserWidget::location-popup] - [signal@Gtk.FileChooserWidget::location-popup-on-paste] - [signal@Gtk.FileChooserWidget::location-toggle-popup] - [signal@Gtk.FileChooserWidget::places-shortcut] - [signal@Gtk.FileChooserWidget::quick-bookmark] - [signal@Gtk.FileChooserWidget::recent-shortcut] - [signal@Gtk.FileChooserWidget::search-shortcut] - [signal@Gtk.FileChooserWidget::show-hidden] - [signal@Gtk.FileChooserWidget::up-folder] # CSS nodes `GtkFileChooserWidget` has a single CSS node with name filechooser. Direct use of `GtkFileChooserWidget` is deprecated Creates a new `GtkFileChooserWidget`. This is a file chooser widget that can be embedded in custom windows, and it is the same widget that is used by `GtkFileChooserDialog`. Direct use of `GtkFileChooserWidget` is deprecated a new `GtkFileChooserWidget` Open or save mode for the widget Whether search mode is enabled. Whether to show the time. The subtitle of the file chooser widget. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser show the user's Desktop folder in the file list. The default binding for this signal is <kbd>Alt</kbd>-<kbd>D</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser go to a child of the current folder in the file hierarchy. The subfolder that will be used is displayed in the path bar widget of the file chooser. For example, if the path bar is showing "/foo/bar/baz", with bar currently displayed, then this will cause the file chooser to switch to the "baz" subfolder. The default binding for this signal is <kbd>Alt</kbd>-<kbd>Down</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser show the user's home folder in the file list. The default binding for this signal is <kbd>Alt</kbd>-<kbd>Home</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser show a "Location" prompt which the user can use to manually type the name of the file he wishes to select. The default bindings for this signal are <kbd>Control</kbd>-<kbd>L</kbd> with a @path string of "" (the empty string). It is also bound to <kbd>/</kbd> with a @path string of "`/`" (a slash): this lets you type `/` and immediately type a path name. On Unix systems, this is bound to <kbd>~</kbd> (tilde) with a @path string of "~" itself for access to home directories. a string that gets put in the text entry for the file name Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser show a "Location" prompt when the user pastes into a `GtkFileChooserWidget`. The default binding for this signal is <kbd>Control</kbd>-<kbd>V</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to toggle the visibility of a "Location" prompt which the user can use to manually type the name of the file he wishes to select. The default binding for this signal is <kbd>Control</kbd>-<kbd>L</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to move the focus to the places sidebar. The default binding for this signal is <kbd>Alt</kbd>-<kbd>P</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser switch to the bookmark specified in the @bookmark_index parameter. For example, if you have three bookmarks, you can pass 0, 1, 2 to this signal to switch to each of them, respectively. The default binding for this signal is <kbd>Alt</kbd>-<kbd>1</kbd>, <kbd>Alt</kbd>-<kbd>2</kbd>, etc. until <kbd>Alt</kbd>-<kbd>0</kbd>. Note that in the default binding, that <kbd>Alt</kbd>-<kbd>1</kbd> is actually defined to switch to the bookmark at index 0, and so on successively. the number of the bookmark to switch to Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser show the Recent location. The default binding for this signal is <kbd>Alt</kbd>-<kbd>R</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser show the search entry. The default binding for this signal is <kbd>Alt</kbd>-<kbd>S</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser display hidden files. The default binding for this signal is <kbd>Control</kbd>-<kbd>H</kbd>. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). This is used to make the file chooser go to the parent of the current folder in the file hierarchy. The default binding for this signal is <kbd>Alt</kbd>-<kbd>Up</kbd>. A `GtkFileDialog` object collects the arguments that are needed to present a file chooser dialog to the user, such as a title for the dialog and whether it should be modal. The dialog is shown with [method@Gtk.FileDialog.open], [method@Gtk.FileDialog.save], etc. Creates a new `GtkFileDialog` object. the new `GtkFileDialog` Retrieves the text used by the dialog on its accept button. the label shown on the file chooser's accept button. a `GtkFileDialog` Gets the filter that will be selected by default in the file chooser dialog. the current filter a `GtkFileDialog` Gets the filters that will be offered to the user in the file chooser dialog. the filters, as a `GListModel` of `GtkFileFilters` a `GtkFileDialog` Gets the file that will be initially selected in the file chooser dialog. the file a `GtkFileDialog` Gets the folder that will be set as the initial folder in the file chooser dialog. the folder a `GtkFileDialog` Gets the name for the file that should be initially set. the name a `GtkFileDialog` Returns whether the file chooser dialog blocks interaction with the parent window while it is presented. `TRUE` if the file chooser dialog is modal a `GtkFileDialog` Returns the title that will be shown on the file chooser dialog. the title a `GtkFileDialog` This function initiates a file selection operation by presenting a file chooser dialog to the user. The @callback will be called when the dialog is dismissed. a `GtkFileDialog` the parent `GtkWindow` a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileDialog.open] call and returns the resulting file. the file that was selected. Otherwise, `NULL` is returned and @error is set a `GtkFileDialog` a `GAsyncResult` This function initiates a multi-file selection operation by presenting a file chooser dialog to the user. The file chooser will initially be opened in the directory [property@Gtk.FileDialog:initial-folder]. The @callback will be called when the dialog is dismissed. a `GtkFileDialog` the parent `GtkWindow` a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileDialog.open] call and returns the resulting files in a `GListModel`. the file that was selected, as a `GListModel` of `GFiles`. Otherwise, `NULL` is returned and @error is set a `GtkFileDialog` a `GAsyncResult` This function initiates a file save operation by presenting a file chooser dialog to the user. The @callback will be called when the dialog is dismissed. a `GtkFileDialog` the parent `GtkWindow` a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileDialog.save] call and returns the resulting file. the file that was selected. Otherwise, `NULL` is returned and @error is set a `GtkFileDialog` a `GAsyncResult` This function initiates a directory selection operation by presenting a file chooser dialog to the user. If you pass @initial_folder, the file chooser will initially be opened in the parent directory of that folder, otherwise, it will be in the directory [property@Gtk.FileDialog:initial-folder]. The @callback will be called when the dialog is dismissed. a `GtkFileDialog` the parent `GtkWindow` a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileDialog.select_folder] call and returns the resulting file. the file that was selected. Otherwise, `NULL` is returned and @error is set a `GtkFileDialog` a `GAsyncResult` This function initiates a multi-directory selection operation by presenting a file chooser dialog to the user. The file chooser will initially be opened in the directory [property@Gtk.FileDialog:initial-folder]. The @callback will be called when the dialog is dismissed. a `GtkFileDialog` the parent `GtkWindow` a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileDialog.select_multiple_folders] call and returns the resulting files in a `GListModel`. the file that was selected, as a `GListModel` of `GFiles`. Otherwise, `NULL` is returned and @error is set a `GtkFileDialog` a `GAsyncResult` Sets the label shown on the file chooser's accept button. Leaving the accept label unset or setting it as `NULL` will fall back to a default label, depending on what API is used to launch the file dialog. a `GtkFileDialog` the new accept label Sets the filter that will be selected by default in the file chooser dialog. If set to %NULL, the first item in [property@Gtk.FileDialog:filters] will be used as the default filter. If that list is empty, the dialog will be unfiltered. a `GtkFileDialog` a `GtkFileFilter` Sets the filters that will be offered to the user in the file chooser dialog. a `GtkFileDialog` a `GListModel` of `GtkFileFilters` Sets the file that will be initially selected in the file chooser dialog. This function is a shortcut for calling both gtk_file_dialog_set_initial_folder() and gtk_file_dialog_set_initial_name() with the directory and name of @file respectively. a `GtkFileDialog` a `GFile` Sets the folder that will be set as the initial folder in the file chooser dialog. a `GtkFileDialog` a `GFile` Sets the name for the file that should be initially set. For saving dialogs, this will usually be pre-entered into the name field. If a file with this name already exists in the directory set via [property@Gtk.FileDialog:initial-folder], the dialog should preselect it. a `GtkFileDialog` a UTF8 string Sets whether the file chooser dialog blocks interaction with the parent window while it is presented. a `GtkFileDialog` the new value Sets the title that will be shown on the file chooser dialog. a `GtkFileDialog` the new title Label for the file chooser's accept button. The default filter, that is, the filter that is initially active in the file chooser dialog. If the default filter is %NULL, the first filter of [property@Gtk.FileDialog:filters] is used as the default filter. If that property contains no filter, the dialog will be unfiltered. If [property@Gtk.FileDialog:filters] is not %NULL, the default filter should be part of the list. If it is not, the dialog may choose to not make it available. The list of filters. See [property@Gtk.FileDialog:default-filter] about how those two properties interact. The initial file, that is, the file that is initially selected in the file chooser dialog This is a utility property that sets both [property@Gtk.FileDialog:initial-folder] and [property@Gtk.FileDialog:initial-name]. The initial folder, that is, the directory that is initially opened in the file chooser dialog The initial name, that is, the filename that is initially selected in the file chooser dialog. Whether the file chooser dialog is modal. A title that may be shown on the file chooser dialog. `GtkFileFilter` filters files by name or mime type. `GtkFileFilter` can be used to restrict the files being shown in a `GtkFileChooser`. Files can be filtered based on their name (with [method@Gtk.FileFilter.add_pattern] or [method@Gtk.FileFilter.add_suffix]) or on their mime type (with [method@Gtk.FileFilter.add_mime_type]). Filtering by mime types handles aliasing and subclassing of mime types; e.g. a filter for text/plain also matches a file with mime type application/rtf, since application/rtf is a subclass of text/plain. Note that `GtkFileFilter` allows wildcards for the subtype of a mime type, so you can e.g. filter for image/\*. Normally, file filters are used by adding them to a `GtkFileChooser` (see [method@Gtk.FileChooser.add_filter]), but it is also possible to manually use a file filter on any [class@Gtk.FilterListModel] containing `GFileInfo` objects. # GtkFileFilter as GtkBuildable The `GtkFileFilter` implementation of the `GtkBuildable` interface supports adding rules using the `<mime-types>` and `<patterns>` and `<suffixes>` elements and listing the rules within. Specifying a `<mime-type>` or `<pattern>` or `<suffix>` has the same effect as as calling [method@Gtk.FileFilter.add_mime_type] or [method@Gtk.FileFilter.add_pattern] or [method@Gtk.FileFilter.add_suffix]. An example of a UI definition fragment specifying `GtkFileFilter` rules: ```xml <object class="GtkFileFilter"> <property name="name" translatable="yes">Text and Images</property> <mime-types> <mime-type>text/plain</mime-type> <mime-type>image/ *</mime-type> </mime-types> <patterns> <pattern>*.txt</pattern> </patterns> <suffixes> <suffix>png</suffix> </suffixes> </object> ``` Creates a new `GtkFileFilter` with no rules added to it. Such a filter doesn’t accept any files, so is not particularly useful until you add rules with [method@Gtk.FileFilter.add_mime_type], [method@Gtk.FileFilter.add_pattern], [method@Gtk.FileFilter.add_suffix] or [method@Gtk.FileFilter.add_pixbuf_formats]. To create a filter that accepts any file, use: ```c GtkFileFilter *filter = gtk_file_filter_new (); gtk_file_filter_add_pattern (filter, "*"); ``` a new `GtkFileFilter` Deserialize a file filter from a `GVariant`. The variant must be in the format produced by [method@Gtk.FileFilter.to_gvariant]. a new `GtkFileFilter` object an `a{sv}` `GVariant` Adds a rule allowing a given mime type to @filter. A `GtkFileFilter` name of a MIME type Adds a rule allowing a shell style glob to a filter. Note that it depends on the platform whether pattern matching ignores case or not. On Windows, it does, on other platforms, it doesn't. a `GtkFileFilter` a shell style glob Adds a rule allowing image files in the formats supported by GdkPixbuf. This is equivalent to calling [method@Gtk.FileFilter.add_mime_type] for all the supported mime types. a `GtkFileFilter` Adds a suffix match rule to a filter. This is similar to adding a match for the pattern "*.@suffix". In contrast to pattern matches, suffix matches are *always* case-insensitive. a `GtkFileFilter` filename suffix to match Gets the attributes that need to be filled in for the `GFileInfo` passed to this filter. This function will not typically be used by applications; it is intended principally for use in the implementation of `GtkFileChooser`. the attributes a `GtkFileFilter` Gets the human-readable name for the filter. See [method@Gtk.FileFilter.set_name]. The human-readable name of the filter a `GtkFileFilter` Sets a human-readable name of the filter. This is the string that will be displayed in the file chooser if there is a selectable list of filters. a `GtkFileFilter` the human-readable-name for the filter, or %NULL to remove any existing name. Serialize a file filter to an `a{sv}` variant. a new, floating, `GVariant` a `GtkFileFilter` The MIME types that this filter matches. The human-readable name of the filter. This is the string that will be displayed in the file chooser user interface if there is a selectable list of filters. The patterns that this filter matches. The suffixes that this filter matches. A `GtkFileLauncher` object collects the arguments that are needed to open a file with an application. Depending on system configuration, user preferences and available APIs, this may or may not show an app chooser dialog or launch the default application right away. The operation is started with the [method@Gtk.FileLauncher.launch] function. To launch uris that don't represent files, use [class@Gtk.UriLauncher]. Creates a new `GtkFileLauncher` object. the new `GtkFileLauncher` the file to open Returns whether to ask the user to choose an app for opening the file. `TRUE` if always asking for app a `GtkFileLauncher` Gets the file that will be opened. the file a `GtkFileLauncher` Returns whether to make the file writable for the handler. `TRUE` if the file will be made writable a `GtkFileLauncher` Launch an application to open the file. This may present an app chooser dialog to the user. a `GtkFileLauncher` the parent `GtkWindow` a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileLauncher.launch] call and returns the result. `TRUE` if an application was launched, or `FALSE` and @error is set a `GtkFileLauncher` a `GAsyncResult` Launch a file manager to show the file in its parent directory. This is only supported native files. It will fail if @file is e.g. a http:// uri. a `GtkFileLauncher` the parent `GtkWindow` a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FileLauncher.open_containing_folder] call and returns the result. `TRUE` if an application was launched, or `FALSE` and @error is set a `GtkFileLauncher` a `GAsyncResult` Sets whether to awlays ask the user to choose an app for opening the file. If `FALSE`, the file might be opened with a default app or the previous choice. a `GtkFileLauncher` a `gboolean` Sets the file that will be opened. a `GtkFileLauncher` a `GFile` Sets whether to make the file writable for the handler. a `GtkFileLauncher` a `gboolean` Whether to ask the user to choose an app for opening the file. If `FALSE`, the file might be opened with a default app or the previous choice. The file to launch. Whether to make the file writable for the handler. A `GtkFilter` object describes the filtering to be performed by a [class@Gtk.FilterListModel]. The model will use the filter to determine if it should include items or not by calling [method@Gtk.Filter.match] for each item and only keeping the ones that the function returns %TRUE for. Filters may change what items they match through their lifetime. In that case, they will emit the [signal@Gtk.Filter::changed] signal to notify that previous filter results are no longer valid and that items should be checked again via [method@Gtk.Filter.match]. GTK provides various pre-made filter implementations for common filtering operations. These filters often include properties that can be linked to various widgets to easily allow searches. However, in particular for large lists or complex search methods, it is also possible to subclass `GtkFilter` and provide one's own filter. Gets the known strictness of @filters. If the strictness is not known, %GTK_FILTER_MATCH_SOME is returned. This value may change after emission of the [signal@Gtk.Filter::changed] signal. This function is meant purely for optimization purposes, filters can choose to omit implementing it, but `GtkFilterListModel` uses it. the strictness of @self a `GtkFilter` Checks if the given @item is matched by the filter or not. %TRUE if the filter matches the item and a filter model should keep it, %FALSE if not. a `GtkFilter` The item to check Notifies all users of the filter that it has changed. This emits the [signal@Gtk.Filter::changed] signal. Users of the filter should then check items again via [method@Gtk.Filter.match]. Depending on the @change parameter, not all items need to be changed, but only some. Refer to the [enum@Gtk.FilterChange] documentation for details. This function is intended for implementers of `GtkFilter` subclasses and should not be called from other functions. a `GtkFilter` How the filter changed Gets the known strictness of @filters. If the strictness is not known, %GTK_FILTER_MATCH_SOME is returned. This value may change after emission of the [signal@Gtk.Filter::changed] signal. This function is meant purely for optimization purposes, filters can choose to omit implementing it, but `GtkFilterListModel` uses it. the strictness of @self a `GtkFilter` Checks if the given @item is matched by the filter or not. %TRUE if the filter matches the item and a filter model should keep it, %FALSE if not. a `GtkFilter` The item to check Emitted whenever the filter changed. Users of the filter should then check items again via [method@Gtk.Filter.match]. `GtkFilterListModel` handles this signal automatically. Depending on the @change parameter, not all items need to be checked, but only some. Refer to the [enum@Gtk.FilterChange] documentation for details. how the filter changed Describes changes in a filter in more detail and allows objects using the filter to optimize refiltering items. If you are writing an implementation and are not sure which value to pass, %GTK_FILTER_CHANGE_DIFFERENT is always a correct choice. The filter change cannot be described with any of the other enumeration values. The filter is less strict than it was before: All items that it used to return %TRUE for still return %TRUE, others now may, too. The filter is more strict than it was before: All items that it used to return %FALSE for still return %FALSE, others now may, too. %TRUE if the filter matches the item and a filter model should keep it, %FALSE if not. a `GtkFilter` The item to check the strictness of @self a `GtkFilter` `GtkFilterListModel` is a list model that filters the elements of the underlying model according to a `GtkFilter`. It hides some elements from the other model according to criteria given by a `GtkFilter`. The model can be set up to do incremental filtering, so that filtering long lists doesn't block the UI. See [method@Gtk.FilterListModel.set_incremental] for details. `GtkFilterListModel` passes through sections from the underlying model. Creates a new `GtkFilterListModel` that will filter @model using the given @filter. a new `GtkFilterListModel` the model to sort filter Gets the `GtkFilter` currently set on @self. The filter currently in use a `GtkFilterListModel` Returns whether incremental filtering is enabled. See [method@Gtk.FilterListModel.set_incremental]. %TRUE if incremental filtering is enabled a `GtkFilterListModel` Gets the model currently filtered or %NULL if none. The model that gets filtered a `GtkFilterListModel` Returns the number of items that have not been filtered yet. You can use this value to check if @self is busy filtering by comparing the return value to 0 or you can compute the percentage of the filter remaining by dividing the return value by the total number of items in the underlying model: ```c pending = gtk_filter_list_model_get_pending (self); model = gtk_filter_list_model_get_model (self); percentage = pending / (double) g_list_model_get_n_items (model); ``` If no filter operation is ongoing - in particular when [property@Gtk.FilterListModel:incremental] is %FALSE - this function returns 0. The number of items not yet filtered a `GtkFilterListModel` Sets the filter used to filter items. a `GtkFilterListModel` filter to use Sets the filter model to do an incremental sort. When incremental filtering is enabled, the `GtkFilterListModel` will not run filters immediately, but will instead queue an idle handler that incrementally filters the items and adds them to the list. This of course means that items are not instantly added to the list, but only appear incrementally. When your filter blocks the UI while filtering, you might consider turning this on. Depending on your model and filters, this may become interesting around 10,000 to 100,000 items. By default, incremental filtering is disabled. See [method@Gtk.FilterListModel.get_pending] for progress information about an ongoing incremental filtering operation. a `GtkFilterListModel` %TRUE to enable incremental filtering Sets the model to be filtered. Note that GTK makes no effort to ensure that @model conforms to the item type of @self. It assumes that the caller knows what they are doing and have set up an appropriate filter to ensure that item types match. a `GtkFilterListModel` The model to be filtered The filter for this model. If the model should filter items incrementally. The type of items. See [method@Gio.ListModel.get_item_type]. The model being filtered. The number of items. See [method@Gio.ListModel.get_n_items]. Number of items not yet filtered. Describes the known strictness of a filter. Note that for filters where the strictness is not known, %GTK_FILTER_MATCH_SOME is always an acceptable value, even if a filter does match all or no items. The filter matches some items, gtk_filter_match() may return %TRUE or %FALSE The filter does not match any item, gtk_filter_match() will always return %FALSE. The filter matches all items, gtk_filter_match() will alays return %TRUE. `GtkFixed` places its child widgets at fixed positions and with fixed sizes. `GtkFixed` performs no automatic layout management. For most applications, you should not use this container! It keeps you from having to learn about the other GTK containers, but it results in broken applications. With `GtkFixed`, the following things will result in truncated text, overlapping widgets, and other display bugs: - Themes, which may change widget sizes. - Fonts other than the one you used to write the app will of course change the size of widgets containing text; keep in mind that users may use a larger font because of difficulty reading the default, or they may be using a different OS that provides different fonts. - Translation of text into other languages changes its size. Also, display of non-English text will use a different font in many cases. In addition, `GtkFixed` does not pay attention to text direction and thus may produce unwanted results if your app is run under right-to-left languages such as Hebrew or Arabic. That is: normally GTK will order containers appropriately for the text direction, e.g. to put labels to the right of the thing they label when using an RTL language, but it can’t do that with `GtkFixed`. So if you need to reorder widgets depending on the text direction, you would need to manually detect it and adjust child positions accordingly. Finally, fixed positioning makes it kind of annoying to add/remove UI elements, since you have to reposition all the other elements. This is a long-term maintenance problem for your application. If you know none of these things are an issue for your application, and prefer the simplicity of `GtkFixed`, by all means use the widget. But you should be aware of the tradeoffs. Creates a new `GtkFixed`. a new `GtkFixed`. Retrieves the translation transformation of the given child `GtkWidget` in the `GtkFixed`. See also: [method@Gtk.Fixed.get_child_transform]. a `GtkFixed` a child of @fixed the horizontal position of the @widget the vertical position of the @widget Retrieves the transformation for @widget set using gtk_fixed_set_child_transform(). a `GskTransform` a `GtkFixed` a `GtkWidget`, child of @fixed Sets a translation transformation to the given @x and @y coordinates to the child @widget of the `GtkFixed`. a `GtkFixed` the child widget the horizontal position to move the widget to the vertical position to move the widget to Adds a widget to a `GtkFixed` at the given position. a `GtkFixed` the widget to add the horizontal position to place the widget at the vertical position to place the widget at Removes a child from @fixed. a `GtkFixed` the child widget to remove Sets the transformation for @widget. This is a convenience function that retrieves the [class@Gtk.FixedLayoutChild] instance associated to @widget and calls [method@Gtk.FixedLayoutChild.set_transform]. a `GtkFixed` a `GtkWidget`, child of @fixed the transformation assigned to @widget to reset @widget's transform `GtkFixedLayout` is a layout manager which can place child widgets at fixed positions. Most applications should never use this layout manager; fixed positioning and sizing requires constant recalculations on where children need to be positioned and sized. Other layout managers perform this kind of work internally so that application developers don't need to do it. Specifically, widgets positioned in a fixed layout manager will need to take into account: - Themes, which may change widget sizes. - Fonts other than the one you used to write the app will of course change the size of widgets containing text; keep in mind that users may use a larger font because of difficulty reading the default, or they may be using a different OS that provides different fonts. - Translation of text into other languages changes its size. Also, display of non-English text will use a different font in many cases. In addition, `GtkFixedLayout` does not pay attention to text direction and thus may produce unwanted results if your app is run under right-to-left languages such as Hebrew or Arabic. That is: normally GTK will order containers appropriately depending on the text direction, e.g. to put labels to the right of the thing they label when using an RTL language; `GtkFixedLayout` won't be able to do that for you. Finally, fixed positioning makes it kind of annoying to add/remove UI elements, since you have to reposition all the other elements. This is a long-term maintenance problem for your application. Creates a new `GtkFixedLayout`. the newly created `GtkFixedLayout` `GtkLayoutChild` subclass for children in a `GtkFixedLayout`. Retrieves the transformation of the child. a `GskTransform` a `GtkFixedLayoutChild` Sets the transformation of the child of a `GtkFixedLayout`. a `GtkFixedLayoutChild` a `GskTransform` The transform of the child. `GtkFlattenListModel` is a list model that concatenates other list models. `GtkFlattenListModel` takes a list model containing list models, and flattens it into a single model. Each list model becomes a section in the single model. Creates a new `GtkFlattenListModel` that flattens @list. a new `GtkFlattenListModel` the model to be flattened Gets the model set via gtk_flatten_list_model_set_model(). The model flattened by @self a `GtkFlattenListModel` Returns the model containing the item at the given position. the model containing the item at @position a `GtkFlattenListModel` a position Sets a new model to be flattened. a `GtkFlattenListModel` the new model The type of items. See [method@Gio.ListModel.get_item_type]. The model being flattened. The number of items. See [method@Gio.ListModel.get_n_items]. A `GtkFlowBox` puts child widgets in reflowing grid. For instance, with the horizontal orientation, the widgets will be arranged from left to right, starting a new row under the previous row when necessary. Reducing the width in this case will require more rows, so a larger height will be requested. Likewise, with the vertical orientation, the widgets will be arranged from top to bottom, starting a new column to the right when necessary. Reducing the height will require more columns, so a larger width will be requested. The size request of a `GtkFlowBox` alone may not be what you expect; if you need to be able to shrink it along both axes and dynamically reflow its children, you may have to wrap it in a `GtkScrolledWindow` to enable that. The children of a `GtkFlowBox` can be dynamically sorted and filtered. Although a `GtkFlowBox` must have only `GtkFlowBoxChild` children, you can add any kind of widget to it via [method@Gtk.FlowBox.insert], and a `GtkFlowBoxChild` widget will automatically be inserted between the box and the widget. Also see [class@Gtk.ListBox]. # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.FlowBox::move-cursor] - [signal@Gtk.FlowBox::select-all] - [signal@Gtk.FlowBox::toggle-cursor-child] - [signal@Gtk.FlowBox::unselect-all] # CSS nodes ``` flowbox ├── flowboxchild │ ╰── <child> ├── flowboxchild │ ╰── <child> ┊ ╰── [rubberband] ``` `GtkFlowBox` uses a single CSS node with name flowbox. `GtkFlowBoxChild` uses a single CSS node with name flowboxchild. For rubberband selection, a subnode with name rubberband is used. # Accessibility `GtkFlowBox` uses the %GTK_ACCESSIBLE_ROLE_GRID role, and `GtkFlowBoxChild` uses the %GTK_ACCESSIBLE_ROLE_GRID_CELL role. Creates a `GtkFlowBox`. a new `GtkFlowBox` Adds @child to the end of @self. If a sort function is set, the widget will actually be inserted at the calculated position. See also: [method@Gtk.FlowBox.insert]. a `GtkFlowBox the `GtkWidget` to add Binds @model to @box. If @box was already bound to a model, that previous binding is destroyed. The contents of @box are cleared and then filled with widgets that represent items from @model. @box is updated whenever @model changes. If @model is %NULL, @box is left empty. It is undefined to add or remove widgets directly (for example, with [method@Gtk.FlowBox.insert]) while @box is bound to a model. Note that using a model is incompatible with the filtering and sorting functionality in `GtkFlowBox`. When using a model, filtering and sorting should be implemented by the model. a `GtkFlowBox` the `GListModel` to be bound to @box a function that creates widgets for items user data passed to @create_widget_func function for freeing @user_data Returns whether children activate on single clicks. %TRUE if children are activated on single click, %FALSE otherwise a `GtkFlowBox` Gets the nth child in the @box. the child widget, which will always be a `GtkFlowBoxChild` or %NULL in case no child widget with the given index exists. a `GtkFlowBox` the position of the child Gets the child in the (@x, @y) position. Both @x and @y are assumed to be relative to the origin of @box. the child widget, which will always be a `GtkFlowBoxChild` or %NULL in case no child widget exists for the given x and y coordinates. a `GtkFlowBox` the x coordinate of the child the y coordinate of the child Gets the horizontal spacing. the horizontal spacing a `GtkFlowBox` Returns whether the box is homogeneous. %TRUE if the box is homogeneous. a `GtkFlowBox` Gets the maximum number of children per line. the maximum number of children per line a `GtkFlowBox` Gets the minimum number of children per line. the minimum number of children per line a `GtkFlowBox` Gets the vertical spacing. the vertical spacing a `GtkFlowBox` Creates a list of all selected children. A `GList` containing the `GtkWidget` for each selected child. Free with g_list_free() when done. a `GtkFlowBox` Gets the selection mode of @box. the `GtkSelectionMode` a `GtkFlowBox` Inserts the @widget into @box at @position. If a sort function is set, the widget will actually be inserted at the calculated position. If @position is -1, or larger than the total number of children in the @box, then the @widget will be appended to the end. a `GtkFlowBox` the `GtkWidget` to add the position to insert @child in Updates the filtering for all children. Call this function when the result of the filter function on the @box is changed due to an external factor. For instance, this would be used if the filter function just looked for a specific search term, and the entry with the string has changed. a `GtkFlowBox` Updates the sorting for all children. Call this when the result of the sort function on @box is changed due to an external factor. a `GtkFlowBox` Adds @child to the start of @self. If a sort function is set, the widget will actually be inserted at the calculated position. See also: [method@Gtk.FlowBox.insert]. a `GtkFlowBox the `GtkWidget` to add Removes a child from @box. a `GtkFlowBox` the child widget to remove Removes all children from @box. This function does nothing if @box is backed by a model. a `GtkFlowBox` Select all children of @box, if the selection mode allows it. a `GtkFlowBox` Selects a single child of @box, if the selection mode allows it. a `GtkFlowBox` a child of @box Calls a function for each selected child. Note that the selection cannot be modified from within this function. a `GtkFlowBox` the function to call for each selected child user data to pass to the function If @single is %TRUE, children will be activated when you click on them, otherwise you need to double-click. a `GtkFlowBox` %TRUE to emit child-activated on a single click Sets the horizontal space to add between children. a `GtkFlowBox` the spacing to use By setting a filter function on the @box one can decide dynamically which of the children to show. For instance, to implement a search function that only shows the children matching the search terms. The @filter_func will be called for each child after the call, and it will continue to be called each time a child changes (via [method@Gtk.FlowBoxChild.changed]) or when [method@Gtk.FlowBox.invalidate_filter] is called. Note that using a filter function is incompatible with using a model (see [method@Gtk.FlowBox.bind_model]). a `GtkFlowBox` callback that lets you filter which children to show user data passed to @filter_func destroy notifier for @user_data Hooks up an adjustment to focus handling in @box. The adjustment is also used for autoscrolling during rubberband selection. See [method@Gtk.ScrolledWindow.get_hadjustment] for a typical way of obtaining the adjustment, and [method@Gtk.FlowBox.set_vadjustment] for setting the vertical adjustment. The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the box. a `GtkFlowBox` an adjustment which should be adjusted when the focus is moved among the descendents of @container Sets whether or not all children of @box are given equal space in the box. a `GtkFlowBox` %TRUE to create equal allotments, %FALSE for variable allotments Sets the maximum number of children to request and allocate space for in @box’s orientation. Setting the maximum number of children per line limits the overall natural size request to be no more than @n_children children long in the given orientation. a `GtkFlowBox` the maximum number of children per line Sets the minimum number of children to line up in @box’s orientation before flowing. a `GtkFlowBox` the minimum number of children per line Sets the vertical space to add between children. a `GtkFlowBox` the spacing to use Sets how selection works in @box. a `GtkFlowBox` the new selection mode By setting a sort function on the @box, one can dynamically reorder the children of the box, based on the contents of the children. The @sort_func will be called for each child after the call, and will continue to be called each time a child changes (via [method@Gtk.FlowBoxChild.changed]) and when [method@Gtk.FlowBox.invalidate_sort] is called. Note that using a sort function is incompatible with using a model (see [method@Gtk.FlowBox.bind_model]). a `GtkFlowBox` the sort function user data passed to @sort_func destroy notifier for @user_data Hooks up an adjustment to focus handling in @box. The adjustment is also used for autoscrolling during rubberband selection. See [method@Gtk.ScrolledWindow.get_vadjustment] for a typical way of obtaining the adjustment, and [method@Gtk.FlowBox.set_hadjustment] for setting the horizontal adjustment. The adjustments have to be in pixel units and in the same coordinate system as the allocation for immediate children of the box. a `GtkFlowBox` an adjustment which should be adjusted when the focus is moved among the descendents of @container Unselect all children of @box, if the selection mode allows it. a `GtkFlowBox` Unselects a single child of @box, if the selection mode allows it. a `GtkFlowBox` a child of @box Whether to accept unpaired release events. Determines whether children can be activated with a single click, or require a double-click. The amount of horizontal space between two children. Determines whether all children should be allocated the same size. The maximum amount of children to request space for consecutively in the given orientation. The minimum number of children to allocate consecutively in the given orientation. Setting the minimum children per line ensures that a reasonably small height will be requested for the overall minimum width of the box. The amount of vertical space between two children. The selection mode used by the flow box. Emitted when the user activates the @box. This is a [keybinding signal](class.SignalAction.html). Emitted when a child has been activated by the user. the child that is activated Emitted when the user initiates a cursor movement. This is a [keybinding signal](class.SignalAction.html). Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifier does not. There are too many key combinations to list them all here. - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move by individual children - <kbd>Home</kbd>, <kbd>End</kbd> move to the ends of the box - <kbd>PgUp</kbd>, <kbd>PgDn</kbd> move vertically by pages %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the granularity of the move, as a `GtkMovementStep` the number of @step units to move whether to extend the selection whether to modify the selection Emitted to select all children of the box, if the selection mode permits it. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal is <kbd>Ctrl</kbd>-<kbd>a</kbd>. Emitted when the set of selected children changes. Use [method@Gtk.FlowBox.selected_foreach] or [method@Gtk.FlowBox.get_selected_children] to obtain the selected children. Emitted to toggle the selection of the child that has the focus. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Ctrl</kbd>-<kbd>Space</kbd>. Emitted to unselect all children of the box, if the selection mode permits it. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal is <kbd>Ctrl</kbd>-<kbd>Shift</kbd>-<kbd>a</kbd>. `GtkFlowBoxChild` is the kind of widget that can be added to a `GtkFlowBox`. Creates a new `GtkFlowBoxChild`. This should only be used as a child of a `GtkFlowBox`. a new `GtkFlowBoxChild` Marks @child as changed, causing any state that depends on this to be updated. This affects sorting and filtering. Note that calls to this method must be in sync with the data used for the sorting and filtering functions. For instance, if the list is mirroring some external data set, and *two* children changed in the external data set when you call gtk_flow_box_child_changed() on the first child, the sort function must only read the new data for the first of the two changed children, otherwise the resorting of the children will be wrong. This generally means that if you don’t fully control the data model, you have to duplicate the data that affects the sorting and filtering functions into the widgets themselves. Another alternative is to call [method@Gtk.FlowBox.invalidate_sort] on any model change, but that is more expensive. a `GtkFlowBoxChild` Gets the child widget of @self. the child widget of @self a `GtkFlowBoxChild` Gets the current index of the @child in its `GtkFlowBox` container. the index of the @child, or -1 if the @child is not in a flow box a `GtkFlowBoxChild` Returns whether the @child is currently selected in its `GtkFlowBox` container. %TRUE if @child is selected a `GtkFlowBoxChild` Sets the child widget of @self. a `GtkFlowBoxChild` the child widget The child widget. Emitted when the user activates a child widget in a `GtkFlowBox`. This can happen either by clicking or double-clicking, or via a keybinding. This is a [keybinding signal](class.SignalAction.html), but it can be used by applications for their own purposes. The default bindings are <kbd>Space</kbd> and <kbd>Enter</kbd>. Called for flow boxes that are bound to a `GListModel`. This function is called for each item that gets added to the model. a `GtkWidget` that represents @item the item from the model for which to create a widget for user data from gtk_flow_box_bind_model() A function that will be called whenever a child changes or is added. It lets you control if the child should be visible or not. %TRUE if the row should be visible, %FALSE otherwise a `GtkFlowBoxChild` that may be filtered user data A function used by gtk_flow_box_selected_foreach(). It will be called on every selected child of the @box. a `GtkFlowBox` a `GtkFlowBoxChild` user data A function to compare two children to determine which should come first. < 0 if @child1 should be before @child2, 0 if they are equal, and > 0 otherwise the first child the second child user data The `GtkFontButton` allows to open a font chooser dialog to change the font.  It is suitable widget for selecting a font in a preference dialog. # CSS nodes ``` fontbutton ╰── button.font ╰── [content] ``` `GtkFontButton` has a single CSS node with name fontbutton which contains a button node with the .font style class. Use [class@Gtk.FontDialogButton] instead Creates a new font picker widget. Use [class@Gtk.FontDialogButton] instead a new font picker widget. Creates a new font picker widget showing the given font. Use [class@Gtk.FontDialogButton] instead a new font picker widget. Name of font to display in font chooser dialog Gets whether the dialog is modal. Use [class@Gtk.FontDialogButton] instead %TRUE if the dialog is modal a `GtkFontButton` Retrieves the title of the font chooser dialog. Use [class@Gtk.FontDialogButton] instead an internal copy of the title string which must not be freed. a `GtkFontButton` Returns whether the selected font is used in the label. Use [class@Gtk.FontDialogButton] instead whether the selected font is used in the label. a `GtkFontButton` Returns whether the selected size is used in the label. Use [class@Gtk.FontDialogButton] instead whether the selected size is used in the label. a `GtkFontButton` Sets whether the dialog should be modal. Use [class@Gtk.FontDialogButton] instead a `GtkFontButton` %TRUE to make the dialog modal Sets the title for the font chooser dialog. Use [class@Gtk.FontDialogButton] instead a `GtkFontButton` a string containing the font chooser dialog title If @use_font is %TRUE, the font name will be written using the selected font. Use [class@Gtk.FontDialogButton] instead a `GtkFontButton` If %TRUE, font name will be written using font chosen. If @use_size is %TRUE, the font name will be written using the selected size. Use [class@Gtk.FontDialogButton] instead a `GtkFontButton` If %TRUE, font name will be written using the selected size. Whether the font chooser dialog should be modal. The title of the font chooser dialog. Whether the buttons label will be drawn in the selected font. Whether the buttons label will use the selected font size. Emitted to when the font button is activated. The `::activate` signal on `GtkFontButton` is an action signal and emitting it causes the button to present its dialog. Emitted when the user selects a font. When handling this signal, use [method@Gtk.FontChooser.get_font] to find out which font was just selected. Note that this signal is only emitted when the user changes the font. If you need to react to programmatic font changes as well, use the notify::font signal. `GtkFontChooser` is an interface that can be implemented by widgets for choosing fonts. In GTK, the main objects that implement this interface are [class@Gtk.FontChooserWidget], [class@Gtk.FontChooserDialog] and [class@Gtk.FontButton]. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead Gets the `PangoFontFace` representing the selected font group details (i.e. family, slant, weight, width, etc). If the selected font is not installed, returns %NULL. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A `PangoFontFace` representing the selected font group details a `GtkFontChooser` Gets the `PangoFontFamily` representing the selected font family. Font families are a collection of font faces. If the selected font is not installed, returns %NULL. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A `PangoFontFamily` representing the selected font family a `GtkFontChooser` Gets the custom font map of this font chooser widget, or %NULL if it does not have one. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `PangoFontMap` a `GtkFontChooser` The selected font size. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A n integer representing the selected font size, or -1 if no font size is selected. a `GtkFontChooser` Adds a filter function that decides which fonts to display in the font chooser. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a `GtkFontFilterFunc` data to pass to @filter function to call to free @data when it is no longer needed Sets a custom font map to use for this font chooser widget. A custom font map can be used to present application-specific fonts instead of or in addition to the normal system fonts. ```c FcConfig *config; PangoFontMap *fontmap; config = FcInitLoadConfigAndFonts (); FcConfigAppFontAddFile (config, my_app_font_file); fontmap = pango_cairo_font_map_new_for_font_type (CAIRO_FONT_TYPE_FT); pango_fc_font_map_set_config (PANGO_FC_FONT_MAP (fontmap), config); gtk_font_chooser_set_font_map (font_chooser, fontmap); ``` Note that other GTK widgets will only be able to use the application-specific font if it is present in the font map they use: ```c context = gtk_widget_get_pango_context (label); pango_context_set_font_map (context, fontmap); ``` Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a `PangoFontMap` Gets the currently-selected font name. Note that this can be a different string than what you set with [method@Gtk.FontChooser.set_font], as the font chooser widget may normalize font names and thus return a string with a different structure. For example, “Helvetica Italic Bold 12” could be normalized to “Helvetica Bold Italic 12”. Use [method@Pango.FontDescription.equal] if you want to compare two font descriptions. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A string with the name of the current font a `GtkFontChooser` Gets the currently-selected font. Note that this can be a different string than what you set with [method@Gtk.FontChooser.set_font], as the font chooser widget may normalize font names and thus return a string with a different structure. For example, “Helvetica Italic Bold 12” could be normalized to “Helvetica Bold Italic 12”. Use [method@Pango.FontDescription.equal] if you want to compare two font descriptions. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A `PangoFontDescription` for the current font a `GtkFontChooser` Gets the `PangoFontFace` representing the selected font group details (i.e. family, slant, weight, width, etc). If the selected font is not installed, returns %NULL. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A `PangoFontFace` representing the selected font group details a `GtkFontChooser` Gets the `PangoFontFamily` representing the selected font family. Font families are a collection of font faces. If the selected font is not installed, returns %NULL. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A `PangoFontFamily` representing the selected font family a `GtkFontChooser` Gets the currently-selected font features. The format of the returned string is compatible with the [CSS font-feature-settings property](https://www.w3.org/TR/css-fonts-4/#font-rend-desc). It can be passed to [func@Pango.AttrFontFeatures.new]. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead the currently selected font features a `GtkFontChooser` Gets the custom font map of this font chooser widget, or %NULL if it does not have one. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `PangoFontMap` a `GtkFontChooser` The selected font size. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead A n integer representing the selected font size, or -1 if no font size is selected. a `GtkFontChooser` Gets the language that is used for font features. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead the currently selected language a `GtkFontChooser` Returns the current level of granularity for selecting fonts. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead the current granularity level a `GtkFontChooser` Gets the text displayed in the preview area. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead the text displayed in the preview area a `GtkFontChooser` Returns whether the preview entry is shown or not. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead %TRUE if the preview entry is shown or %FALSE if it is hidden. a `GtkFontChooser` Adds a filter function that decides which fonts to display in the font chooser. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a `GtkFontFilterFunc` data to pass to @filter function to call to free @data when it is no longer needed Sets the currently-selected font. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a font name like “Helvetica 12” or “Times Bold 18” Sets the currently-selected font from @font_desc. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a `PangoFontDescription` Sets a custom font map to use for this font chooser widget. A custom font map can be used to present application-specific fonts instead of or in addition to the normal system fonts. ```c FcConfig *config; PangoFontMap *fontmap; config = FcInitLoadConfigAndFonts (); FcConfigAppFontAddFile (config, my_app_font_file); fontmap = pango_cairo_font_map_new_for_font_type (CAIRO_FONT_TYPE_FT); pango_fc_font_map_set_config (PANGO_FC_FONT_MAP (fontmap), config); gtk_font_chooser_set_font_map (font_chooser, fontmap); ``` Note that other GTK widgets will only be able to use the application-specific font if it is present in the font map they use: ```c context = gtk_widget_get_pango_context (label); pango_context_set_font_map (context, fontmap); ``` Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a `PangoFontMap` Sets the language to use for font features. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` a language Sets the desired level of granularity for selecting fonts. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` the desired level of granularity Sets the text displayed in the preview area. The @text is used to show how the selected font looks. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` the text to display in the preview area Shows or hides the editable preview entry. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead a `GtkFontChooser` whether to show the editable preview entry or not The font description as a string, e.g. "Sans Italic 12". Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead The font description as a `PangoFontDescription`. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead The selected font features. The format of the string is compatible with CSS and with Pango attributes. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead The language for which the font features were selected. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead The level of granularity to offer for selecting fonts. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead The string with which to preview the font. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead Whether to show an entry to change the preview text. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead Emitted when a font is activated. 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. Use [class@Gtk.FontDialog] and [class@Gtk.FontDialogButton] instead the font name The `GtkFontChooserDialog` widget is a dialog for selecting a font.  `GtkFontChooserDialog` implements the [iface@Gtk.FontChooser] interface and does not provide much API of its own. To create a `GtkFontChooserDialog`, use [ctor@Gtk.FontChooserDialog.new]. # GtkFontChooserDialog as GtkBuildable The `GtkFontChooserDialog` implementation of the `GtkBuildable` interface exposes the buttons with the names “select_button” and “cancel_button”. ## CSS nodes `GtkFontChooserDialog` has a single CSS node with the name `window` and style class `.fontchooser`. Use [class@Gtk.FontDialog] instead Creates a new `GtkFontChooserDialog`. Use [class@Gtk.FontDialog] instead a new `GtkFontChooserDialog` Title of the dialog Transient parent of the dialog A `PangoFontFamily` representing the selected font family a `GtkFontChooser` A `PangoFontFace` representing the selected font group details a `GtkFontChooser` A n integer representing the selected font size, or -1 if no font size is selected. a `GtkFontChooser` a `GtkFontChooser` a `GtkFontFilterFunc` data to pass to @filter function to call to free @data when it is no longer needed a `GtkFontChooser` a `PangoFontMap` a `PangoFontMap` a `GtkFontChooser` Specifies the granularity of font selection that is desired in a `GtkFontChooser`. This enumeration may be extended in the future; applications should ignore unknown values. Allow selecting a font family Allow selecting a specific font face Allow selecting a specific font size Allow changing OpenType font variation axes Allow selecting specific OpenType font features The `GtkFontChooserWidget` widget lets the user select a font. It is used in the `GtkFontChooserDialog` widget to provide a dialog for selecting fonts. To set the font which is initially selected, use [method@Gtk.FontChooser.set_font] or [method@Gtk.FontChooser.set_font_desc]. To get the selected font use [method@Gtk.FontChooser.get_font] or [method@Gtk.FontChooser.get_font_desc]. To change the text which is shown in the preview area, use [method@Gtk.FontChooser.set_preview_text]. # CSS nodes `GtkFontChooserWidget` has a single CSS node with name fontchooser. Direct use of `GtkFontChooserWidget` is deprecated. Creates a new `GtkFontChooserWidget`. Direct use of `GtkFontChooserWidget` is deprecated. a new `GtkFontChooserWidget` A toggle action that can be used to switch to the tweak page of the font chooser widget, which lets the user tweak the OpenType features and variation axes of the selected font. The action will be enabled or disabled depending on whether the selected font has any features or axes. A `GtkFontDialog` object collects the arguments that are needed to present a font chooser dialog to the user, such as a title for the dialog and whether it should be modal. The dialog is shown with the [method@Gtk.FontDialog.choose_font] function or its variants. See [class@Gtk.FontDialogButton] for a convenient control that uses `GtkFontDialog` and presents the results. Creates a new `GtkFontDialog` object. the new `GtkFontDialog` This function initiates a font selection operation by presenting a dialog to the user for selecting a font face (i.e. a font family and style, but not a specific font size). a `GtkFontDialog` the parent `GtkWindow` the initial value a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FontDialog.choose_face] call and returns the resulting font face. the selected font face a `GtkFontDialog` a `GAsyncResult` This function initiates a font selection operation by presenting a dialog to the user for selecting a font family. a `GtkFontDialog` the parent `GtkWindow` the initial value a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FontDialog.choose_family] call and returns the resulting family. This function never returns an error. If the operation is not finished successfully, the value passed as @initial_value to [method@Gtk.FontDialog.choose_family] is returned. the selected family a `GtkFontDialog` a `GAsyncResult` This function initiates a font selection operation by presenting a dialog to the user for selecting a font. If you want to let the user select font features as well, use [method@Gtk.FontDialog.choose_font_and_features] instead. a `GtkFontDialog` the parent `GtkWindow` the font to select initially a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback This function initiates a font selection operation by presenting a dialog to the user for selecting a font and font features. Font features affect how the font is rendered, for example enabling glyph variants or ligatures. a `GtkFontDialog` the parent `GtkWindow` the font to select initially a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.FontDialog.choose_font_and_features] call and returns the resulting font description and font features. `TRUE` if a font was selected. Otherwise `FALSE` is returned and @error is set a `GtkFontDialog` a `GAsyncResult` return location for font description return location for font features return location for the language Finishes the [method@Gtk.FontDialog.choose_font] call and returns the resulting font description. the selected font a `GtkFontDialog` a `GAsyncResult` Returns the filter that decides which fonts to display in the font chooser dialog. the filter a `GtkFontDialog` Returns the fontmap from which fonts are selected, or `NULL` for the default fontmap. the fontmap a `GtkFontDialog` Returns the language for which font features are applied. the language for font features a `GtkFontDialog` Returns whether the font chooser dialog blocks interaction with the parent window while it is presented. `TRUE` if the font chooser dialog is modal a `GtkFontDialog` Returns the title that will be shown on the font chooser dialog. the title a `GtkFontDialog` Adds a filter that decides which fonts to display in the font chooser dialog. The `GtkFilter` must be able to handle both `PangoFontFamily` and `PangoFontFace` objects. a `GtkFontDialog` a `GtkFilter` Sets the fontmap from which fonts are selected. If @fontmap is `NULL`, the default fontmap is used. a `GtkFontDialog` the fontmap Sets the language for which font features are applied. a `GtkFontDialog` the language for font features Sets whether the font chooser dialog blocks interaction with the parent window while it is presented. a `GtkFontDialog` the new value Sets the title that will be shown on the font chooser dialog. a `GtkFontDialog` the new title Sets a filter to restrict what fonts are shown in the font chooser dialog. Sets a custom font map to select fonts from. A custom font map can be used to present application-specific fonts instead of or in addition to the normal system fonts. The language for which the font features are selected. Whether the font chooser dialog is modal. A title that may be shown on the font chooser dialog that is presented by [method@Gtk.FontDialog.choose_font]. The `GtkFontDialogButton` is wrapped around a [class@Gtk.FontDialog] and allows to open a font chooser dialog to change the font.  It is suitable widget for selecting a font in a preference dialog. # CSS nodes ``` fontbutton ╰── button.font ╰── [content] ``` `GtkFontDialogButton` has a single CSS node with name fontbutton which contains a button node with the .font style class. Creates a new `GtkFontDialogButton` with the given `GtkFontDialog`. You can pass `NULL` to this function and set a `GtkFontDialog` later. The button will be insensitive until that happens. the new `GtkFontDialogButton` the `GtkFontDialog` to use Returns the `GtkFontDialog` of @self. the `GtkFontDialog` a `GtkFontDialogButton` Returns the font of the button. This function is what should be used to obtain the font that was chosen by the user. To get informed about changes, listen to "notify::font-desc". the font a `GtkFontDialogButton` Returns the font features of the button. This function is what should be used to obtain the font features that were chosen by the user. To get informed about changes, listen to "notify::font-features". Note that the button will only let users choose font features if [property@Gtk.FontDialogButton:level] is set to `GTK_FONT_LEVEL_FEATURES`. the font features a `GtkFontDialogButton` Returns the language that is used for font features. the language a `GtkFontDialogButton` Returns the level of detail at which this dialog lets the user select fonts. the level of detail a `GtkFontDialogButton Returns whether the selected font is used in the label. whether the selected font is used in the label a `GtkFontDialogButton` Returns whether the selected font size is used in the label. whether the selected font size is used in the label a `GtkFontDialogButton` Sets a `GtkFontDialog` object to use for creating the font chooser dialog that is presented when the user clicks the button. a `GtkFontDialogButton` the new `GtkFontDialog` Sets the font of the button. a `GtkFontDialogButton` the new font Sets the font features of the button. a `GtkFontDialogButton` the font features Sets the language to use for font features. a `GtkFontDialogButton` the new language Sets the level of detail at which this dialog lets the user select fonts. a `GtkFontDialogButton` the level of detail If @use_font is `TRUE`, the font name will be written using the selected font. a `GtkFontDialogButton` If `TRUE`, font name will be written using the chosen font If @use_size is `TRUE`, the font name will be written using the selected font size. a `GtkFontDialogButton` If `TRUE`, font name will be written using the chosen font size The `GtkFontDialog` that contains parameters for the font chooser dialog. The selected font. This property can be set to give the button its initial font, and it will be updated to reflect the users choice in the font chooser dialog. Listen to `notify::font-desc` to get informed about changes to the buttons font. The selected font features. This property will be updated to reflect the users choice in the font chooser dialog. Listen to `notify::font-features` to get informed about changes to the buttons font features. The selected language for font features. This property will be updated to reflect the users choice in the font chooser dialog. Listen to `notify::language` to get informed about changes to the buttons language. The level of detail for the font chooser dialog. Whether the buttons label will be drawn in the selected font. Whether the buttons label will use the selected font size. Emitted when the font dialog button is activated. The `::activate` signal on `GtkFontDialogButton` is an action signal and emitting it causes the button to pop up its dialog. The type of function that is used for deciding what fonts get shown in a `GtkFontChooser`. See [method@Gtk.FontChooser.set_filter_func]. %TRUE if the font should be displayed a `PangoFontFamily` a `PangoFontFace` belonging to @family user data passed to gtk_font_chooser_set_filter_func() The level of granularity for the font selection. Depending on this value, the `PangoFontDescription` that is returned by [method@Gtk.FontDialogButton.get_font_desc] will have more or less fields set. Select a font family Select a font face (i.e. a family and a style) Select a font (i.e. a face with a size, and possibly font variations) Select a font and font features Values for the [property@Gtk.Settings:gtk-font-rendering] setting that influence how GTK renders fonts. Set up font rendering automatically, taking factors like screen resolution and scale into account Follow low-level font-related settings when configuring font rendering `GtkFrame` is a widget that surrounds its child with a decorative frame and an optional label.  If present, the label is drawn inside the top edge of the frame. The horizontal position of the label can be controlled with [method@Gtk.Frame.set_label_align]. `GtkFrame` clips its child. You can use this to add rounded corners to widgets, but be aware that it also cuts off shadows. # GtkFrame as GtkBuildable The `GtkFrame` implementation of the `GtkBuildable` interface supports placing a child in the label position by specifying “label” as the “type” attribute of a `<child>` element. A normal content child can be specified without specifying a `<child>` type attribute. An example of a UI definition fragment with GtkFrame: ```xml <object class="GtkFrame"> <child type="label"> <object class="GtkLabel" id="frame_label"/> </child> <child> <object class="GtkEntry" id="frame_content"/> </child> </object> ``` # CSS nodes ``` frame ├── <label widget> ╰── <child> ``` `GtkFrame` has a main CSS node with name “frame”, which is used to draw the visible border. You can set the appearance of the border using CSS properties like “border-style” on this node. # Accessibility `GtkFrame` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. Creates a new `GtkFrame`, with optional label @label. If @label is %NULL, the label is omitted. a new `GtkFrame` widget the text to use as the label of the frame Gets the child widget of @frame. the child widget of @frame a `GtkFrame` Returns the frame labels text. If the frame's label widget is not a `GtkLabel`, %NULL is returned. the text in the label, or %NULL if there was no label widget or the label widget was not a `GtkLabel`. This string is owned by GTK and must not be modified or freed. a `GtkFrame` Retrieves the X alignment of the frame’s label. the frames X alignment a `GtkFrame` Retrieves the label widget for the frame. the label widget a `GtkFrame` Sets the child widget of @frame. a `GtkFrame` the child widget Creates a new `GtkLabel` with the @label and sets it as the frame's label widget. a `GtkFrame` the text to use as the label of the frame Sets the X alignment of the frame widget’s label. The default value for a newly created frame is 0.0. a `GtkFrame` The position of the label along the top edge of the widget. A value of 0.0 represents left alignment; 1.0 represents right alignment. Sets the label widget for the frame. This is the widget that will appear embedded in the top edge of the frame as a title. a `GtkFrame` the new label widget The child widget. Text of the frame's label. Widget to display in place of the usual frame label. The horizontal alignment of the label. The parent class. `GtkGLArea` is a widget that allows drawing with OpenGL.  `GtkGLArea` sets up its own [class@Gdk.GLContext], and creates a custom GL framebuffer that the widget will do GL rendering onto. It also ensures that this framebuffer is the default GL rendering target when rendering. The completed rendering is integrated into the larger GTK scene graph as a texture. In order to draw, you have to connect to the [signal@Gtk.GLArea::render] signal, or subclass `GtkGLArea` and override the GtkGLAreaClass.render virtual function. The `GtkGLArea` widget ensures that the `GdkGLContext` is associated with the widget's drawing area, and it is kept updated when the size and position of the drawing area changes. ## Drawing with GtkGLArea The simplest way to draw using OpenGL commands in a `GtkGLArea` is to create a widget instance and connect to the [signal@Gtk.GLArea::render] signal: The `render()` function will be called when the `GtkGLArea` is ready for you to draw its content: The initial contents of the framebuffer are transparent. ```c static gboolean render (GtkGLArea *area, GdkGLContext *context) { // inside this function it's safe to use GL; the given // GdkGLContext has been made current to the drawable // surface used by the `GtkGLArea` and the viewport has // already been set to be the size of the allocation // we can start by clearing the buffer glClearColor (0, 0, 0, 0); glClear (GL_COLOR_BUFFER_BIT); // draw your object // draw_an_object (); // we completed our drawing; the draw commands will be // flushed at the end of the signal emission chain, and // the buffers will be drawn on the window return TRUE; } void setup_glarea (void) { // create a GtkGLArea instance GtkWidget *gl_area = gtk_gl_area_new (); // connect to the "render" signal g_signal_connect (gl_area, "render", G_CALLBACK (render), NULL); } ``` If you need to initialize OpenGL state, e.g. buffer objects or shaders, you should use the [signal@Gtk.Widget::realize] signal; you can use the [signal@Gtk.Widget::unrealize] signal to clean up. Since the `GdkGLContext` creation and initialization may fail, you will need to check for errors, using [method@Gtk.GLArea.get_error]. An example of how to safely initialize the GL state is: ```c static void on_realize (GtkGLarea *area) { // We need to make the context current if we want to // call GL API gtk_gl_area_make_current (area); // If there were errors during the initialization or // when trying to make the context current, this // function will return a GError for you to catch if (gtk_gl_area_get_error (area) != NULL) return; // You can also use gtk_gl_area_set_error() in order // to show eventual initialization errors on the // GtkGLArea widget itself GError *internal_error = NULL; init_buffer_objects (&error); if (error != NULL) { gtk_gl_area_set_error (area, error); g_error_free (error); return; } init_shaders (&error); if (error != NULL) { gtk_gl_area_set_error (area, error); g_error_free (error); return; } } ``` If you need to change the options for creating the `GdkGLContext` you should use the [signal@Gtk.GLArea::create-context] signal. Creates a new `GtkGLArea` widget. a new `GtkGLArea` class closure for the `GtkGLArea::create-context` signal class closure for the `GtkGLArea::render` signal class closeure for the `GtkGLArea::resize` signal Binds buffers to the framebuffer. Ensures that the @area framebuffer object is made the current draw and read target, and that all the required buffers for the @area are created and bound to the framebuffer. This function is automatically called before emitting the [signal@Gtk.GLArea::render] signal, and doesn't normally need to be called by application code. a `GtkGLArea` Gets the allowed APIs. See [method@Gtk.GLArea.set_allowed_apis]. the allowed APIs a `GtkGLArea` Gets the API that is currently in use. If the GL area has not been realized yet, 0 is returned. the currently used API a `GtkGLArea` Returns whether the area is in auto render mode or not. %TRUE if the @area is auto rendering, %FALSE otherwise a `GtkGLArea` Retrieves the `GdkGLContext` used by @area. the `GdkGLContext` a `GtkGLArea` Gets the current error set on the @area. the `GError` a `GtkGLArea` Returns whether the area has a depth buffer. %TRUE if the @area has a depth buffer, %FALSE otherwise a `GtkGLArea` Returns whether the area has a stencil buffer. %TRUE if the @area has a stencil buffer, %FALSE otherwise a `GtkGLArea` Retrieves the required version of OpenGL. See [method@Gtk.GLArea.set_required_version]. a `GtkGLArea` return location for the required major version return location for the required minor version Returns whether the `GtkGLArea` should use OpenGL ES. See [method@Gtk.GLArea.set_use_es]. Use [method@Gtk.GLArea.get_api] %TRUE if the `GtkGLArea` should create an OpenGL ES context and %FALSE otherwise a `GtkGLArea` Ensures that the `GdkGLContext` used by @area is associated with the `GtkGLArea`. This function is automatically called before emitting the [signal@Gtk.GLArea::render] signal, and doesn't normally need to be called by application code. a `GtkGLArea` Marks the currently rendered data (if any) as invalid, and queues a redraw of the widget. This ensures that the [signal@Gtk.GLArea::render] signal is emitted during the draw. This is only needed when [method@Gtk.GLArea.set_auto_render] has been called with a %FALSE value. The default behaviour is to emit [signal@Gtk.GLArea::render] on each draw. a `GtkGLArea` Sets the allowed APIs to create a context with. You should check [property@Gtk.GLArea:api] before drawing with either API. By default, all APIs are allowed. a `GtkGLArea` the allowed APIs Sets whether the `GtkGLArea` is in auto render mode. If @auto_render is %TRUE the [signal@Gtk.GLArea::render] signal will be emitted every time the widget draws. This is the default and is useful if drawing the widget is faster. If @auto_render is %FALSE the data from previous rendering is kept around and will be used for drawing the widget the next time, unless the window is resized. In order to force a rendering [method@Gtk.GLArea.queue_render] must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw. a `GtkGLArea` a boolean Sets an error on the area which will be shown instead of the GL rendering. This is useful in the [signal@Gtk.GLArea::create-context] signal if GL context creation fails. a `GtkGLArea` a new `GError`, or %NULL to unset the error Sets whether the `GtkGLArea` should use a depth buffer. If @has_depth_buffer is %TRUE the widget will allocate and enable a depth buffer for the target framebuffer. Otherwise there will be none. a `GtkGLArea` %TRUE to add a depth buffer Sets whether the `GtkGLArea` should use a stencil buffer. If @has_stencil_buffer is %TRUE the widget will allocate and enable a stencil buffer for the target framebuffer. Otherwise there will be none. a `GtkGLArea` %TRUE to add a stencil buffer Sets the required version of OpenGL to be used when creating the context for the widget. This function must be called before the area has been realized. a `GtkGLArea` the major version the minor version Sets whether the @area should create an OpenGL or an OpenGL ES context. You should check the capabilities of the `GdkGLContext` before drawing with either API. Use [method@Gtk.GLArea.set_allowed_apis] a `GtkGLArea` whether to use OpenGL or OpenGL ES The allowed APIs. The API currently in use. If set to %TRUE the ::render signal will be emitted every time the widget draws. This is the default and is useful if drawing the widget is faster. If set to %FALSE the data from previous rendering is kept around and will be used for drawing the widget the next time, unless the window is resized. In order to force a rendering [method@Gtk.GLArea.queue_render] must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw. The `GdkGLContext` used by the `GtkGLArea` widget. The `GtkGLArea` widget is responsible for creating the `GdkGLContext` instance. If you need to render with other kinds of buffers (stencil, depth, etc), use render buffers. If set to %TRUE the widget will allocate and enable a depth buffer for the target framebuffer. Setting this property will enable GL's depth testing as a side effect. If you don't need depth testing, you should call `glDisable(GL_DEPTH_TEST)` in your `GtkGLArea::render` handler. If set to %TRUE the widget will allocate and enable a stencil buffer for the target framebuffer. If set to %TRUE the widget will try to create a `GdkGLContext` using OpenGL ES instead of OpenGL. Use [property@Gtk.GLArea:allowed-apis] Emitted when the widget is being realized. This allows you to override how the GL context is created. This is useful when you want to reuse an existing GL context, or if you want to try creating different kinds of GL options. If context creation fails then the signal handler can use [method@Gtk.GLArea.set_error] to register a more detailed error of how the construction failed. a newly created `GdkGLContext`; the `GtkGLArea` widget will take ownership of the returned value. Emitted every time the contents of the `GtkGLArea` should be redrawn. The @context is bound to the @area prior to emitting this function, and the buffers are painted to the window once the emission terminates. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. the `GdkGLContext` used by @area Emitted once when the widget is realized, and then each time the widget is changed while realized. This is useful in order to keep GL state up to date with the widget size, like for instance camera properties which may depend on the width/height ratio. The GL context for the area is guaranteed to be current when this signal is emitted. The default handler sets up the GL viewport. the width of the viewport the height of the viewport The `GtkGLAreaClass` structure contains only private data. class closure for the `GtkGLArea::render` signal class closeure for the `GtkGLArea::resize` signal class closure for the `GtkGLArea::create-context` signal `GtkGesture` is the base class for gesture recognition. Although `GtkGesture` is quite generalized to serve as a base for multi-touch gestures, it is suitable to implement single-touch and pointer-based gestures (using the special %NULL `GdkEventSequence` value for these). The number of touches that a `GtkGesture` need to be recognized is controlled by the [property@Gtk.Gesture:n-points] property, if a gesture is keeping track of less or more than that number of sequences, it won't check whether the gesture is recognized. As soon as the gesture has the expected number of touches, it will check regularly if it is recognized, the criteria to consider a gesture as "recognized" is left to `GtkGesture` subclasses. A recognized gesture will then emit the following signals: - [signal@Gtk.Gesture::begin] when the gesture is recognized. - [signal@Gtk.Gesture::update], whenever an input event is processed. - [signal@Gtk.Gesture::end] when the gesture is no longer recognized. ## Event propagation In order to receive events, a gesture needs to set a propagation phase through [method@Gtk.EventController.set_propagation_phase]. In the capture phase, events are propagated from the toplevel down to the target widget, and gestures that are attached to containers above the widget get a chance to interact with the event before it reaches the target. In the bubble phase, events are propagated up from the target widget to the toplevel, and gestures that are attached to containers above the widget get a chance to interact with events that have not been handled yet. ## States of a sequence Whenever input interaction happens, a single event may trigger a cascade of `GtkGesture`s, both across the parents of the widget receiving the event and in parallel within an individual widget. It is a responsibility of the widgets using those gestures to set the state of touch sequences accordingly in order to enable cooperation of gestures around the `GdkEventSequence`s triggering those. Within a widget, gestures can be grouped through [method@Gtk.Gesture.group]. Grouped gestures synchronize the state of sequences, so calling [method@Gtk.Gesture.set_state] on one will effectively propagate the state throughout the group. By default, all sequences start out in the %GTK_EVENT_SEQUENCE_NONE state, sequences in this state trigger the gesture event handler, but event propagation will continue unstopped by gestures. If a sequence enters into the %GTK_EVENT_SEQUENCE_DENIED state, the gesture group will effectively ignore the sequence, letting events go unstopped through the gesture, but the "slot" will still remain occupied while the touch is active. If a sequence enters in the %GTK_EVENT_SEQUENCE_CLAIMED state, the gesture group will grab all interaction on the sequence, by: - Setting the same sequence to %GTK_EVENT_SEQUENCE_DENIED on every other gesture group within the widget, and every gesture on parent widgets in the propagation chain. - Emitting [signal@Gtk.Gesture::cancel] on every gesture in widgets underneath in the propagation chain. - Stopping event propagation after the gesture group handles the event. Note: if a sequence is set early to %GTK_EVENT_SEQUENCE_CLAIMED on %GDK_TOUCH_BEGIN/%GDK_BUTTON_PRESS (so those events are captured before reaching the event widget, this implies %GTK_PHASE_CAPTURE), one similar event will be emulated if the sequence changes to %GTK_EVENT_SEQUENCE_DENIED. This way event coherence is preserved before event propagation is unstopped again. Sequence states can't be changed freely. See [method@Gtk.Gesture.set_state] to know about the possible lifetimes of a `GdkEventSequence`. ## Touchpad gestures On the platforms that support it, `GtkGesture` will handle transparently touchpad gesture events. The only precautions users of `GtkGesture` should do to enable this support are: - If the gesture has %GTK_PHASE_NONE, ensuring events of type %GDK_TOUCHPAD_SWIPE and %GDK_TOUCHPAD_PINCH are handled by the `GtkGesture` If there are touch sequences being currently handled by @gesture, returns %TRUE and fills in @rect with the bounding box containing all active touches. Otherwise, %FALSE will be returned. Note: This function will yield unexpected results on touchpad gestures. Since there is no correlation between physical and pixel distances, these will look as if constrained in an infinitely small area, @rect width and height will thus be 0 regardless of the number of touchpoints. %TRUE if there are active touches, %FALSE otherwise a `GtkGesture` bounding box containing all active touches. If there are touch sequences being currently handled by @gesture, returns %TRUE and fills in @x and @y with the center of the bounding box containing all active touches. Otherwise, %FALSE will be returned. %FALSE if no active touches are present, %TRUE otherwise a `GtkGesture` X coordinate for the bounding box center Y coordinate for the bounding box center Returns the logical `GdkDevice` that is currently operating on @gesture. This returns %NULL if the gesture is not being interacted. a `GdkDevice` a `GtkGesture` Returns all gestures in the group of @gesture The list of `GtkGesture`s, free with g_list_free() a `GtkGesture` Returns the last event that was processed for @sequence. Note that the returned pointer is only valid as long as the @sequence is still interpreted by the @gesture. If in doubt, you should make a copy of the event. The last event from @sequence a `GtkGesture` a `GdkEventSequence` Returns the `GdkEventSequence` that was last updated on @gesture. The last updated sequence a `GtkGesture` If @sequence is currently being interpreted by @gesture, returns %TRUE and fills in @x and @y with the last coordinates stored for that event sequence. The coordinates are always relative to the widget allocation. %TRUE if @sequence is currently interpreted a `GtkGesture` a `GdkEventSequence`, or %NULL for pointer events return location for X axis of the sequence coordinates return location for Y axis of the sequence coordinates Returns the @sequence state, as seen by @gesture. The sequence state in @gesture a `GtkGesture` a `GdkEventSequence` Returns the list of `GdkEventSequences` currently being interpreted by @gesture. A list of `GdkEventSequence`, the list elements are owned by GTK and must not be freed or modified, the list itself must be deleted through g_list_free() a `GtkGesture` Adds @gesture to the same group than @group_gesture. Gestures are by default isolated in their own groups. Both gestures must have been added to the same widget before they can be grouped. When gestures are grouped, the state of `GdkEventSequences` is kept in sync for all of those, so calling [method@Gtk.Gesture.set_sequence_state], on one will transfer the same value to the others. Groups also perform an "implicit grabbing" of sequences, if a `GdkEventSequence` state is set to %GTK_EVENT_SEQUENCE_CLAIMED on one group, every other gesture group attached to the same `GtkWidget` will switch the state for that sequence to %GTK_EVENT_SEQUENCE_DENIED. `GtkGesture` to group @gesture with a `GtkGesture` Returns %TRUE if @gesture is currently handling events corresponding to @sequence. %TRUE if @gesture is handling @sequence, %FALSE otherwise a `GtkGesture` a `GdkEventSequence` Returns %TRUE if the gesture is currently active. A gesture is active while there are touch sequences interacting with it. %TRUE if gesture is active a `GtkGesture` Returns %TRUE if both gestures pertain to the same group. whether the gestures are grouped a `GtkGesture` another `GtkGesture` Returns %TRUE if the gesture is currently recognized. A gesture is recognized if there are as many interacting touch sequences as required by @gesture. %TRUE if gesture is recognized a `GtkGesture` Sets the state of @sequence in @gesture. Sequences start in state %GTK_EVENT_SEQUENCE_NONE, and whenever they change state, they can never go back to that state. Likewise, sequences in state %GTK_EVENT_SEQUENCE_DENIED cannot turn back to a not denied state. With these rules, the lifetime of an event sequence is constrained to the next four: * None * None → Denied * None → Claimed * None → Claimed → Denied Note: Due to event handling ordering, it may be unsafe to set the state on another gesture within a [signal@Gtk.Gesture::begin] signal handler, as the callback might be executed before the other gesture knows about the sequence. A safe way to perform this could be: ```c static void first_gesture_begin_cb (GtkGesture *first_gesture, GdkEventSequence *sequence, gpointer user_data) { gtk_gesture_set_sequence_state (first_gesture, sequence, GTK_EVENT_SEQUENCE_CLAIMED); gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED); } static void second_gesture_begin_cb (GtkGesture *second_gesture, GdkEventSequence *sequence, gpointer user_data) { if (gtk_gesture_get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_CLAIMED) gtk_gesture_set_sequence_state (second_gesture, sequence, GTK_EVENT_SEQUENCE_DENIED); } ``` If both gestures are in the same group, just set the state on the gesture emitting the event, the sequence will be already be initialized to the group's global state when the second gesture processes the event. Use [method@Gtk.Gesture.set_state] %TRUE if @sequence is handled by @gesture, and the state is changed successfully a `GtkGesture` a `GdkEventSequence` the sequence state Sets the state of all sequences that @gesture is currently interacting with. Sequences start in state %GTK_EVENT_SEQUENCE_NONE, and whenever they change state, they can never go back to that state. Likewise, sequences in state %GTK_EVENT_SEQUENCE_DENIED cannot turn back to a not denied state. With these rules, the lifetime of an event sequence is constrained to the next four: * None * None → Denied * None → Claimed * None → Claimed → Denied Note: Due to event handling ordering, it may be unsafe to set the state on another gesture within a [signal@Gtk.Gesture::begin] signal handler, as the callback might be executed before the other gesture knows about the sequence. A safe way to perform this could be: ```c static void first_gesture_begin_cb (GtkGesture *first_gesture, GdkEventSequence *sequence, gpointer user_data) { gtk_gesture_set_state (first_gesture, GTK_EVENT_SEQUENCE_CLAIMED); gtk_gesture_set_state (second_gesture, GTK_EVENT_SEQUENCE_DENIED); } static void second_gesture_begin_cb (GtkGesture *second_gesture, GdkEventSequence *sequence, gpointer user_data) { if (gtk_gesture_get_sequence_state (first_gesture, sequence) == GTK_EVENT_SEQUENCE_CLAIMED) gtk_gesture_set_state (second_gesture, GTK_EVENT_SEQUENCE_DENIED); } ``` If both gestures are in the same group, just set the state on the gesture emitting the event, the sequence will be already be initialized to the group's global state when the second gesture processes the event. %TRUE if the state of at least one sequence was changed successfully a `GtkGesture` the sequence state Separates @gesture into an isolated group. a `GtkGesture` The number of touch points that trigger recognition on this gesture. Emitted when the gesture is recognized. This means the number of touch sequences matches [property@Gtk.Gesture:n-points]. Note: These conditions may also happen when an extra touch (eg. a third touch on a 2-touches gesture) is lifted, in that situation @sequence won't pertain to the current set of active touches, so don't rely on this being true. the `GdkEventSequence` that made the gesture to be recognized Emitted whenever a sequence is cancelled. This usually happens on active touches when [method@Gtk.EventController.reset] is called on @gesture (manually, due to grabs...), or the individual @sequence was claimed by parent widgets' controllers (see [method@Gtk.Gesture.set_sequence_state]). @gesture must forget everything about @sequence as in response to this signal. the `GdkEventSequence` that was cancelled Emitted when @gesture either stopped recognizing the event sequences as something to be handled, or the number of touch sequences became higher or lower than [property@Gtk.Gesture:n-points]. Note: @sequence might not pertain to the group of sequences that were previously triggering recognition on @gesture (ie. a just pressed touch sequence that exceeds [property@Gtk.Gesture:n-points]). This situation may be detected by checking through [method@Gtk.Gesture.handles_sequence]. the `GdkEventSequence` that made gesture recognition to finish Emitted whenever a sequence state changes. See [method@Gtk.Gesture.set_sequence_state] to know more about the expectable sequence lifetimes. the `GdkEventSequence` that was cancelled the new sequence state Emitted whenever an event is handled while the gesture is recognized. @sequence is guaranteed to pertain to the set of active touches. the `GdkEventSequence` that was updated `GtkGestureClick` is a `GtkGesture` implementation for clicks. It is able to recognize multiple clicks on a nearby zone, which can be listened for through the [signal@Gtk.GestureClick::pressed] signal. Whenever time or distance between clicks exceed the GTK defaults, [signal@Gtk.GestureClick::stopped] is emitted, and the click counter is reset. Returns a newly created `GtkGesture` that recognizes single and multiple presses. a newly created `GtkGestureClick` Emitted whenever a button or touch press happens. how many touch/button presses happened with this one The X coordinate, in widget allocation coordinates The Y coordinate, in widget allocation coordinates Emitted when a button or touch is released. @n_press will report the number of press that is paired to this event, note that [signal@Gtk.GestureClick::stopped] may have been emitted between the press and its release, @n_press will only start over at the next press. number of press that is paired with this release The X coordinate, in widget allocation coordinates The Y coordinate, in widget allocation coordinates Emitted whenever any time/distance threshold has been exceeded. Emitted whenever the gesture receives a release event that had no previous corresponding press. Due to implicit grabs, this can only happen on situations where input is grabbed elsewhere mid-press or the pressed widget voluntarily relinquishes its implicit grab. X coordinate of the event Y coordinate of the event Button being released Sequence being released `GtkGestureDrag` is a `GtkGesture` implementation for drags. The drag operation itself can be tracked throughout the [signal@Gtk.GestureDrag::drag-begin], [signal@Gtk.GestureDrag::drag-update] and [signal@Gtk.GestureDrag::drag-end] signals, and the relevant coordinates can be extracted through [method@Gtk.GestureDrag.get_offset] and [method@Gtk.GestureDrag.get_start_point]. Returns a newly created `GtkGesture` that recognizes drags. a newly created `GtkGestureDrag` Gets the offset from the start point. If the @gesture is active, this function returns %TRUE and fills in @x and @y with the coordinates of the current point, as an offset to the starting drag point. %TRUE if the gesture is active a `GtkGesture` X offset for the current point Y offset for the current point Gets the point where the drag started. If the @gesture is active, this function returns %TRUE and fills in @x and @y with the drag start coordinates, in widget-relative coordinates. %TRUE if the gesture is active a `GtkGesture` X coordinate for the drag start point Y coordinate for the drag start point Emitted whenever dragging starts. X coordinate, relative to the widget allocation Y coordinate, relative to the widget allocation Emitted whenever the dragging is finished. X offset, relative to the start point Y offset, relative to the start point Emitted whenever the dragging point moves. X offset, relative to the start point Y offset, relative to the start point `GtkGestureLongPress` is a `GtkGesture` for long presses. This gesture is also known as “Press and Hold”. When the timeout is exceeded, the gesture is triggering the [signal@Gtk.GestureLongPress::pressed] signal. If the touchpoint is lifted before the timeout passes, or if it drifts too far of the initial press point, the [signal@Gtk.GestureLongPress::cancelled] signal will be emitted. How long the timeout is before the ::pressed signal gets emitted is determined by the [property@Gtk.Settings:gtk-long-press-time] setting. It can be modified by the [property@Gtk.GestureLongPress:delay-factor] property. Returns a newly created `GtkGesture` that recognizes long presses. a newly created `GtkGestureLongPress`. Returns the delay factor. the delay factor A `GtkGestureLongPress` Applies the given delay factor. The default long press time will be multiplied by this value. Valid values are in the range [0.5..2.0]. A `GtkGestureLongPress` The delay factor to apply Factor by which to modify the default timeout. Emitted whenever a press moved too far, or was released before [signal@Gtk.GestureLongPress::pressed] happened. Emitted whenever a press goes unmoved/unreleased longer than what the GTK defaults tell. the X coordinate where the press happened, relative to the widget allocation the Y coordinate where the press happened, relative to the widget allocation `GtkGesturePan` is a `GtkGesture` for pan gestures. These are drags that are locked to happen along one axis. The axis that a `GtkGesturePan` handles is defined at construct time, and can be changed through [method@Gtk.GesturePan.set_orientation]. When the gesture starts to be recognized, `GtkGesturePan` will attempt to determine as early as possible whether the sequence is moving in the expected direction, and denying the sequence if this does not happen. Once a panning gesture along the expected axis is recognized, the [signal@Gtk.GesturePan::pan] signal will be emitted as input events are received, containing the offset in the given axis. Returns a newly created `GtkGesture` that recognizes pan gestures. a newly created `GtkGesturePan` expected orientation Returns the orientation of the pan gestures that this @gesture expects. the expected orientation for pan gestures A `GtkGesturePan` Sets the orientation to be expected on pan gestures. A `GtkGesturePan` expected orientation The expected orientation of pan gestures. Emitted once a panning gesture along the expected axis is detected. current direction of the pan gesture Offset along the gesture orientation `GtkGestureRotate` is a `GtkGesture` for 2-finger rotations. Whenever the angle between both handled sequences changes, the [signal@Gtk.GestureRotate::angle-changed] signal is emitted. Returns a newly created `GtkGesture` that recognizes 2-touch rotation gestures. a newly created `GtkGestureRotate` Gets the angle delta in radians. If @gesture is active, this function returns the angle difference in radians since the gesture was first recognized. If @gesture is not active, 0 is returned. the angle delta in radians a `GtkGestureRotate` Emitted when the angle between both tracked points changes. Current angle in radians Difference with the starting angle, in radians `GtkGestureSingle` is a `GtkGestures` subclass optimized for singe-touch and mouse gestures. Under interaction, these gestures stick to the first interacting sequence, which is accessible through [method@Gtk.GestureSingle.get_current_sequence] while the gesture is being interacted with. By default gestures react to both %GDK_BUTTON_PRIMARY and touch events. [method@Gtk.GestureSingle.set_touch_only] can be used to change the touch behavior. Callers may also specify a different mouse button number to interact with through [method@Gtk.GestureSingle.set_button], or react to any mouse button by setting it to 0. While the gesture is active, the button being currently pressed can be known through [method@Gtk.GestureSingle.get_current_button]. Returns the button number @gesture listens for. If this is 0, the gesture reacts to any button press. The button number, or 0 for any button a `GtkGestureSingle` Returns the button number currently interacting with @gesture, or 0 if there is none. The current button number a `GtkGestureSingle` Returns the event sequence currently interacting with @gesture. This is only meaningful if [method@Gtk.Gesture.is_active] returns %TRUE. the current sequence a `GtkGestureSingle` Gets whether a gesture is exclusive. For more information, see [method@Gtk.GestureSingle.set_exclusive]. Whether the gesture is exclusive a `GtkGestureSingle` Returns %TRUE if the gesture is only triggered by touch events. %TRUE if the gesture only handles touch events a `GtkGestureSingle` Sets the button number @gesture listens to. If non-0, every button press from a different button number will be ignored. Touch events implicitly match with button 1. a `GtkGestureSingle` button number to listen to, or 0 for any button Sets whether @gesture is exclusive. An exclusive gesture will only handle pointer and "pointer emulated" touch events, so at any given time, there is only one sequence able to interact with those. a `GtkGestureSingle` %TRUE to make @gesture exclusive Sets whether to handle only touch events. If @touch_only is %TRUE, @gesture will only handle events of type %GDK_TOUCH_BEGIN, %GDK_TOUCH_UPDATE or %GDK_TOUCH_END. If %FALSE, mouse events will be handled too. a `GtkGestureSingle` whether @gesture handles only touch events Mouse button number to listen to, or 0 to listen for any button. Whether the gesture is exclusive. Exclusive gestures only listen to pointer and pointer emulated events. Whether the gesture handles only touch events. `GtkGestureStylus` is a `GtkGesture` specific to stylus input. The provided signals just relay the basic information of the stylus events. Creates a new `GtkGestureStylus`. a newly created stylus gesture Returns the current values for the requested @axes. This function must be called from the handler of one of the [signal@Gtk.GestureStylus::down], [signal@Gtk.GestureStylus::motion], [signal@Gtk.GestureStylus::up] or [signal@Gtk.GestureStylus::proximity] signals. %TRUE if there is a current value for the axes a `GtkGestureStylus` array of requested axes, terminated with %GDK_AXIS_IGNORE return location for the axis values Returns the current value for the requested @axis. This function must be called from the handler of one of the [signal@Gtk.GestureStylus::down], [signal@Gtk.GestureStylus::motion], [signal@Gtk.GestureStylus::up] or [signal@Gtk.GestureStylus::proximity] signals. %TRUE if there is a current value for the axis a `GtkGestureStylus` requested device axis return location for the axis value Returns the accumulated backlog of tracking information. By default, GTK will limit rate of input events. On stylus input where accuracy of strokes is paramount, this function returns the accumulated coordinate/timing state before the emission of the current [Gtk.GestureStylus::motion] signal. This function may only be called within a [signal@Gtk.GestureStylus::motion] signal handler, the state given in this signal and obtainable through [method@Gtk.GestureStylus.get_axis] express the latest (most up-to-date) state in motion history. The @backlog is provided in chronological order. %TRUE if there is a backlog to unfold in the current state. a `GtkGestureStylus` coordinates and times for the backlog events return location for the number of elements Returns the `GdkDeviceTool` currently driving input through this gesture. This function must be called from the handler of one of the [signal@Gtk.GestureStylus::down], [signal@Gtk.GestureStylus::motion], [signal@Gtk.GestureStylus::up] or [signal@Gtk.GestureStylus::proximity] signals. The current stylus tool a `GtkGestureStylus` Checks whether the gesture is for styluses only. Stylus-only gestures will signal events exclusively from stylus input devices. %TRUE if the gesture is only for stylus events the gesture Sets the state of stylus-only If true, the gesture will exclusively handle events from stylus input devices, otherwise it'll handle events from any pointing device. the gesture whether the gesture is used exclusively for stylus events If this gesture should exclusively react to stylus input devices. Emitted when the stylus touches the device. the X coordinate of the stylus event the Y coordinate of the stylus event Emitted when the stylus moves while touching the device. the X coordinate of the stylus event the Y coordinate of the stylus event Emitted when the stylus is in proximity of the device. the X coordinate of the stylus event the Y coordinate of the stylus event Emitted when the stylus no longer touches the device. the X coordinate of the stylus event the Y coordinate of the stylus event `GtkGestureSwipe` is a `GtkGesture` for swipe gestures. After a press/move/.../move/release sequence happens, the [signal@Gtk.GestureSwipe::swipe] signal will be emitted, providing the velocity and directionality of the sequence at the time it was lifted. If the velocity is desired in intermediate points, [method@Gtk.GestureSwipe.get_velocity] can be called in a [signal@Gtk.Gesture::update] handler. All velocities are reported in pixels/sec units. Returns a newly created `GtkGesture` that recognizes swipes. a newly created `GtkGestureSwipe` Gets the current velocity. If the gesture is recognized, this function returns %TRUE and fills in @velocity_x and @velocity_y with the recorded velocity, as per the last events processed. whether velocity could be calculated a `GtkGestureSwipe` return value for the velocity in the X axis, in pixels/sec return value for the velocity in the Y axis, in pixels/sec Emitted when the recognized gesture is finished. Velocity and direction are a product of previously recorded events. velocity in the X axis, in pixels/sec velocity in the Y axis, in pixels/sec `GtkGestureZoom` is a `GtkGesture` for 2-finger pinch/zoom gestures. Whenever the distance between both tracked sequences changes, the [signal@Gtk.GestureZoom::scale-changed] signal is emitted to report the scale factor. Returns a newly created `GtkGesture` that recognizes pinch/zoom gestures. a newly created `GtkGestureZoom` Gets the scale delta. If @gesture is active, this function returns the zooming difference since the gesture was recognized (hence the starting point is considered 1:1). If @gesture is not active, 1 is returned. the scale delta a `GtkGestureZoom` Emitted whenever the distance between both tracked sequences changes. Scale delta, taking the initial state as 1:1 A widget that allows to bypass gsk rendering for its child by passing the content directly to the compositor. Graphics offload is an optimization to reduce overhead and battery use that is most useful for video content. It only works on some platforms and in certain situations. GTK will automatically fall back to normal rendering if it doesn't. Graphics offload is most efficient if there are no controls drawn on top of the video content. You should consider using graphics offload for your main widget if it shows frequently changing content (such as a video, or a VM display) and you provide the content in the form of dmabuf textures (see [class@Gdk.DmabufTextureBuilder]), in particular if it may be fullscreen. Numerous factors can prohibit graphics offload: - Unsupported platforms. Currently, graphics offload only works on Linux with Wayland. - Clipping, such as rounded corners that cause the video content to not be rectangular - Unsupported dmabuf formats (see [method@Gdk.Display.get_dmabuf_formats]) - Translucent video content (content with an alpha channel, even if it isn't used) - Transforms that are more complex than translations and scales - Filters such as opacity, grayscale or similar To investigate problems related graphics offload, GTK offers debug flags to print out information about graphics offload and dmabuf use: GDK_DEBUG=offload GDK_DEBUG=dmabuf The GTK inspector provides a visual debugging tool for graphics offload. Creates a new GtkGraphicsOffload widget. the new widget the child widget Returns whether the widget draws a black background. See [method@Gtk.GraphicsOffload.set_black_background]. `TRUE` if black background is drawn a `GtkGraphicsOffload` Gets the child of @self. the child widget a `GtkGraphicsOffload` Returns whether offload is enabled for @self. whether offload is enabled a `GtkGraphicsOffload` Sets whether this GtkGraphicsOffload widget will draw a black background. A main use case for this is **_letterboxing_** where black bars are visible next to the content if the aspect ratio of the content does not match the dimensions of the monitor. Using this property for letterboxing instead of CSS allows compositors to show content with maximum efficiency, using direct scanout to avoid extra copies in the compositor. On Wayland, this is implemented using the [single-pixel buffer](https://wayland.app/protocols/single-pixel-buffer-v1) protocol. a `GtkGraphicsOffload` whether to draw a black background behind the content Sets the child of @self. a `GtkGraphicsOffload` the child widget Sets whether this GtkGraphicsOffload widget will attempt to offload the content of its child widget. a `GtkGraphicsOffload` whether to enable offload Whether to draw a black background. The child widget. Whether graphics offload is enabled. Represents the state of graphics offloading. Graphics offloading is enabled. Graphics offloading is disabled. `GtkGrid` is a container which arranges its child widgets in rows and columns.  It supports arbitrary positions and horizontal/vertical spans. Children are added using [method@Gtk.Grid.attach]. They can span multiple rows or columns. It is also possible to add a child next to an existing child, using [method@Gtk.Grid.attach_next_to]. To remove a child from the grid, use [method@Gtk.Grid.remove]. The behaviour of `GtkGrid` when several children occupy the same grid cell is undefined. # GtkGrid as GtkBuildable Every child in a `GtkGrid` has access to a custom [iface@Gtk.Buildable] element, called `<layout>`. It can by used to specify a position in the grid and optionally spans. All properties that can be used in the `<layout>` element are implemented by [class@Gtk.GridLayoutChild]. It is implemented by `GtkWidget` using [class@Gtk.LayoutManager]. To showcase it, here is a simple example: ```xml <object class="GtkGrid" id="my_grid"> <child> <object class="GtkButton" id="button1"> <property name="label">Button 1</property> <layout> <property name="column">0</property> <property name="row">0</property> </layout> </object> </child> <child> <object class="GtkButton" id="button2"> <property name="label">Button 2</property> <layout> <property name="column">1</property> <property name="row">0</property> </layout> </object> </child> <child> <object class="GtkButton" id="button3"> <property name="label">Button 3</property> <layout> <property name="column">2</property> <property name="row">0</property> <property name="row-span">2</property> </layout> </object> </child> <child> <object class="GtkButton" id="button4"> <property name="label">Button 4</property> <layout> <property name="column">0</property> <property name="row">1</property> <property name="column-span">2</property> </layout> </object> </child> </object> ``` It organizes the first two buttons side-by-side in one cell each. The third button is in the last column but spans across two rows. This is defined by the `row-span` property. The last button is located in the second row and spans across two columns, which is defined by the `column-span` property. # CSS nodes `GtkGrid` uses a single CSS node with name `grid`. # Accessibility Until GTK 4.10, `GtkGrid` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. Starting from GTK 4.12, `GtkGrid` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. Creates a new grid widget. the new `GtkGrid` Adds a widget to the grid. The position of @child is determined by @column and @row. The number of “cells” that @child will occupy is determined by @width and @height. a `GtkGrid` the widget to add the column number to attach the left side of @child to the row number to attach the top side of @child to the number of columns that @child will span the number of rows that @child will span Adds a widget to the grid. The widget is placed next to @sibling, on the side determined by @side. When @sibling is %NULL, the widget is placed in row (for left or right placement) or column 0 (for top or bottom placement), at the end indicated by @side. Attaching widgets labeled `[1]`, `[2]`, `[3]` with `@sibling == %NULL` and `@side == %GTK_POS_LEFT` yields a layout of `[3][2][1]`. a `GtkGrid` the widget to add the child of @grid that @child will be placed next to, or %NULL to place @child at the beginning or end the side of @sibling that @child is positioned next to the number of columns that @child will span the number of rows that @child will span Returns which row defines the global baseline of @grid. the row index defining the global baseline a `GtkGrid` Gets the child of @grid whose area covers the grid cell at @column, @row. the child at the given position a `GtkGrid` the left edge of the cell the top edge of the cell Returns whether all columns of @grid have the same width. whether all columns of @grid have the same width. a `GtkGrid` Returns the amount of space between the columns of @grid. the column spacing of @grid a `GtkGrid` Returns the baseline position of @row. See [method@Gtk.Grid.set_row_baseline_position]. the baseline position of @row a `GtkGrid` a row index Returns whether all rows of @grid have the same height. whether all rows of @grid have the same height. a `GtkGrid` Returns the amount of space between the rows of @grid. the row spacing of @grid a `GtkGrid` Inserts a column at the specified position. Children which are attached at or to the right of this position are moved one column to the right. Children which span across this position are grown to span the new column. a `GtkGrid` the position to insert the column at Inserts a row or column at the specified position. The new row or column is placed next to @sibling, on the side determined by @side. If @side is %GTK_POS_TOP or %GTK_POS_BOTTOM, a row is inserted. If @side is %GTK_POS_LEFT of %GTK_POS_RIGHT, a column is inserted. a `GtkGrid` the child of @grid that the new row or column will be placed next to the side of @sibling that @child is positioned next to Inserts a row at the specified position. Children which are attached at or below this position are moved one row down. Children which span across this position are grown to span the new row. a `GtkGrid` the position to insert the row at Queries the attach points and spans of @child inside the given `GtkGrid`. a `GtkGrid` a `GtkWidget` child of @grid the column used to attach the left side of @child the row used to attach the top side of @child the number of columns @child spans the number of rows @child spans Removes a child from @grid. The child must have been added with [method@Gtk.Grid.attach] or [method@Gtk.Grid.attach_next_to]. a `GtkGrid` the child widget to remove Removes a column from the grid. Children that are placed in this column are removed, spanning children that overlap this column have their width reduced by one, and children after the column are moved to the left. a `GtkGrid` the position of the column to remove Removes a row from the grid. Children that are placed in this row are removed, spanning children that overlap this row have their height reduced by one, and children below the row are moved up. a `GtkGrid` the position of the row to remove Sets which row defines the global baseline for the entire grid. Each row in the grid can have its own local baseline, but only one of those is global, meaning it will be the baseline in the parent of the @grid. a `GtkGrid` the row index Sets whether all columns of @grid will have the same width. a `GtkGrid` %TRUE to make columns homogeneous Sets the amount of space between columns of @grid. a `GtkGrid` the amount of space to insert between columns Sets how the baseline should be positioned on @row of the grid, in case that row is assigned more space than is requested. The default baseline position is %GTK_BASELINE_POSITION_CENTER. a `GtkGrid` a row index a `GtkBaselinePosition` Sets whether all rows of @grid will have the same height. a `GtkGrid` %TRUE to make rows homogeneous Sets the amount of space between rows of @grid. a `GtkGrid` the amount of space to insert between rows The row to align to the baseline when valign is using baseline alignment. If %TRUE, the columns are all the same width. The amount of space between two consecutive columns. If %TRUE, the rows are all the same height. The amount of space between two consecutive rows. The parent class. `GtkGridLayout` is a layout manager which arranges child widgets in rows and columns. Children have an "attach point" defined by the horizontal and vertical index of the cell they occupy; children can span multiple rows or columns. The layout properties for setting the attach points and spans are set using the [class@Gtk.GridLayoutChild] associated to each child widget. The behaviour of `GtkGridLayout` when several children occupy the same grid cell is undefined. `GtkGridLayout` can be used like a `GtkBoxLayout` if all children are attached to the same row or column; however, if you only ever need a single row or column, you should consider using `GtkBoxLayout`. Creates a new `GtkGridLayout`. the newly created `GtkGridLayout` Retrieves the row set with gtk_grid_layout_set_baseline_row(). the global baseline row a `GtkGridLayout` Checks whether all columns of @grid should have the same width. %TRUE if the columns are homogeneous, and %FALSE otherwise a `GtkGridLayout` Retrieves the spacing set with gtk_grid_layout_set_column_spacing(). the spacing between consecutive columns a `GtkGridLayout` Returns the baseline position of @row. If no value has been set with [method@Gtk.GridLayout.set_row_baseline_position], the default value of %GTK_BASELINE_POSITION_CENTER is returned. the baseline position of @row a `GtkGridLayout` a row index Checks whether all rows of @grid should have the same height. %TRUE if the rows are homogeneous, and %FALSE otherwise a `GtkGridLayout` Retrieves the spacing set with gtk_grid_layout_set_row_spacing(). the spacing between consecutive rows a `GtkGridLayout` Sets which row defines the global baseline for the entire grid. Each row in the grid can have its own local baseline, but only one of those is global, meaning it will be the baseline in the parent of the @grid. a `GtkGridLayout` the row index Sets whether all columns of @grid should have the same width. a `GtkGridLayout` %TRUE to make columns homogeneous Sets the amount of space to insert between consecutive columns. a `GtkGridLayout` the amount of space between columns, in pixels Sets how the baseline should be positioned on @row of the grid, in case that row is assigned more space than is requested. a `GtkGridLayout` a row index a `GtkBaselinePosition` Sets whether all rows of @grid should have the same height. a `GtkGridLayout` %TRUE to make rows homogeneous Sets the amount of space to insert between consecutive rows. a `GtkGridLayout` the amount of space between rows, in pixels The row to align to the baseline, when `GtkWidget:valign` is set to %GTK_ALIGN_BASELINE. Whether all the columns in the grid have the same width. The amount of space between to consecutive columns. Whether all the rows in the grid have the same height. The amount of space between to consecutive rows. `GtkLayoutChild` subclass for children in a `GtkGridLayout`. Retrieves the column number to which @child attaches its left side. the column number a `GtkGridLayoutChild` Retrieves the number of columns that @child spans to. the number of columns a `GtkGridLayoutChild` Retrieves the row number to which @child attaches its top side. the row number a `GtkGridLayoutChild` Retrieves the number of rows that @child spans to. the number of row a `GtkGridLayoutChild` Sets the column number to attach the left side of @child. a `GtkGridLayoutChild` the attach point for @child Sets the number of columns @child spans to. a `GtkGridLayoutChild` the span of @child Sets the row to place @child in. a `GtkGridLayoutChild` the row for @child Sets the number of rows @child spans to. a `GtkGridLayoutChild` the span of @child The column to place the child in. The number of columns the child spans to. The row to place the child in. The number of rows the child spans to. `GtkGridView` presents a large dynamic grid of items. `GtkGridView` uses its factory to generate one child widget for each visible item and shows them in a grid. The orientation of the grid view determines if the grid reflows vertically or horizontally. `GtkGridView` allows the user to select items according to the selection characteristics of the model. For models that allow multiple selected items, it is possible to turn on _rubberband selection_, using [property@Gtk.GridView:enable-rubberband]. To learn more about the list widget framework, see the [overview](section-list-widget.html). # Actions `GtkGridView` defines a set of built-in actions: - `list.activate-item` activates the item at given position by emitting the the [signal@Gtk.GridView::activate] signal. # CSS nodes ``` gridview ├── child[.activatable] │ ├── child[.activatable] │ ┊ ╰── [rubberband] ``` `GtkGridView` uses a single CSS node with name `gridview`. Each child uses a single CSS node with name `child`. If the [property@Gtk.ListItem:activatable] property is set, the corresponding row will have the `.activatable` style class. For rubberband selection, a subnode with name `rubberband` is used. # Accessibility `GtkGridView` uses the %GTK_ACCESSIBLE_ROLE_GRID role, and the items use the %GTK_ACCESSIBLE_ROLE_GRID_CELL role. Creates a new `GtkGridView` that uses the given @factory for mapping items to widgets. The function takes ownership of the arguments, so you can write code like ```c grid_view = gtk_grid_view_new (create_model (), gtk_builder_list_item_factory_new_from_resource ("/resource.ui")); ``` a new `GtkGridView` using the given @model and @factory the model to use The factory to populate items with Returns whether rows can be selected by dragging with the mouse. %TRUE if rubberband selection is enabled a `GtkGridView` Gets the factory that's currently used to populate list items. The factory in use a `GtkGridView` Gets the maximum number of columns that the grid will use. The maximum number of columns a `GtkGridView` Gets the minimum number of columns that the grid will use. The minimum number of columns a `GtkGridView` Gets the model that's currently used to read the items displayed. The model in use a `GtkGridView` Returns whether items will be activated on single click and selected on hover. %TRUE if items are activated on single click a `GtkGridView` Gets the behavior set for the <kbd>Tab</kbd> key. The behavior of the <kbd>Tab</kbd> key a `GtkGridView` Scrolls to the item at the given position and performs the actions specified in @flags. This function works no matter if the gridview is shown or focused. If it isn't, then the changes will take effect once that happens. The gridview to scroll in position of the item. Must be less than the number of items in the view. actions to perform details of how to perform the scroll operation or %NULL to scroll into view Sets whether selections can be changed by dragging with the mouse. a `GtkGridView` %TRUE to enable rubberband selection Sets the `GtkListItemFactory` to use for populating list items. a `GtkGridView` the factory to use Sets the maximum number of columns to use. This number must be at least 1. If @max_columns is smaller than the minimum set via [method@Gtk.GridView.set_min_columns], that value is used instead. a `GtkGridView` The maximum number of columns Sets the minimum number of columns to use. This number must be at least 1. If @min_columns is smaller than the minimum set via [method@Gtk.GridView.set_max_columns], that value is ignored. a `GtkGridView` The minimum number of columns Sets the model to use. This must be a [iface@Gtk.SelectionModel]. a `GtkGridView` the model to use Sets whether items should be activated on single click and selected on hover. a `GtkGridView` %TRUE to activate items on single click Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. a `GtkGridView` The desired tab behavior Allow rubberband selection. Factory for populating list items. The factory must be for configuring [class@Gtk.ListItem] objects. Maximum number of columns per row. If this number is smaller than [property@Gtk.GridView:min-columns], that value is used instead. Minimum number of columns per row. Model for the items displayed. Activate rows on single click and select them on hover. Behavior of the <kbd>Tab</kbd> key Emitted when a cell has been activated by the user, usually via activating the GtkGridView|list.activate-item action. This allows for a convenient way to handle activation in a gridview. See [property@Gtk.ListItem:activatable] for details on how to use this signal. position of item to activate `GtkHeaderBar` is a widget for creating custom title bars for windows.  `GtkHeaderBar` is similar to a horizontal `GtkCenterBox`. It allows children to be placed at the start or the end. In addition, it allows the window title to be displayed. The title will be centered with respect to the width of the box, even if the children at either side take up different amounts of space. `GtkHeaderBar` can add typical window frame controls, such as minimize, maximize and close buttons, or the window icon. For these reasons, `GtkHeaderBar` is the natural choice for use as the custom titlebar widget of a `GtkWindow` (see [method@Gtk.Window.set_titlebar]), as it gives features typical of titlebars while allowing the addition of child widgets. ## GtkHeaderBar as GtkBuildable The `GtkHeaderBar` implementation of the `GtkBuildable` interface supports adding children at the start or end sides by specifying “start” or “end” as the “type” attribute of a `<child>` element, or setting the title widget by specifying “title” value. By default the `GtkHeaderBar` uses a `GtkLabel` displaying the title of the window it is contained in as the title widget, equivalent to the following UI definition: ```xml <object class="GtkHeaderBar"> <property name="title-widget"> <object class="GtkLabel"> <property name="label" translatable="yes">Label</property> <property name="single-line-mode">True</property> <property name="ellipsize">end</property> <property name="width-chars">5</property> <style> <class name="title"/> </style> </object> </property> </object> ``` # CSS nodes ``` headerbar ╰── windowhandle ╰── box ├── box.start │ ├── windowcontrols.start │ ╰── [other children] ├── [Title Widget] ╰── box.end ├── [other children] ╰── windowcontrols.end ``` A `GtkHeaderBar`'s CSS node is called `headerbar`. It contains a `windowhandle` subnode, which contains a `box` subnode, which contains two `box` subnodes at the start and end of the header bar, as well as a center node that represents the title. Each of the boxes contains a `windowcontrols` subnode, see [class@Gtk.WindowControls] for details, as well as other children. # Accessibility `GtkHeaderBar` uses the %GTK_ACCESSIBLE_ROLE_GROUP role. Creates a new `GtkHeaderBar` widget. a new `GtkHeaderBar` Gets the decoration layout of the `GtkHeaderBar`. the decoration layout a `GtkHeaderBar` Returns whether this header bar shows the standard window title buttons. %TRUE if title buttons are shown a `GtkHeaderBar` Retrieves the title widget of the header. See [method@Gtk.HeaderBar.set_title_widget]. the title widget of the header a `GtkHeaderBar` Adds @child to @bar, packed with reference to the end of the @bar. A `GtkHeaderBar` the `GtkWidget` to be added to @bar Adds @child to @bar, packed with reference to the start of the @bar. A `GtkHeaderBar` the `GtkWidget` to be added to @bar Removes a child from the `GtkHeaderBar`. The child must have been added with [method@Gtk.HeaderBar.pack_start], [method@Gtk.HeaderBar.pack_end] or [method@Gtk.HeaderBar.set_title_widget]. a `GtkHeaderBar` the child to remove Sets the decoration layout for this header bar. This property overrides the [property@Gtk.Settings:gtk-decoration-layout] setting. There can be valid reasons for overriding the setting, such as a header bar design that does not allow for buttons to take room on the right, or only offers room for a single close button. Split header bars are another example for overriding the setting. The format of the string is button names, separated by commas. A colon separates the buttons that should appear on the left from those on the right. Recognized button names are minimize, maximize, close and icon (the window icon). For example, “icon:minimize,maximize,close” specifies an icon on the left, and minimize, maximize and close buttons on the right. a `GtkHeaderBar` a decoration layout, or %NULL to unset the layout Sets whether this header bar shows the standard window title buttons. a `GtkHeaderBar` %TRUE to show standard title buttons Sets the title for the `GtkHeaderBar`. When set to %NULL, the headerbar will display the title of the window it is contained in. The title should help a user identify the current view. To achieve the same style as the builtin title, use the “title” style class. You should set the title widget to %NULL, for the window title label to be visible again. a `GtkHeaderBar` a widget to use for a title The decoration layout for buttons. If this property is not set, the [property@Gtk.Settings:gtk-decoration-layout] setting is used. Whether to show title buttons like close, minimize, maximize. Which buttons are actually shown and where is determined by the [property@Gtk.HeaderBar:decoration-layout] property, and by the state of the window (e.g. a close button will not be shown if the window can't be closed). The title widget to display. `GtkIMContext` defines the interface for GTK input methods. `GtkIMContext` is used by GTK text input widgets like `GtkText` to map from key events to Unicode character strings. An input method may consume multiple key events in sequence before finally outputting the composed result. This is called *preediting*, and an input method may provide feedback about this process by displaying the intermediate composition states as preedit text. To do so, the `GtkIMContext` will emit [signal@Gtk.IMContext::preedit-start], [signal@Gtk.IMContext::preedit-changed] and [signal@Gtk.IMContext::preedit-end] signals. For instance, the built-in GTK input method [class@Gtk.IMContextSimple] implements the input of arbitrary Unicode code points by holding down the <kbd>Control</kbd> and <kbd>Shift</kbd> keys and then typing <kbd>u</kbd> followed by the hexadecimal digits of the code point. When releasing the <kbd>Control</kbd> and <kbd>Shift</kbd> keys, preediting ends and the character is inserted as text. For example, Ctrl+Shift+u 2 0 A C results in the € sign. Additional input methods can be made available for use by GTK widgets as loadable modules. An input method module is a small shared library which provides a `GIOExtension` for the extension point named "gtk-im-module". To connect a widget to the users preferred input method, you should use [class@Gtk.IMMulticontext]. Default handler of the [signal@Gtk.IMContext::commit] signal. Asks the widget that the input context is attached to delete characters around the cursor position by emitting the `::delete_surrounding` signal. Note that @offset and @n_chars are in characters not in bytes which differs from the usage other places in `GtkIMContext`. In order to use this function, you should first call [method@Gtk.IMContext.get_surrounding] to get the current context, and call this function immediately afterwards to make sure that you know what you are deleting. You should also account for the fact that even if the signal was handled, the input context might not have deleted all the characters that were requested to be deleted. This function is used by an input method that wants to make substitutions in the existing text in response to new input. It is not useful for applications. %TRUE if the signal was handled. a `GtkIMContext` offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. Allow an input method to internally handle key press and release events. If this function returns %TRUE, then no further processing should be done for this key event. %TRUE if the input method handled the key event. a `GtkIMContext` the key event Notify the input method that the widget to which this input context corresponds has gained focus. The input method may, for example, change the displayed feedback to reflect this change. a `GtkIMContext` Notify the input method that the widget to which this input context corresponds has lost focus. The input method may, for example, change the displayed feedback or reset the contexts state to reflect this change. a `GtkIMContext` Retrieve the current preedit string for the input context, and a list of attributes to apply to the string. This string should be displayed inserted at the insertion point. a `GtkIMContext` location to store the retrieved string. The string retrieved must be freed with g_free(). location to store the retrieved attribute list. When you are done with this list, you must unreference it with [method@Pango.AttrList.unref]. location to store position of cursor (in characters) within the preedit string. Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai where only some sequences of characters are allowed. This function is implemented by emitting the [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method; in response to this signal, a widget should provide as much context as is available, up to an entire paragraph, by calling [method@Gtk.IMContext.set_surrounding]. Note that there is no obligation for a widget to respond to the `::retrieve-surrounding` signal, so input methods must be prepared to function without context. Use [method@Gtk.IMContext.get_surrounding_with_selection] instead. `TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. a `GtkIMContext` location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai where only some sequences of characters are allowed. This function is implemented by emitting the [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method; in response to this signal, a widget should provide as much context as is available, up to an entire paragraph, by calling [method@Gtk.IMContext.set_surrounding_with_selection]. Note that there is no obligation for a widget to respond to the `::retrieve-surrounding` signal, so input methods must be prepared to function without context. `TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. a `GtkIMContext` location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. location to store byte index of the selection bound within @text Default handler of the [signal@Gtk.IMContext::preedit-changed] signal. Default handler of the [signal@Gtk.IMContext::preedit-end] signal. Default handler of the [signal@Gtk.IMContext::preedit-start] signal. Notify the input method that a change such as a change in cursor position has been made. This will typically cause the input method to clear the preedit state. a `GtkIMContext` Default handler of the [signal@Gtk.IMContext::retrieve-surrounding] signal. Set the client widget for the input context. This is the `GtkWidget` holding the input focus. This widget is used in order to correctly position status windows, and may also be used for purposes internal to the input method. a `GtkIMContext` the client widget. This may be %NULL to indicate that the previous client widget no longer exists. Notify the input method that a change in cursor position has been made. The location is relative to the client widget. a `GtkIMContext` new location Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the [signal@Gtk.IMContext::retrieve-surrounding] signal, and will likely have no effect if called at other times. Use [method@Gtk.IMContext.set_surrounding_with_selection] instead a `GtkIMContext` text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the [signal@Gtk.IMContext::retrieve_surrounding] signal, and will likely have no effect if called at other times. a `GtkIMContext` text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text the byte index of the selection bound within @text Sets whether the IM context should use the preedit string to display feedback. If @use_preedit is %FALSE (default is %TRUE), then the IM context may use some other method to display feedback, such as displaying it in a child of the root window. a `GtkIMContext` whether the IM context should use the preedit string. Requests the platform to show an on-screen keyboard for user input. This method will return %TRUE if this request was actually performed to the platform, other environmental factors may result in an on-screen keyboard effectively not showing up. %TRUE if an on-screen keyboard could be requested to the platform. a `GtkIMContext` a [class@Gdk.Event] Asks the widget that the input context is attached to delete characters around the cursor position by emitting the `::delete_surrounding` signal. Note that @offset and @n_chars are in characters not in bytes which differs from the usage other places in `GtkIMContext`. In order to use this function, you should first call [method@Gtk.IMContext.get_surrounding] to get the current context, and call this function immediately afterwards to make sure that you know what you are deleting. You should also account for the fact that even if the signal was handled, the input context might not have deleted all the characters that were requested to be deleted. This function is used by an input method that wants to make substitutions in the existing text in response to new input. It is not useful for applications. %TRUE if the signal was handled. a `GtkIMContext` offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. Allow an input method to forward key press and release events to another input method without necessarily having a `GdkEvent` available. %TRUE if the input method handled the key event. a `GtkIMContext` whether to forward a key press or release event the surface the event is for the device that the event is for the timestamp for the event the keycode for the event modifier state for the event the active keyboard group for the event Allow an input method to internally handle key press and release events. If this function returns %TRUE, then no further processing should be done for this key event. %TRUE if the input method handled the key event. a `GtkIMContext` the key event Notify the input method that the widget to which this input context corresponds has gained focus. The input method may, for example, change the displayed feedback to reflect this change. a `GtkIMContext` Notify the input method that the widget to which this input context corresponds has lost focus. The input method may, for example, change the displayed feedback or reset the contexts state to reflect this change. a `GtkIMContext` Retrieve the current preedit string for the input context, and a list of attributes to apply to the string. This string should be displayed inserted at the insertion point. a `GtkIMContext` location to store the retrieved string. The string retrieved must be freed with g_free(). location to store the retrieved attribute list. When you are done with this list, you must unreference it with [method@Pango.AttrList.unref]. location to store position of cursor (in characters) within the preedit string. Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai where only some sequences of characters are allowed. This function is implemented by emitting the [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method; in response to this signal, a widget should provide as much context as is available, up to an entire paragraph, by calling [method@Gtk.IMContext.set_surrounding]. Note that there is no obligation for a widget to respond to the `::retrieve-surrounding` signal, so input methods must be prepared to function without context. Use [method@Gtk.IMContext.get_surrounding_with_selection] instead. `TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. a `GtkIMContext` location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. Retrieves context around the insertion point. Input methods typically want context in order to constrain input text based on existing text; this is important for languages such as Thai where only some sequences of characters are allowed. This function is implemented by emitting the [signal@Gtk.IMContext::retrieve-surrounding] signal on the input method; in response to this signal, a widget should provide as much context as is available, up to an entire paragraph, by calling [method@Gtk.IMContext.set_surrounding_with_selection]. Note that there is no obligation for a widget to respond to the `::retrieve-surrounding` signal, so input methods must be prepared to function without context. `TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. a `GtkIMContext` location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. location to store byte index of the selection bound within @text Notify the input method that a change such as a change in cursor position has been made. This will typically cause the input method to clear the preedit state. a `GtkIMContext` Set the client widget for the input context. This is the `GtkWidget` holding the input focus. This widget is used in order to correctly position status windows, and may also be used for purposes internal to the input method. a `GtkIMContext` the client widget. This may be %NULL to indicate that the previous client widget no longer exists. Notify the input method that a change in cursor position has been made. The location is relative to the client widget. a `GtkIMContext` new location Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the [signal@Gtk.IMContext::retrieve-surrounding] signal, and will likely have no effect if called at other times. Use [method@Gtk.IMContext.set_surrounding_with_selection] instead a `GtkIMContext` text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. Sets surrounding context around the insertion point and preedit string. This function is expected to be called in response to the [signal@Gtk.IMContext::retrieve_surrounding] signal, and will likely have no effect if called at other times. a `GtkIMContext` text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text the byte index of the selection bound within @text Sets whether the IM context should use the preedit string to display feedback. If @use_preedit is %FALSE (default is %TRUE), then the IM context may use some other method to display feedback, such as displaying it in a child of the root window. a `GtkIMContext` whether the IM context should use the preedit string. Additional hints that allow input methods to fine-tune their behaviour. The purpose of the text field that the `GtkIMContext is connected to. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. The ::commit signal is emitted when a complete input sequence has been entered by the user. If the commit comes after a preediting sequence, the ::commit signal is emitted after ::preedit-end. This can be a single character immediately after a key press or the final result of preediting. the completed character(s) entered by the user The ::delete-surrounding signal is emitted when the input method needs to delete all or part of the context surrounding the cursor. %TRUE if the signal was handled. the character offset from the cursor position of the text to be deleted. A negative value indicates a position before the cursor. the number of characters to be deleted The ::preedit-changed signal is emitted whenever the preedit sequence currently being entered has changed. It is also emitted at the end of a preedit sequence, in which case [method@Gtk.IMContext.get_preedit_string] returns the empty string. The ::preedit-end signal is emitted when a preediting sequence has been completed or canceled. The ::preedit-start signal is emitted when a new preediting sequence starts. The ::retrieve-surrounding signal is emitted when the input method requires the context surrounding the cursor. The callback should set the input method surrounding context by calling the [method@Gtk.IMContext.set_surrounding] method. %TRUE if the signal was handled. Default handler of the [signal@Gtk.IMContext::preedit-start] signal. Default handler of the [signal@Gtk.IMContext::preedit-end] signal. Default handler of the [signal@Gtk.IMContext::preedit-changed] signal. Default handler of the [signal@Gtk.IMContext::commit] signal. Default handler of the [signal@Gtk.IMContext::retrieve-surrounding] signal. Default handler of the [signal@Gtk.IMContext::delete-surrounding] signal. %TRUE if the signal was handled. a `GtkIMContext` offset from cursor position in chars; a negative value means start before the cursor. number of characters to delete. Called via [method@Gtk.IMContext.set_client_widget] when the input window where the entered text will appear changes. Override this to keep track of the current input window, for instance for the purpose of positioning a status display of your input method. a `GtkIMContext` the client widget. This may be %NULL to indicate that the previous client widget no longer exists. Called via [method@Gtk.IMContext.get_preedit_string] to retrieve the text currently being preedited for display at the cursor position. Any input method which composes complex characters or any other compositions from multiple sequential key presses should override this method to provide feedback. a `GtkIMContext` location to store the retrieved string. The string retrieved must be freed with g_free(). location to store the retrieved attribute list. When you are done with this list, you must unreference it with [method@Pango.AttrList.unref]. location to store position of cursor (in characters) within the preedit string. Called via [method@Gtk.IMContext.filter_keypress] on every key press or release event. Every non-trivial input method needs to override this in order to implement the mapping from key events to text. A return value of %TRUE indicates to the caller that the event was consumed by the input method. In that case, the [signal@Gtk.IMContext::commit] signal should be emitted upon completion of a key sequence to pass the resulting text back to the input widget. Alternatively, %FALSE may be returned to indicate that the event wasn’t handled by the input method. If a builtin mapping exists for the key, it is used to produce a character. %TRUE if the input method handled the key event. a `GtkIMContext` the key event Called via [method@Gtk.IMContext.focus_in] when the input widget has gained focus. May be overridden to keep track of the current focus. a `GtkIMContext` Called via [method@Gtk.IMContext.focus_out] when the input widget has lost focus. May be overridden to keep track of the current focus. a `GtkIMContext` Called via [method@Gtk.IMContext.reset] to signal a change such as a change in cursor position. An input method that implements preediting should override this method to clear the preedit state on reset. a `GtkIMContext` Called via [method@Gtk.IMContext.set_cursor_location] to inform the input method of the current cursor location relative to the client window. May be overridden to implement the display of popup windows at the cursor position. a `GtkIMContext` new location Called via [method@Gtk.IMContext.set_use_preedit] to control the use of the preedit string. Override this to display feedback by some other means if turned off. a `GtkIMContext` whether the IM context should use the preedit string. Called via [method@Gtk.IMContext.set_surrounding] in response to [signal@Gtk.IMContext::retrieve-surrounding] signal to update the input method’s idea of the context around the cursor. It is not necessary to override this method even with input methods which implement context-dependent behavior. The base implementation is sufficient for [method@Gtk.IMContext.get_surrounding] to work. a `GtkIMContext` text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text. Called via [method@Gtk.IMContext.get_surrounding] to update the context around the cursor location. It is not necessary to override this method even with input methods which implement context-dependent behavior. The base implementation emits [signal@Gtk.IMContext::retrieve-surrounding] and records the context received by the subsequent invocation of [vfunc@Gtk.IMContext.get_surrounding]. `TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. a `GtkIMContext` location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. Called via [method@Gtk.IMContext.set_surrounding_with_selection] in response to the [signal@Gtk.IMContext::retrieve-surrounding] signal to update the input method’s idea of the context around the cursor. It is not necessary to override this method even with input methods which implement context-dependent behavior. The base implementation is sufficient for [method@Gtk.IMContext.get_surrounding] to work. a `GtkIMContext` text surrounding the insertion point, as UTF-8. the preedit string should not be included within @text the length of @text, or -1 if @text is nul-terminated the byte index of the insertion cursor within @text the byte index of the selection bound within @text Called via [method@Gtk.IMContext.get_surrounding_with_selection] to update the context around the cursor location. It is not necessary to override this method even with input methods which implement context-dependent behavior. The base implementation emits [signal@Gtk.IMContext::retrieve-surrounding] and records the context received by the subsequent invocation of [vfunc@Gtk.IMContext.get_surrounding]. `TRUE` if surrounding text was provided; in this case you must free the result stored in `text`. a `GtkIMContext` location to store a UTF-8 encoded string of text holding context around the insertion point. If the function returns %TRUE, then you must free the result stored in this location with g_free(). location to store byte index of the insertion cursor within @text. location to store byte index of the selection bound within @text `GtkIMContextSimple` is an input method supporting table-based input methods. ## Compose sequences `GtkIMContextSimple` reads compose sequences from the first of the following files that is found: ~/.config/gtk-4.0/Compose, ~/.XCompose, /usr/share/X11/locale/$locale/Compose (for locales that have a nontrivial Compose file). A subset of the file syntax described in the Compose(5) manual page is supported. Additionally, `include "%L"` loads GTK’s built-in table of compose sequences rather than the locale-specific one from X11. If none of these files is found, `GtkIMContextSimple` uses a built-in table of compose sequences that is derived from the X11 Compose files. Note that compose sequences typically start with the Compose_key, which is often not available as a dedicated key on keyboards. Keyboard layouts may map this keysym to other keys, such as the right Control key. ## Unicode characters `GtkIMContextSimple` also supports numeric entry of Unicode characters by typing <kbd>Ctrl</kbd>-<kbd>Shift</kbd>-<kbd>u</kbd>, followed by a hexadecimal Unicode codepoint. For example, Ctrl-Shift-u 1 2 3 Enter yields U+0123 LATIN SMALL LETTER G WITH CEDILLA, i.e. ģ. ## Dead keys `GtkIMContextSimple` supports dead keys. For example, typing dead_acute a yields U+00E! LATIN SMALL LETTER_A WITH ACUTE, i.e. á. Note that this depends on the keyboard layout including dead keys. Creates a new `GtkIMContextSimple`. a new `GtkIMContextSimple` Adds an additional table from the X11 compose file. A `GtkIMContextSimple` The path of compose file Adds an additional table to search to the input context. Each row of the table consists of @max_seq_len key symbols followed by two #guint16 interpreted as the high and low words of a #gunicode value. Tables are searched starting from the last added. The table must be sorted in dictionary order on the numeric value of the key symbol fields. (Values beyond the length of the sequence should be zero.) Use gtk_im_context_simple_add_compose_file() A `GtkIMContextSimple` the table Maximum length of a sequence in the table number of sequences in the table `GtkIMMulticontext` is an input method context supporting multiple, switchable input methods. Text widgets such as `GtkText` or `GtkTextView` use a `GtkIMMultiContext` to implement their `im-module` property for switching between different input methods. Creates a new `GtkIMMulticontext`. a new `GtkIMMulticontext`. Gets the id of the currently active delegate of the @context. the id of the currently active delegate a `GtkIMMulticontext` Sets the context id for @context. This causes the currently active delegate of @context to be replaced by the delegate corresponding to the new context id. Setting this to a non-%NULL value overrides the system-wide IM module setting. See the [property@Gtk.Settings:gtk-im-module] property. a `GtkIMMulticontext` the id to use The default name of the extension point. Constant to return from a signal handler for the ::input signal in case of conversion failure. See [signal@Gtk.SpinButton::input]. Like [func@get_interface_age], but from the headers used at application compile time, rather than from the library linked against at application run time. The value used to refer to a guaranteed invalid position in a `GListModel`. This value may be returned from some functions, others may accept it as input. Its interpretation may differ for different functions. Refer to each function's documentation for if this value is allowed and what it does. Used to specify options for gtk_icon_theme_lookup_icon(). Try to always load regular icons, even when symbolic icon names are given Try to always load symbolic icons, even when regular icon names are given Starts loading the texture in the background so it is ready when later needed. Contains information found when looking up an icon in `GtkIconTheme`. `GtkIconPaintable` implements `GdkPaintable`. Creates a `GtkIconPaintable` for a file with a given size and scale. The icon can then be rendered by using it as a `GdkPaintable`. a `GtkIconPaintable` containing for the icon. Unref with g_object_unref() a `GFile` desired icon size, in application pixels the desired scale Gets the `GFile` that was used to load the icon. Returns %NULL if the icon was not loaded from a file. the `GFile` for the icon a `GtkIconPaintable` Get the icon name being used for this icon. When an icon looked up in the icon theme was not available, the icon theme may use fallback icons - either those specified to gtk_icon_theme_lookup_icon() or the always-available "image-missing". The icon chosen is returned by this function. If the icon was created without an icon theme, this function returns %NULL. the themed icon-name for the icon, or %NULL if its not a themed icon. a `GtkIconPaintable` Checks if the icon is symbolic or not. This currently uses only the file name and not the file contents for determining this. This behaviour may change in the future. Note that to render a symbolic `GtkIconPaintable` properly (with recoloring), you have to set its icon name on a `GtkImage`. %TRUE if the icon is symbolic, %FALSE otherwise a `GtkIconPaintable` The file representing the icon, if any. The icon name that was chosen during lookup. Whether the icon is symbolic or not. Built-in icon sizes. Icon sizes default to being inherited. Where they cannot be inherited, text size is the default. All widgets which use `GtkIconSize` set the normal-icons or large-icons style classes correspondingly, and let themes determine the actual size to be used with the `-gtk-icon-size` CSS property. Keep the size of the parent element Size similar to text size Large size, for example in an icon view `GtkIconTheme` provides a facility for loading themed icons. The main reason for using a name rather than simply providing a filename is to allow different icons to be used depending on what “icon theme” is selected by the user. The operation of icon themes on Linux and Unix follows the [Icon Theme Specification](http://www.freedesktop.org/Standards/icon-theme-spec) There is a fallback icon theme, named `hicolor`, where applications should install their icons, but additional icon themes can be installed as operating system vendors and users choose. In many cases, named themes are used indirectly, via [class@Gtk.Image] rather than directly, but looking up icons directly is also simple. The `GtkIconTheme` object acts as a database of all the icons in the current theme. You can create new `GtkIconTheme` objects, but it’s much more efficient to use the standard icon theme of the `GtkWidget` so that the icon information is shared with other people looking up icons. ```c GtkIconTheme *icon_theme; GtkIconPaintable *icon; GdkPaintable *paintable; icon_theme = gtk_icon_theme_get_for_display (gtk_widget_get_display (my_widget)); icon = gtk_icon_theme_lookup_icon (icon_theme, "my-icon-name", // icon name 48, // icon size 1, // scale 0, // flags); paintable = GDK_PAINTABLE (icon); // Use the paintable g_object_unref (icon); ``` Creates a new icon theme object. Icon theme objects are used to lookup up an icon by name in a particular icon theme. Usually, you’ll want to use [func@Gtk.IconTheme.get_for_display] rather than creating a new icon theme object for scratch. the newly created `GtkIconTheme` object. Gets the icon theme object associated with @display. If this function has not previously been called for the given display, a new icon theme object will be created and associated with the display. Icon theme objects are fairly expensive to create, so using this function is usually a better choice than calling [ctor@Gtk.IconTheme.new] and setting the display yourself; by using this function a single icon theme object will be shared between users. A unique `GtkIconTheme` associated with the given display. This icon theme is associated with the display and can be used as long as the display is open. Do not ref or unref it. a `GdkDisplay` Adds a resource path that will be looked at when looking for icons, similar to search paths. See [method@Gtk.IconTheme.set_resource_path]. This function should be used to make application-specific icons available as part of the icon theme. a `GtkIconTheme` a resource path Appends a directory to the search path. See [method@Gtk.IconTheme.set_search_path]. a `GtkIconTheme` directory name to append to the icon path Returns the display that the `GtkIconTheme` object was created for. the display of @icon_theme a `GtkIconTheme` Lists the names of icons in the current icon theme. a string array holding the names of all the icons in the theme. You must free the array using g_strfreev(). a `GtkIconTheme` Returns an array of integers describing the sizes at which the icon is available without scaling. A size of -1 means that the icon is available in a scalable format. The array is zero-terminated. A newly allocated array describing the sizes at which the icon is available. The array should be freed with g_free() when it is no longer needed. a `GtkIconTheme` the name of an icon Gets the current resource path. See [method@Gtk.IconTheme.set_resource_path]. A list of resource paths a `GtkIconTheme` Gets the current search path. See [method@Gtk.IconTheme.set_search_path]. a list of icon theme path directories a `GtkIconTheme` Gets the current icon theme name. the current icon theme name, a `GtkIconTheme` Checks whether an icon theme includes an icon for a particular `GIcon`. %TRUE if @self includes an icon for @gicon a `GtkIconTheme` a `GIcon` Checks whether an icon theme includes an icon for a particular name. %TRUE if @self includes an icon for @icon_name. a `GtkIconTheme` the name of an icon Looks up a icon for a desired size and window scale. The icon can then be rendered by using it as a `GdkPaintable`, or you can get information such as the filename and size. a `GtkIconPaintable` containing information about the icon. Unref with g_object_unref() a `GtkIconTheme` the `GIcon` to look up desired icon size, in application pixels the desired scale text direction the icon will be displayed in flags modifying the behavior of the icon lookup Looks up a named icon for a desired size and window scale, returning a `GtkIconPaintable`. The icon can then be rendered by using it as a `GdkPaintable`, or you can get information such as the filename and size. If the available @icon_name is not available and @fallbacks are provided, they will be tried in order. If no matching icon is found, then a paintable that renders the "missing icon" icon is returned. If you need to do something else for missing icons you need to use [method@Gtk.IconTheme.has_icon]. Note that you probably want to listen for icon theme changes and update the icon. This is usually done by overriding the GtkWidgetClass.css-changed() function. a `GtkIconPaintable` object containing the icon. a `GtkIconTheme` the name of the icon to lookup fallback names desired icon size, in application pixels the window scale this will be displayed on text direction the icon will be displayed in flags modifying the behavior of the icon lookup Sets the resource paths that will be looked at when looking for icons, similar to search paths. The resources are considered as part of the hicolor icon theme and must be located in subdirectories that are defined in the hicolor icon theme, such as `@path/16x16/actions/run.png` or `@path/scalable/actions/run.svg`. Icons that are directly placed in the resource path instead of a subdirectory are also considered as ultimate fallback, but they are treated like unthemed icons. a `GtkIconTheme` NULL-terminated array of resource paths that are searched for icons Sets the search path for the icon theme object. When looking for an icon theme, GTK will search for a subdirectory of one or more of the directories in @path with the same name as the icon theme containing an index.theme file. (Themes from multiple of the path elements are combined to allow themes to be extended by adding icons in the user’s home directory.) In addition if an icon found isn’t found either in the current icon theme or the default icon theme, and an image file with the right name is found directly in one of the elements of @path, then that image will be used for the icon name. (This is legacy feature, and new icons should be put into the fallback icon theme, which is called hicolor, rather than directly on the icon path.) a `GtkIconTheme` NULL-terminated array of directories that are searched for icon themes Sets the name of the icon theme that the `GtkIconTheme` object uses overriding system configuration. This function cannot be called on the icon theme objects returned from [func@Gtk.IconTheme.get_for_display]. a `GtkIconTheme` name of icon theme to use instead of configured theme, or %NULL to unset a previously set custom theme The display that this icon theme object is attached to. The icon names that are supported by the icon theme. Resource paths that will be looked at when looking for icons, similar to search paths. The resources are considered as part of the hicolor icon theme and must be located in subdirectories that are defined in the hicolor icon theme, such as `@path/16x16/actions/run.png`. Icons that are directly placed in the resource path instead of a subdirectory are also considered as ultimate fallback. The search path for this icon theme. When looking for icons, GTK will search for a subdirectory of one or more of the directories in the search path with the same name as the icon theme containing an index.theme file. (Themes from multiple of the path elements are combined to allow themes to be extended by adding icons in the user’s home directory.) The name of the icon theme that is being used. Unless set to a different value, this will be the value of the `GtkSettings:gtk-icon-theme-name` property of the `GtkSettings` object associated to the display of the icontheme object. Emitted when the icon theme changes. This can happen because current icon theme is switched or because GTK detects that a change has occurred in the contents of the current icon theme. Error codes for `GtkIconTheme` operations. The icon specified does not exist in the theme An unspecified error occurred. Registers an error quark for [class@Gtk.IconTheme] errors. the error quark `GtkIconView` is a widget which displays data in a grid of icons. `GtkIconView` provides an alternative view on a `GtkTreeModel`. It displays the model as a grid of icons with labels. Like [class@Gtk.TreeView], it allows to select one or multiple items (depending on the selection mode, see [method@Gtk.IconView.set_selection_mode]). In addition to selection with the arrow keys, `GtkIconView` supports rubberband selection, which is controlled by dragging the pointer. Note that if the tree model is backed by an actual tree store (as opposed to a flat list where the mapping to icons is obvious), `GtkIconView` will only display the first level of the tree and ignore the tree’s branches. ## CSS nodes ``` iconview.view ╰── [rubberband] ``` `GtkIconView` has a single CSS node with name iconview and style class .view. For rubberband selection, a subnode with name rubberband is used. Use [class@Gtk.GridView] instead Creates a new `GtkIconView` widget Use [class@Gtk.GridView] instead A newly created `GtkIconView` widget Creates a new `GtkIconView` widget using the specified @area to layout cells inside the icons. Use [class@Gtk.GridView] instead A newly created `GtkIconView` widget the `GtkCellArea` to use to layout cells Creates a new `GtkIconView` widget with the model @model. Use [class@Gtk.GridView] instead A newly created `GtkIconView` widget. The model. Creates a `GdkPaintable` representation of the item at @path. This image is used for a drag icon. Use [class@Gtk.GridView] instead a newly-allocated `GdkPaintable` of the drag icon. a `GtkIconView` a `GtkTreePath` in @icon_view Turns @icon_view into a drop destination for automatic DND. Calling this method sets `GtkIconView`:reorderable to %FALSE. Use [class@Gtk.GridView] instead a `GtkIconView` the formats that the drag will support the bitmask of possible actions for a drag to this widget Turns @icon_view into a drag source for automatic DND. Calling this method sets `GtkIconView`:reorderable to %FALSE. Use [class@Gtk.GridView] instead a `GtkIconView` Mask of allowed buttons to start drag the formats that the drag will support the bitmask of possible actions for a drag from this widget Gets the setting set by gtk_icon_view_set_activate_on_single_click(). Use [class@Gtk.GridView] instead %TRUE if item-activated will be emitted on a single click a `GtkIconView` Fills the bounding rectangle in widget coordinates for the cell specified by @path and @cell. If @cell is %NULL the main cell area is used. This function is only valid if @icon_view is realized. Use [class@Gtk.GridView] instead %FALSE if there is no such item, %TRUE otherwise a `GtkIconView` a `GtkTreePath` a `GtkCellRenderer` rectangle to fill with cell rect Returns the value of the ::column-spacing property. Use [class@Gtk.GridView] instead the space between columns a `GtkIconView` Returns the value of the ::columns property. Use [class@Gtk.GridView] instead the number of columns, or -1 a `GtkIconView` Fills in @path and @cell with the current cursor path and cell. If the cursor isn’t currently set, then *@path will be %NULL. If no cell currently has focus, then *@cell will be %NULL. The returned `GtkTreePath` must be freed with gtk_tree_path_free(). Use [class@Gtk.GridView] instead %TRUE if the cursor is set. A `GtkIconView` Return location for the current cursor path Return location the current focus cell Determines the destination item for a given position. Use [class@Gtk.GridView] instead whether there is an item at the given position. a `GtkIconView` the position to determine the destination item for the position to determine the destination item for Return location for the path of the item Return location for the drop position Gets information about the item that is highlighted for feedback. Use [class@Gtk.GridView] instead a `GtkIconView` Return location for the path of the highlighted item Return location for the drop position Gets the path and cell for the icon at the given position. Use [class@Gtk.GridView] instead %TRUE if an item exists at the specified position A `GtkIconView`. The x position to be identified The y position to be identified Return location for the path Return location for the renderer responsible for the cell at (@x, @y) Gets the column in which the item @path is currently displayed. Column numbers start at 0. Use [class@Gtk.GridView] instead The column in which the item is displayed a `GtkIconView` the `GtkTreePath` of the item Returns the value of the ::item-orientation property which determines whether the labels are drawn beside the icons instead of below. Use [class@Gtk.GridView] instead the relative position of texts and icons a `GtkIconView` Returns the value of the ::item-padding property. Use [class@Gtk.GridView] instead the padding around items a `GtkIconView` Gets the row in which the item @path is currently displayed. Row numbers start at 0. Use [class@Gtk.GridView] instead The row in which the item is displayed a `GtkIconView` the `GtkTreePath` of the item Returns the value of the ::item-width property. Use [class@Gtk.GridView] instead the width of a single item, or -1 a `GtkIconView` Returns the value of the ::margin property. Use [class@Gtk.GridView] instead the space at the borders a `GtkIconView` Returns the column with markup text for @icon_view. Use [class@Gtk.GridView] instead the markup column, or -1 if it’s unset. A `GtkIconView`. Returns the model the `GtkIconView` is based on. Returns %NULL if the model is unset. Use [class@Gtk.GridView] instead The currently used `GtkTreeModel` a `GtkIconView` Gets the path for the icon at the given position. Use [class@Gtk.GridView] instead The `GtkTreePath` corresponding to the icon or %NULL if no icon exists at that position. A `GtkIconView`. The x position to be identified The y position to be identified Returns the column with pixbufs for @icon_view. Use [class@Gtk.GridView] instead the pixbuf column, or -1 if it’s unset. A `GtkIconView`. Retrieves whether the user can reorder the list via drag-and-drop. See gtk_icon_view_set_reorderable(). Use [class@Gtk.GridView] instead %TRUE if the list can be reordered. a `GtkIconView` Returns the value of the ::row-spacing property. Use [class@Gtk.GridView] instead the space between rows a `GtkIconView` Creates a list of paths of all selected items. Additionally, if you are planning on modifying the model after calling this function, you may want to convert the returned list into a list of `GtkTreeRowReferences`. To do this, you can use gtk_tree_row_reference_new(). To free the return value, use `g_list_free_full`: |[<!-- language="C" --> GtkWidget *icon_view = gtk_icon_view_new (); // Use icon_view GList *list = gtk_icon_view_get_selected_items (GTK_ICON_VIEW (icon_view)); // use list g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); ]| Use [class@Gtk.GridView] instead A `GList` containing a `GtkTreePath` for each selected row. A `GtkIconView`. Gets the selection mode of the @icon_view. Use [class@Gtk.GridView] instead the current selection mode A `GtkIconView`. Returns the value of the ::spacing property. Use [class@Gtk.GridView] instead the space between cells a `GtkIconView` Returns the column with text for @icon_view. Use [class@Gtk.GridView] instead the text column, or -1 if it’s unset. A `GtkIconView`. Returns the column of @icon_view’s model which is being used for displaying tooltips on @icon_view’s rows. Use [class@Gtk.GridView] instead the index of the tooltip column that is currently being used, or -1 if this is disabled. a `GtkIconView` This function is supposed to be used in a `GtkWidget::query-tooltip` signal handler for `GtkIconView`. The @x, @y and @keyboard_tip values which are received in the signal handler, should be passed to this function without modification. The return value indicates whether there is an icon view item at the given coordinates (%TRUE) or not (%FALSE) for mouse tooltips. For keyboard tooltips the item returned will be the cursor item. When %TRUE, then any of @model, @path and @iter which have been provided will be set to point to that row and the corresponding model. Use [class@Gtk.GridView] instead whether or not the given tooltip context points to an item an `GtkIconView` the x coordinate (relative to widget coordinates) the y coordinate (relative to widget coordinates) whether this is a keyboard tooltip or not a pointer to receive a `GtkTreeModel` a pointer to receive a `GtkTreePath` a pointer to receive a `GtkTreeIter` Sets @start_path and @end_path to be the first and last visible path. Note that there may be invisible paths in between. Both paths should be freed with gtk_tree_path_free() after use. Use [class@Gtk.GridView] instead %TRUE, if valid paths were placed in @start_path and @end_path A `GtkIconView` Return location for start of region Return location for end of region Activates the item determined by @path. Use [class@Gtk.GridView] instead A `GtkIconView` The `GtkTreePath` to be activated Returns %TRUE if the icon pointed to by @path is currently selected. If @path does not point to a valid location, %FALSE is returned. Use [class@Gtk.GridView] instead %TRUE if @path is selected. A `GtkIconView`. A `GtkTreePath` to check selection on. Moves the alignments of @icon_view to the position specified by @path. @row_align determines where the row is placed, and @col_align determines where @column is placed. Both are expected to be between 0.0 and 1.0. 0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 means center. If @use_align is %FALSE, then the alignment arguments are ignored, and the tree does the minimum amount of work to scroll the item onto the screen. This means that the item will be scrolled to the edge closest to its current position. If the item is currently visible on the screen, nothing is done. This function only works if the model is set, and @path is a valid row on the model. If the model changes before the @icon_view is realized, the centered path will be modified to reflect this change. Use [class@Gtk.GridView] instead A `GtkIconView` The path of the item to move to. whether to use alignment arguments, or %FALSE. The vertical alignment of the item specified by @path. The horizontal alignment of the item specified by @path. Selects all the icons. @icon_view must has its selection mode set to %GTK_SELECTION_MULTIPLE. Use [class@Gtk.GridView] instead A `GtkIconView`. Selects the row at @path. Use [class@Gtk.GridView] instead A `GtkIconView`. The `GtkTreePath` to be selected. Calls a function for each selected icon. Note that the model or selection cannot be modified from within this function. Use [class@Gtk.GridView] instead A `GtkIconView`. The function to call for each selected icon. User data to pass to the function. Causes the `GtkIconView`::item-activated signal to be emitted on a single click instead of a double click. Use [class@Gtk.GridView] instead a `GtkIconView` %TRUE to emit item-activated on a single click Sets the ::column-spacing property which specifies the space which is inserted between the columns of the icon view. Use [class@Gtk.GridView] instead a `GtkIconView` the column spacing Sets the ::columns property which determines in how many columns the icons are arranged. If @columns is -1, the number of columns will be chosen automatically to fill the available area. Use [class@Gtk.GridView] instead a `GtkIconView` the number of columns Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular item. If @cell is not %NULL, then focus is given to the cell specified by it. Additionally, if @start_editing is %TRUE, then editing should be started in the specified cell. This function is often followed by `gtk_widget_grab_focus (icon_view)` in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized. Use [class@Gtk.GridView] instead A `GtkIconView` A `GtkTreePath` One of the cell renderers of @icon_view %TRUE if the specified cell should start being edited. Sets the item that is highlighted for feedback. Use [class@Gtk.GridView] instead a `GtkIconView` The path of the item to highlight Specifies where to drop, relative to the item Sets the ::item-orientation property which determines whether the labels are drawn beside the icons instead of below. Use [class@Gtk.GridView] instead a `GtkIconView` the relative position of texts and icons Sets the `GtkIconView`:item-padding property which specifies the padding around each of the icon view’s items. Use [class@Gtk.GridView] instead a `GtkIconView` the item padding Sets the ::item-width property which specifies the width to use for each item. If it is set to -1, the icon view will automatically determine a suitable item size. Use [class@Gtk.GridView] instead a `GtkIconView` the width for each item Sets the ::margin property which specifies the space which is inserted at the top, bottom, left and right of the icon view. Use [class@Gtk.GridView] instead a `GtkIconView` the margin Sets the column with markup information for @icon_view to be @column. The markup column must be of type `G_TYPE_STRING`. If the markup column is set to something, it overrides the text column set by gtk_icon_view_set_text_column(). Use [class@Gtk.GridView] instead A `GtkIconView`. A column in the currently used model, or -1 to display no text Sets the model for a `GtkIconView`. If the @icon_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. Use [class@Gtk.GridView] instead A `GtkIconView`. The model. Sets the column with pixbufs for @icon_view to be @column. The pixbuf column must be of type `GDK_TYPE_PIXBUF` Use [class@Gtk.GridView] instead A `GtkIconView`. A column in the currently used model, or -1 to disable This function is a convenience function to allow you to reorder models that support the `GtkTreeDragSourceIface` and the `GtkTreeDragDestIface`. Both `GtkTreeStore` and `GtkListStore` support these. If @reorderable is %TRUE, then the user can reorder the model by dragging and dropping rows. The developer can listen to these changes by connecting to the model's row_inserted and row_deleted signals. The reordering is implemented by setting up the icon view as a drag source and destination. Therefore, drag and drop can not be used in a reorderable view for any other purpose. This function does not give you any degree of control over the order -- any reordering is allowed. If more control is needed, you should probably handle drag and drop manually. Use [class@Gtk.GridView] instead A `GtkIconView`. %TRUE, if the list of items can be reordered. Sets the ::row-spacing property which specifies the space which is inserted between the rows of the icon view. Use [class@Gtk.GridView] instead a `GtkIconView` the row spacing Sets the selection mode of the @icon_view. Use [class@Gtk.GridView] instead A `GtkIconView`. The selection mode Sets the ::spacing property which specifies the space which is inserted between the cells (i.e. the icon and the text) of an item. Use [class@Gtk.GridView] instead a `GtkIconView` the spacing Sets the column with text for @icon_view to be @column. The text column must be of type `G_TYPE_STRING`. Use [class@Gtk.GridView] instead A `GtkIconView`. A column in the currently used model, or -1 to display no text Sets the tip area of @tooltip to the area which @cell occupies in the item pointed to by @path. See also gtk_tooltip_set_tip_area(). See also gtk_icon_view_set_tooltip_column() for a simpler alternative. Use [class@Gtk.GridView] instead a `GtkIconView` a `GtkTooltip` a `GtkTreePath` a `GtkCellRenderer` If you only plan to have simple (text-only) tooltips on full items, you can use this function to have `GtkIconView` handle these automatically for you. @column should be set to the column in @icon_view’s model containing the tooltip texts, or -1 to disable this feature. When enabled, `GtkWidget:has-tooltip` will be set to %TRUE and @icon_view will connect a `GtkWidget::query-tooltip` signal handler. Note that the signal handler sets the text with gtk_tooltip_set_markup(), so &, <, etc have to be escaped in the text. Use [class@Gtk.GridView] instead a `GtkIconView` an integer, which is a valid column number for @icon_view’s model Sets the tip area of @tooltip to be the area covered by the item at @path. See also gtk_icon_view_set_tooltip_column() for a simpler alternative. See also gtk_tooltip_set_tip_area(). Use [class@Gtk.GridView] instead a `GtkIconView` a `GtkTooltip` a `GtkTreePath` Unselects all the icons. Use [class@Gtk.GridView] instead A `GtkIconView`. Unselects the row at @path. Use [class@Gtk.GridView] instead A `GtkIconView`. The `GtkTreePath` to be unselected. Undoes the effect of gtk_icon_view_enable_model_drag_dest(). Calling this method sets `GtkIconView`:reorderable to %FALSE. Use [class@Gtk.GridView] instead a `GtkIconView` Undoes the effect of gtk_icon_view_enable_model_drag_source(). Calling this method sets `GtkIconView`:reorderable to %FALSE. Use [class@Gtk.GridView] instead a `GtkIconView` The activate-on-single-click property specifies whether the "item-activated" signal will be emitted after a single click. The `GtkCellArea` used to layout cell renderers for this view. If no area is specified when creating the icon view with gtk_icon_view_new_with_area() a `GtkCellAreaBox` will be used. The column-spacing property specifies the space which is inserted between the columns of the icon view. The columns property contains the number of the columns in which the items should be displayed. If it is -1, the number of columns will be chosen automatically to fill the available area. The item-orientation property specifies how the cells (i.e. the icon and the text) of the item are positioned relative to each other. The item-padding property specifies the padding around each of the icon view's item. The item-width property specifies the width to use for each item. If it is set to -1, the icon view will automatically determine a suitable item size. The margin property specifies the space which is inserted at the edges of the icon view. The ::markup-column property contains the number of the model column containing markup information to be displayed. The markup column must be of type `G_TYPE_STRING`. If this property and the :text-column property are both set to column numbers, it overrides the text column. If both are set to -1, no texts are displayed. The model of the icon view. The ::pixbuf-column property contains the number of the model column containing the pixbufs which are displayed. The pixbuf column must be of type `GDK_TYPE_PIXBUF`. Setting this property to -1 turns off the display of pixbufs. The reorderable property specifies if the items can be reordered by DND. The row-spacing property specifies the space which is inserted between the rows of the icon view. The ::selection-mode property specifies the selection mode of icon view. If the mode is %GTK_SELECTION_MULTIPLE, rubberband selection is enabled, for the other modes, only keyboard selection is possible. The spacing property specifies the space which is inserted between the cells (i.e. the icon and the text) of an item. The ::text-column property contains the number of the model column containing the texts which are displayed. The text column must be of type `G_TYPE_STRING`. If this property and the :markup-column property are both set to -1, no texts are displayed. The column of the icon view model which is being used for displaying tooltips on it's rows. A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user activates the currently focused item. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control activation programmatically. The default bindings for this signal are Space, Return and Enter. whether the item was activated The ::item-activated signal is emitted when the method gtk_icon_view_item_activated() is called, when the user double clicks an item with the "activate-on-single-click" property set to %FALSE, or when the user single clicks an item when the "activate-on-single-click" property set to %TRUE. It is also emitted when a non-editable item is selected and one of the keys: Space, Return or Enter is pressed. the `GtkTreePath` for the activated item The ::move-cursor signal is a [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user initiates a cursor movement. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal include - Arrow keys which move by individual steps - Home/End keys which move to the first/last item - PageUp/PageDown which move by "pages" All of these will extend the selection when combined with the Shift modifier. whether the cursor was moved the granularity of the move, as a `GtkMovementStep` the number of @step units to move whether to extend the selection whether to modify the selection A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user selects all items. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control selection programmatically. The default binding for this signal is Ctrl-a. A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user selects the item that is currently focused. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control selection programmatically. There is no default binding for this signal. The ::selection-changed signal is emitted when the selection (i.e. the set of selected items) changes. A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user toggles whether the currently focused item is selected or not. The exact effect of this depend on the selection mode. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control selection programmatically. There is no default binding for this signal is Ctrl-Space. A [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user unselects all items. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control selection programmatically. The default binding for this signal is Ctrl-Shift-a. An enum for determining where a dropped item goes. no drop possible dropped item replaces the item dropped item is inserted to the left dropped item is inserted to the right dropped item is inserted above dropped item is inserted below A function used by gtk_icon_view_selected_foreach() to map all selected rows. It will be called on every selected row in the view. a `GtkIconView` The `GtkTreePath` of a selected row user data The `GtkImage` widget displays an image.  Various kinds of object can be displayed as an image; most typically, you would load a `GdkTexture` from a file, using the convenience function [ctor@Gtk.Image.new_from_file], for instance: ```c GtkWidget *image = gtk_image_new_from_file ("myfile.png"); ``` If the file isn’t loaded successfully, the image will contain a “broken image” icon similar to that used in many web browsers. If you want to handle errors in loading the file yourself, for example by displaying an error message, then load the image with [ctor@Gdk.Texture.new_from_file], then create the `GtkImage` with [ctor@Gtk.Image.new_from_paintable]. Sometimes an application will want to avoid depending on external data files, such as image files. See the documentation of `GResource` inside GIO, for details. In this case, [property@Gtk.Image:resource], [ctor@Gtk.Image.new_from_resource], and [method@Gtk.Image.set_from_resource] should be used. `GtkImage` displays its image as an icon, with a size that is determined by the application. See [class@Gtk.Picture] if you want to show an image at is actual size. ## CSS nodes `GtkImage` has a single CSS node with the name `image`. The style classes `.normal-icons` or `.large-icons` may appear, depending on the [property@Gtk.Image:icon-size] property. ## Accessibility `GtkImage` uses the `GTK_ACCESSIBLE_ROLE_IMG` role. Creates a new empty `GtkImage` widget. a newly created `GtkImage` widget. Creates a new `GtkImage` displaying the file @filename. If the file isn’t found or can’t be loaded, the resulting `GtkImage` will display a “broken image” icon. This function never returns %NULL, it always returns a valid `GtkImage` widget. If you need to detect failures to load the file, use [ctor@Gdk.Texture.new_from_file] to load the file yourself, then create the `GtkImage` from the texture. The storage type (see [method@Gtk.Image.get_storage_type]) of the returned image is not defined, it will be whatever is appropriate for displaying the file. a new `GtkImage` a filename Creates a `GtkImage` displaying an icon from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately. a new `GtkImage` displaying the themed icon an icon Creates a `GtkImage` displaying an icon from the current icon theme. If the icon name isn’t known, a “broken image” icon will be displayed instead. If the current icon theme is changed, the icon will be updated appropriately. a new `GtkImage` displaying the themed icon an icon name Creates a new `GtkImage` displaying @paintable. The `GtkImage` does not assume a reference to the paintable; you still need to unref it if you own references. `GtkImage` will add its own reference rather than adopting yours. The `GtkImage` will track changes to the @paintable and update its size and contents in response to it. a new `GtkImage` a `GdkPaintable` Creates a new `GtkImage` displaying @pixbuf. The `GtkImage` does not assume a reference to the pixbuf; you still need to unref it if you own references. `GtkImage` will add its own reference rather than adopting yours. This is a helper for [ctor@Gtk.Image.new_from_paintable], and you can't get back the exact pixbuf once this is called, only a texture. Note that this function just creates an `GtkImage` from the pixbuf. The `GtkImage` created will not react to state changes. Should you want that, you should use [ctor@Gtk.Image.new_from_icon_name]. Use [ctor@Gtk.Image.new_from_paintable] and [ctor@Gdk.Texture.new_for_pixbuf] instead a new `GtkImage` a `GdkPixbuf` Creates a new `GtkImage` displaying the resource file @resource_path. If the file isn’t found or can’t be loaded, the resulting `GtkImage` will display a “broken image” icon. This function never returns %NULL, it always returns a valid `GtkImage` widget. If you need to detect failures to load the file, use [ctor@GdkPixbuf.Pixbuf.new_from_file] to load the file yourself, then create the `GtkImage` from the pixbuf. The storage type (see [method@Gtk.Image.get_storage_type]) of the returned image is not defined, it will be whatever is appropriate for displaying the file. a new `GtkImage` a resource path Resets the image to be empty. a `GtkImage` Gets the `GIcon` being displayed by the `GtkImage`. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_GICON (see [method@Gtk.Image.get_storage_type]). The caller of this function does not own a reference to the returned `GIcon`. a `GIcon` a `GtkImage` Gets the icon name and size being displayed by the `GtkImage`. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_ICON_NAME (see [method@Gtk.Image.get_storage_type]). The returned string is owned by the `GtkImage` and should not be freed. the icon name a `GtkImage` Gets the icon size used by the @image when rendering icons. the image size used by icons a `GtkImage` Gets the image `GdkPaintable` being displayed by the `GtkImage`. The storage type of the image must be %GTK_IMAGE_EMPTY or %GTK_IMAGE_PAINTABLE (see [method@Gtk.Image.get_storage_type]). The caller of this function does not own a reference to the returned paintable. the displayed paintable a `GtkImage` Gets the pixel size used for named icons. the pixel size used for named icons. a `GtkImage` Gets the type of representation being used by the `GtkImage` to store image data. If the `GtkImage` has no image data, the return value will be %GTK_IMAGE_EMPTY. image representation being used a `GtkImage` Sets a `GtkImage` to show a file. See [ctor@Gtk.Image.new_from_file] for details. a `GtkImage` a filename Sets a `GtkImage` to show a `GIcon`. See [ctor@Gtk.Image.new_from_gicon] for details. a `GtkImage` an icon Sets a `GtkImage` to show a named icon. See [ctor@Gtk.Image.new_from_icon_name] for details. a `GtkImage` an icon name Sets a `GtkImage` to show a `GdkPaintable`. See [ctor@Gtk.Image.new_from_paintable] for details. a `GtkImage` a `GdkPaintable` Sets a `GtkImage` to show a `GdkPixbuf`. See [ctor@Gtk.Image.new_from_pixbuf] for details. Note: This is a helper for [method@Gtk.Image.set_from_paintable], and you can't get back the exact pixbuf once this is called, only a paintable. Use [method@Gtk.Image.set_from_paintable] instead a `GtkImage` a `GdkPixbuf` or `NULL` Sets a `GtkImage` to show a resource. See [ctor@Gtk.Image.new_from_resource] for details. a `GtkImage` a resource path Suggests an icon size to the theme for named icons. a `GtkImage` the new icon size Sets the pixel size to use for named icons. If the pixel size is set to a value != -1, it is used instead of the icon size set by [method@Gtk.Image.set_from_icon_name]. a `GtkImage` the new pixel size A path to the file to display. The `GIcon` displayed in the GtkImage. For themed icons, If the icon theme is changed, the image will be updated automatically. The name of the icon in the icon theme. If the icon theme is changed, the image will be updated automatically. The symbolic size to display icons at. The `GdkPaintable` to display. The size in pixels to display icons at. If set to a value != -1, this property overrides the [property@Gtk.Image:icon-size] property for images of type `GTK_IMAGE_ICON_NAME`. A path to a resource file to display. The representation being used for image data. Whether the icon displayed in the `GtkImage` will use standard icon names fallback. The value of this property is only relevant for images of type %GTK_IMAGE_ICON_NAME and %GTK_IMAGE_GICON. Describes the image data representation used by a [class@Gtk.Image]. If you want to get the image from the widget, you can only get the currently-stored representation; for instance, if the gtk_image_get_storage_type() returns %GTK_IMAGE_PAINTABLE, then you can call gtk_image_get_paintable(). For empty images, you can request any storage type (call any of the "get" functions), but they will all return %NULL values. there is no image displayed by the widget the widget contains a named icon the widget contains a `GIcon` the widget contains a `GdkPaintable` `GtkInfoBar` can be used to show messages to the user without a dialog.  It is often temporarily shown at the top or bottom of a document. In contrast to [class@Gtk.Dialog], which has an action area at the bottom, `GtkInfoBar` has an action area at the side. The API of `GtkInfoBar` is very similar to `GtkDialog`, allowing you to add buttons to the action area with [method@Gtk.InfoBar.add_button] or [ctor@Gtk.InfoBar.new_with_buttons]. The sensitivity of action widgets can be controlled with [method@Gtk.InfoBar.set_response_sensitive]. To add widgets to the main content area of a `GtkInfoBar`, use [method@Gtk.InfoBar.add_child]. Similar to [class@Gtk.MessageDialog], the contents of a `GtkInfoBar` can by classified as error message, warning, informational message, etc, by using [method@Gtk.InfoBar.set_message_type]. GTK may use the message type to determine how the message is displayed. A simple example for using a `GtkInfoBar`: ```c GtkWidget *message_label; GtkWidget *widget; GtkWidget *grid; GtkInfoBar *bar; // set up info bar widget = gtk_info_bar_new (); bar = GTK_INFO_BAR (widget); grid = gtk_grid_new (); message_label = gtk_label_new (""); gtk_info_bar_add_child (bar, message_label); gtk_info_bar_add_button (bar, _("_OK"), GTK_RESPONSE_OK); g_signal_connect (bar, "response", G_CALLBACK (gtk_widget_hide), NULL); gtk_grid_attach (GTK_GRID (grid), widget, 0, 2, 1, 1); // ... // show an error message gtk_label_set_text (GTK_LABEL (message_label), "An error occurred!"); gtk_info_bar_set_message_type (bar, GTK_MESSAGE_ERROR); gtk_widget_show (bar); ``` # GtkInfoBar as GtkBuildable `GtkInfoBar` supports a custom `<action-widgets>` element, which can contain multiple `<action-widget>` elements. The “response” attribute specifies a numeric response, and the content of the element is the id of widget (which should be a child of the dialogs @action_area). `GtkInfoBar` supports adding action widgets by specifying “action” as the “type” attribute of a `<child>` element. The widget will be added either to the action area. The response id has to be associated with the action widget using the `<action-widgets>` element. # CSS nodes `GtkInfoBar` has a single CSS node with name infobar. The node may get one of the style classes .info, .warning, .error or .question, depending on the message type. If the info bar shows a close button, that button will have the .close style class applied. There is no replacement in GTK for an "info bar" widget; you can use [class@Gtk.Revealer] with a [class@Gtk.Box] containing a [class@Gtk.Label] and an optional [class@Gtk.Button], according to your application's design. Creates a new `GtkInfoBar` object. a new `GtkInfoBar` object Creates a new `GtkInfoBar` with buttons. Button text/response ID pairs should be listed, with a %NULL pointer ending the list. A response ID can be any positive number, or one of the values in the `GtkResponseType` enumeration. If the user clicks one of these dialog buttons, GtkInfoBar will emit the [signal@Gtk.InfoBar::response] signal with the corresponding response ID. a new `GtkInfoBar` ext to go in first button response ID for first button, then additional buttons, ending with %NULL Add an activatable widget to the action area of a `GtkInfoBar`. This also connects a signal handler that will emit the [signal@Gtk.InfoBar::response] signal on the message area when the widget is activated. The widget is appended to the end of the message areas action area. a `GtkInfoBar` an activatable widget response ID for @child Adds a button with the given text. Clicking the button will emit the [signal@Gtk.InfoBar::response] signal with the given response_id. The button is appended to the end of the info bar's action area. The button widget is returned, but usually you don't need it. the `GtkButton` widget that was added a `GtkInfoBar` text of button response ID for the button Adds multiple buttons. This is the same as calling [method@Gtk.InfoBar.add_button] repeatedly. The variable argument list should be %NULL-terminated as with [ctor@Gtk.InfoBar.new_with_buttons]. Each button must have both text and response ID. a `GtkInfoBar` button text response ID for first button, then more text-response_id pairs, ending with %NULL Adds a widget to the content area of the info bar. a `GtkInfoBar` the child to be added Returns the message type of the message area. the message type of the message area. a `GtkInfoBar` Returns whether the info bar is currently revealed. the current value of the [property@Gtk.InfoBar:revealed] property a `GtkInfoBar` Returns whether the widget will display a standard close button. %TRUE if the widget displays standard close button a `GtkInfoBar` Removes a widget from the action area of @info_bar. The widget must have been put there by a call to [method@Gtk.InfoBar.add_action_widget] or [method@Gtk.InfoBar.add_button]. a `GtkInfoBar` an action widget to remove Removes a widget from the content area of the info bar. a `GtkInfoBar` a child that has been added to the content area Emits the “response” signal with the given @response_id. a `GtkInfoBar` a response ID Sets the last widget in the info bar’s action area with the given response_id as the default widget for the dialog. Pressing “Enter” normally activates the default widget. Note that this function currently requires @info_bar to be added to a widget hierarchy. a `GtkInfoBar` a response ID Sets the message type of the message area. GTK uses this type to determine how the message is displayed. a `GtkInfoBar` a `GtkMessageType` Sets the sensitivity of action widgets for @response_id. Calls `gtk_widget_set_sensitive (widget, setting)` for each widget in the info bars’s action area with the given @response_id. A convenient way to sensitize/desensitize buttons. a `GtkInfoBar` a response ID TRUE for sensitive Sets whether the `GtkInfoBar` is revealed. Changing this will make @info_bar reveal or conceal itself via a sliding transition. Note: this does not show or hide @info_bar in the [property@Gtk.Widget:visible] sense, so revealing has no effect if [property@Gtk.Widget:visible] is %FALSE. a `GtkInfoBar` The new value of the property If true, a standard close button is shown. When clicked it emits the response %GTK_RESPONSE_CLOSE. a `GtkInfoBar` %TRUE to include a close button The type of the message. The type may be used to determine the appearance of the info bar. Whether the info bar shows its contents. Whether to include a standard close button. Gets emitted when the user uses a keybinding to dismiss the info bar. The ::close signal is a [keybinding signal](class.SignalAction.html). The default binding for this signal is the Escape key. Emitted when an action widget is clicked. The signal is also emitted when the application programmer calls [method@Gtk.InfoBar.response]. The @response_id depends on which action widget was clicked. the response ID Describes hints that might be taken into account by input methods or applications. Note that input methods may already tailor their behaviour according to the [enum@InputPurpose] of the entry. Some common sense is expected when using these flags - mixing %GTK_INPUT_HINT_LOWERCASE with any of the uppercase hints makes no sense. This enumeration may be extended in the future; input methods should ignore unknown values. No special behaviour suggested Suggest checking for typos Suggest not checking for typos Suggest word completion Suggest to convert all text to lowercase Suggest to capitalize all text Suggest to capitalize the first character of each word Suggest to capitalize the first word of each sentence Suggest to not show an onscreen keyboard (e.g for a calculator that already has all the keys). The text is vertical Suggest offering Emoji support Suggest not offering Emoji support Request that the input method should not update personalized data (like typing history) Describes primary purpose of the input widget. This information is useful for on-screen keyboards and similar input methods to decide which keys should be presented to the user. Note that the purpose is not meant to impose a totally strict rule about allowed characters, and does not replace input validation. It is fine for an on-screen keyboard to let the user override the character set restriction that is expressed by the purpose. The application is expected to validate the entry contents, even if it specified a purpose. The difference between %GTK_INPUT_PURPOSE_DIGITS and %GTK_INPUT_PURPOSE_NUMBER is that the former accepts only digits while the latter also some punctuation (like commas or points, plus, minus) and “e” or “E” as in 3.14E+000. This enumeration may be extended in the future; input methods should interpret unknown values as “free form”. Allow any character Allow only alphabetic characters Allow only digits Edited field expects numbers Edited field expects phone number Edited field expects URL Edited field expects email address Edited field expects the name of a person Like %GTK_INPUT_PURPOSE_FREE_FORM, but characters are hidden Like %GTK_INPUT_PURPOSE_DIGITS, but characters are hidden Allow any character, in addition to control codes `GtkInscription` is a widget to show text in a predefined area. You likely want to use `GtkLabel` instead as this widget is intended only for a small subset of use cases. The main scenario envisaged is inside lists such as `GtkColumnView`. While a `GtkLabel` sizes itself depending on the text that is displayed, `GtkInscription` is given a size and inscribes the given text into that space as well as it can. Users of this widget should take care to plan behaviour for the common case where the text doesn't fit exactly in the allocated space. Creates a new `GtkInscription` with the given text. a new `GtkInscription` The text to display. Gets the inscription's attribute list. the attribute list a `GtkInscription` Gets the `min-chars` of the inscription. See the [property@Gtk.Inscription:min-chars] property. the min-chars property a `GtkInscription` Gets the `min-lines` of the inscription. See the [property@Gtk.Inscription:min-lines] property. the min-lines property a `GtkInscription` Gets the `nat-chars` of the inscription. See the [property@Gtk.Inscription:nat-chars] property. the nat-chars property a `GtkInscription` Gets the `nat-lines` of the inscription. See the [property@Gtk.Inscription:nat-lines] property. the nat-lines property a `GtkInscription` Gets the text that is displayed. The displayed text a `GtkInscription` Gets the inscription's overflow method. the overflow method a `GtkInscription` Returns line wrap mode used by the inscription. See [method@Gtk.Inscription.set_wrap_mode]. the line wrap mode a `GtkInscription` Gets the `xalign` of the inscription. See the [property@Gtk.Inscription:xalign] property. the xalign property a `GtkInscription` Gets the `yalign` of the inscription. See the [property@Gtk.Inscription:yalign] property. the yalign property a `GtkInscription` Apply attributes to the inscription text. These attributes will not be evaluated for sizing the inscription. a `GtkInscription` a [struct@Pango.AttrList] Utility function to set the text and attributes to be displayed. See the [property@Gtk.Inscription:markup] property. a `GtkInscription` The markup to display Sets the `min-chars` of the inscription. See the [property@Gtk.Inscription:min-chars] property. a `GtkInscription` the minimum number of characters that should fit, approximately Sets the `min-lines` of the inscription. See the [property@Gtk.Inscription:min-lines] property. a `GtkInscription` the minimum number of lines that should fit, approximately Sets the `nat-chars` of the inscription. See the [property@Gtk.Inscription:nat-chars] property. a `GtkInscription` the number of characters that should ideally fit, approximately Sets the `nat-lines` of the inscription. See the [property@Gtk.Inscription:nat-lines] property. a `GtkInscription` the number of lines that should ideally fit Sets the text to be displayed. a `GtkInscription` The text to display Sets what to do when the text doesn't fit. a `GtkInscription` the overflow method to use Controls how line wrapping is done. a `GtkInscription` the line wrapping mode Sets the `xalign` of the inscription. See the [property@Gtk.Inscription:xalign] property. a `GtkInscription` the new xalign value, between 0 and 1 Sets the `yalign` of the inscription. See the [property@Gtk.Inscription:yalign] property. a `GtkInscription` the new yalign value, between 0 and 1 A list of style attributes to apply to the text of the inscription. Utility property that sets both the [property@Gtk.Inscription:text] and [property@Gtk.Inscription:attributes] properties, mainly intended for use in GtkBuilder ui files to ease translation support and bindings. This function uses [func@Pango.parse_markup] to parse the markup into text and attributes. The markup must be valid. If you cannot ensure that, consider using [func@Pango.parse_markup] and setting the two properties yourself. The number of characters that should fit into the inscription at minimum. This influences the requested width, not the width actually given to the widget, which might turn out to be larger. Note that this is an approximate character width, so some characters might be wider and some might be thinner, so do not expect the number of characters to exactly match. If you set this property to 0, the inscription will not request any width at all and its width will be determined entirely by its surroundings. The number of lines that should fit into the inscription at minimum. This influences the requested height, not the height actually given to the widget, which might turn out to be larger. Note that this is an approximate line height, so if the text uses things like fancy Unicode or attribute that influence the height, the text might not fit. If you set this property to 0, the inscription will not request any height at all and its height will be determined entirely by its surroundings. The number of characters that should ideally fit into the inscription. This influences the requested width, not the width actually given to the widget. The widget might turn out larger as well as smaller. If this property is set to a value smaller than [property@Gtk.Inscription:min-chars], that value will be used. In particular, for the default value of 0, this will always be the case. The number of lines that should ideally fit into the inscription. This influences the requested height, not the height actually given to the widget. The widget might turn out larger as well as smaller. If this property is set to a value smaller than [property@Gtk.Inscription:min-lines], that value will be used. In particular, for the default value of 0, this will always be the case. The displayed text. The overflow method to use for the text. Controls how the line wrapping is done. Note that unlike `GtkLabel`, the default here is %PANGO_WRAP_WORD_CHAR. The horizontal alignment of the text inside the allocated size. Compare this to [property@Gtk.Widget:halign], which determines how the inscription's size allocation is positioned in the available space. The vertical alignment of the text inside the allocated size. Compare this to [property@Gtk.Widget:valign], which determines how the inscription's size allocation is positioned in the available space. The different methods to handle text in #GtkInscription when it doesn't fit the available space. Clip the remaining text Omit characters at the start of the text Omit characters at the middle of the text Omit characters at the end of the text Used for justifying the text inside a [class@Label] widget. The text is placed at the left edge of the label. The text is placed at the right edge of the label. The text is placed in the center of the label. The text is placed is distributed across the label. A `GtkShortcutTrigger` that triggers when a specific keyval and modifiers are pressed. Creates a `GtkShortcutTrigger` that will trigger whenever the key with the given @keyval and @modifiers is pressed. A new `GtkShortcutTrigger` The keyval to trigger for the modifiers that need to be present Gets the keyval that must be pressed to succeed triggering @self. the keyval a keyval `GtkShortcutTrigger` Gets the modifiers that must be present to succeed triggering @self. the modifiers a keyval `GtkShortcutTrigger` The key value for the trigger. The key modifiers for the trigger. The name used for the stock full offset included by `GtkLevelBar`. The name used for the stock high offset included by `GtkLevelBar`. The name used for the stock low offset included by `GtkLevelBar`. The `GtkLabel` widget displays a small amount of text. As the name implies, most labels are used to label another widget such as a [class@Button].  ## Shortcuts and Gestures `GtkLabel` supports the following keyboard shortcuts, when the cursor is visible: - <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. - <kbd>Ctrl</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&sol;</kbd> selects all. - <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&bsol;</kbd> unselects all. Additionally, the following signals have default keybindings: - [signal@Gtk.Label::activate-current-link] - [signal@Gtk.Label::copy-clipboard] - [signal@Gtk.Label::move-cursor] ## Actions `GtkLabel` defines a set of built-in actions: - `clipboard.copy` copies the text to the clipboard. - `clipboard.cut` doesn't do anything, since text in labels can't be deleted. - `clipboard.paste` doesn't do anything, since text in labels can't be edited. - `link.open` opens the link, when activated on a link inside the label. - `link.copy` copies the link to the clipboard, when activated on a link inside the label. - `menu.popup` opens the context menu. - `selection.delete` doesn't do anything, since text in labels can't be deleted. - `selection.select-all` selects all of the text, if the label allows selection. ## CSS nodes ``` label ├── [selection] ├── [link] ┊ ╰── [link] ``` `GtkLabel` has a single CSS node with the name label. A wide variety of style classes may be applied to labels, such as .title, .subtitle, .dim-label, etc. In the `GtkShortcutsWindow`, labels are used with the .keycap style class. If the label has a selection, it gets a subnode with name selection. If the label has links, there is one subnode per link. These subnodes carry the link or visited state depending on whether they have been visited. In this case, label node also gets a .link style class. ## GtkLabel as GtkBuildable The GtkLabel implementation of the GtkBuildable interface supports a custom `<attributes>` element, which supports any number of `<attribute>` elements. The `<attribute>` element has attributes named “name“, “value“, “start“ and “end“ and allows you to specify [struct@Pango.Attribute] values for this label. An example of a UI definition fragment specifying Pango attributes: ```xml <object class="GtkLabel"> <attributes> <attribute name="weight" value="PANGO_WEIGHT_BOLD"/> <attribute name="background" value="red" start="5" end="10"/> </attributes> </object> ``` The start and end attributes specify the range of characters to which the Pango attribute applies. If start and end are not specified, the attribute is applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup embedded in the translatable content instead. ## Accessibility `GtkLabel` uses the %GTK_ACCESSIBLE_ROLE_LABEL role. ## Mnemonics Labels may contain “mnemonics”. Mnemonics are underlined characters in the label, used for keyboard navigation. Mnemonics are created by providing a string with an underscore before the mnemonic character, such as `"_File"`, to the functions [ctor@Gtk.Label.new_with_mnemonic] or [method@Gtk.Label.set_text_with_mnemonic]. Mnemonics automatically activate any activatable widget the label is inside, such as a [class@Gtk.Button]; if the label is not inside the mnemonic’s target widget, you have to tell the label about the target using [method@Gtk.Label.set_mnemonic_widget]. Here’s a simple example where the label is inside a button: ```c // Pressing Alt+H will activate this button GtkWidget *button = gtk_button_new (); GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello"); gtk_button_set_child (GTK_BUTTON (button), label); ``` There’s a convenience function to create buttons with a mnemonic label already inside: ```c // Pressing Alt+H will activate this button GtkWidget *button = gtk_button_new_with_mnemonic ("_Hello"); ``` To create a mnemonic for a widget alongside the label, such as a [class@Gtk.Entry], you have to point the label at the entry with [method@Gtk.Label.set_mnemonic_widget]: ```c // Pressing Alt+H will focus the entry GtkWidget *entry = gtk_entry_new (); GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello"); gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry); ``` ## Markup (styled text) To make it easy to format text in a label (changing colors, fonts, etc.), label text can be provided in a simple markup format: Here’s how to create a label with a small font: ```c GtkWidget *label = gtk_label_new (NULL); gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>"); ``` (See the Pango manual for complete documentation] of available tags, [func@Pango.parse_markup]) The markup passed to [method@Gtk.Label.set_markup] must be valid; for example, literal `<`, `>` and `&` characters must be escaped as `&lt;`, `&gt;`, and `&amp;`. If you pass text obtained from the user, file, or a network to [method@Gtk.Label.set_markup], you’ll want to escape it with [func@GLib.markup_escape_text] or [func@GLib.markup_printf_escaped]. Markup strings are just a convenient way to set the [struct@Pango.AttrList] on a label; [method@Gtk.Label.set_attributes] may be a simpler way to set attributes in some cases. Be careful though; [struct@Pango.AttrList] tends to cause internationalization problems, unless you’re applying attributes to the entire string (i.e. unless you set the range of each attribute to [0, %G_MAXINT)). The reason is that specifying the start_index and end_index for a [struct@Pango.Attribute] requires knowledge of the exact string being displayed, so translations will cause problems. ## Selectable labels Labels can be made selectable with [method@Gtk.Label.set_selectable]. Selectable labels allow the user to copy the label contents to the clipboard. Only labels that contain useful-to-copy information—such as error messages—should be made selectable. ## Text layout A label can contain any number of paragraphs, but will have performance problems if it contains more than a small number. Paragraphs are separated by newlines or other paragraph separators understood by Pango. Labels can automatically wrap text if you call [method@Gtk.Label.set_wrap]. [method@Gtk.Label.set_justify] sets how the lines in a label align with one another. If you want to set how the label as a whole aligns in its available space, see the [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties. The [property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] properties can be used to control the size allocation of ellipsized or wrapped labels. For ellipsizing labels, if either is specified (and less than the actual text size), it is used as the minimum width, and the actual text size is used as the natural width of the label. For wrapping labels, width-chars is used as the minimum width, if specified, and max-width-chars is used as the natural width. Even if max-width-chars specified, wrapping labels will be rewrapped to use all of the available width. ## Links GTK supports markup for clickable hyperlinks in addition to regular Pango markup. The markup for links is borrowed from HTML, using the `<a>` with “href“, “title“ and “class“ attributes. GTK renders links similar to the way they appear in web browsers, with colored, underlined text. The “title“ attribute is displayed as a tooltip on the link. The “class“ attribute is used as style class on the CSS node for the link. An example of inline links looks like this: ```c const char *text = "Go to the " "<a href=\"https://www.gtk.org\" title=\"&lt;i&gt;Our&lt;/i&gt; website\">" "GTK website</a> for more..."; GtkWidget *label = gtk_label_new (NULL); gtk_label_set_markup (GTK_LABEL (label), text); ``` It is possible to implement custom handling for links and their tooltips with the [signal@Gtk.Label::activate-link] signal and the [method@Gtk.Label.get_current_uri] function. Creates a new label with the given text inside it. You can pass %NULL to get an empty label widget. the new `GtkLabel` The text of the label Creates a new `GtkLabel`, containing the text in @str. If characters in @str are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use '__' (two underscores). The first underlined character represents a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. If [method@Gtk.Label.set_mnemonic_widget] is not called, then the first activatable ancestor of the `GtkLabel` will be chosen as the mnemonic widget. For instance, if the label is inside a button or menu item, the button or menu item will automatically become the mnemonic widget and be activated by the mnemonic. the new `GtkLabel` The text of the label, with an underscore in front of the mnemonic character Gets the label's attribute list. This is the [struct@Pango.AttrList] that was set on the label using [method@Gtk.Label.set_attributes], if any. This function does not reflect attributes that come from the label's markup (see [method@Gtk.Label.set_markup]). If you want to get the effective attributes for the label, use `pango_layout_get_attributes (gtk_label_get_layout (self))`. the attribute list a `GtkLabel` Returns the URI for the currently active link in the label. The active link is the one under the mouse pointer or, in a selectable label, the link in which the text cursor is currently positioned. This function is intended for use in a [signal@Gtk.Label::activate-link] handler or for use in a [signal@Gtk.Widget::query-tooltip] handler. the currently active URI a `GtkLabel` Returns the ellipsizing position of the label. See [method@Gtk.Label.set_ellipsize]. `PangoEllipsizeMode` a `GtkLabel` Gets the extra menu model of @label. See [method@Gtk.Label.set_extra_menu]. the menu model a `GtkLabel` Returns the justification of the label. See [method@Gtk.Label.set_justify]. `GtkJustification` a `GtkLabel` Fetches the text from a label. The returned text includes any embedded underlines indicating mnemonics and Pango markup. (See [method@Gtk.Label.get_text]). the text of the label widget. This string is owned by the widget and must not be modified or freed. a `GtkLabel` Gets the `PangoLayout` used to display the label. The layout is useful to e.g. convert text positions to pixel positions, in combination with [method@Gtk.Label.get_layout_offsets]. The returned layout is owned by the @label so need not be freed by the caller. The @label is free to recreate its layout at any time, so it should be considered read-only. the [class@Pango.Layout] for this label a `GtkLabel` Obtains the coordinates where the label will draw its `PangoLayout`. The coordinates are useful to convert mouse events into coordinates inside the [class@Pango.Layout], e.g. to take some action if some part of the label is clicked. Remember when using the [class@Pango.Layout] functions you need to convert to and from pixels using PANGO_PIXELS() or [const@Pango.SCALE]. a `GtkLabel` location to store X offset of layout location to store Y offset of layout Gets the number of lines to which an ellipsized, wrapping label should be limited. See [method@Gtk.Label.set_lines]. The number of lines a `GtkLabel` Retrieves the desired maximum width of @label, in characters. See [method@Gtk.Label.set_width_chars]. the maximum width of the label in characters. a `GtkLabel` Return the mnemonic accelerator. If the label has been set so that it has a mnemonic key this function returns the keyval used for the mnemonic accelerator. If there is no mnemonic set up it returns `GDK_KEY_VoidSymbol`. GDK keyval usable for accelerators, or `GDK_KEY_VoidSymbol` a `GtkLabel` Retrieves the target of the mnemonic (keyboard shortcut) of this label. See [method@Gtk.Label.set_mnemonic_widget]. the target of the label’s mnemonic, or %NULL if none has been set and the default algorithm will be used. a `GtkLabel` Returns line wrap mode used by the label. See [method@Gtk.Label.set_natural_wrap_mode]. the natural line wrap mode a `GtkLabel` Returns whether the label is selectable. %TRUE if the user can copy text from the label a `GtkLabel` Gets the selected range of characters in the label. %TRUE if selection is non-empty a `GtkLabel` return location for start of selection, as a character offset return location for end of selection, as a character offset Returns whether the label is in single line mode. %TRUE when the label is in single line mode. a `GtkLabel` Gets the tabs for @self. The returned array will be %NULL if “standard” (8-space) tabs are used. Free the return value with [method@Pango.TabArray.free]. copy of default tab array, or %NULL if standard tabs are used; must be freed with [method@Pango.TabArray.free]. a `GtkLabel` Fetches the text from a label. The returned text is as it appears on screen. This does not include any embedded underlines indicating mnemonics or Pango markup. (See [method@Gtk.Label.get_label]) the text in the label widget. This is the internal string used by the label, and must not be modified. a `GtkLabel` Returns whether the label’s text is interpreted as Pango markup. See [method@Gtk.Label.set_use_markup]. %TRUE if the label’s text will be parsed for markup. a `GtkLabel` Returns whether an embedded underlines in the label indicate mnemonics. See [method@Gtk.Label.set_use_underline]. %TRUE whether an embedded underline in the label indicates the mnemonic accelerator keys. a `GtkLabel` Retrieves the desired width of @label, in characters. See [method@Gtk.Label.set_width_chars]. the width of the label in characters. a `GtkLabel` Returns whether lines in the label are automatically wrapped. See [method@Gtk.Label.set_wrap]. %TRUE if the lines of the label are automatically wrapped. a `GtkLabel` Returns line wrap mode used by the label. See [method@Gtk.Label.set_wrap_mode]. the line wrap mode a `GtkLabel` Gets the `xalign` of the label. See the [property@Gtk.Label:xalign] property. the xalign property a `GtkLabel` Gets the `yalign` of the label. See the [property@Gtk.Label:yalign] property. the yalign property a `GtkLabel` Selects a range of characters in the label, if the label is selectable. See [method@Gtk.Label.set_selectable]. If the label is not selectable, this function has no effect. If @start_offset or @end_offset are -1, then the end of the label will be substituted. a `GtkLabel` start offset (in characters not bytes) end offset (in characters not bytes) Apply attributes to the label text. The attributes set with this function will be applied and merged with any other attributes previously effected by way of the [property@Gtk.Label:use-underline] or [property@Gtk.Label:use-markup] properties. While it is not recommended to mix markup strings with manually set attributes, if you must; know that the attributes will be applied to the label after the markup string is parsed. a `GtkLabel` a [struct@Pango.AttrList] Sets the mode used to ellipsize the text. The text will be ellipsized if there is not enough space to render the entire string. a `GtkLabel` a `PangoEllipsizeMode` Sets a menu model to add when constructing the context menu for @label. a `GtkLabel` a `GMenuModel` Sets the alignment of the lines in the text of the label relative to each other. %GTK_JUSTIFY_LEFT is the default value when the widget is first created with [ctor@Gtk.Label.new]. If you instead want to set the alignment of the label as a whole, use [method@Gtk.Widget.set_halign] instead. [method@Gtk.Label.set_justify] has no effect on labels containing only a single line. a `GtkLabel` a `GtkJustification` Sets the text of the label. The label is interpreted as including embedded underlines and/or Pango markup depending on the values of the [property@Gtk.Label:use-underline] and [property@Gtk.Label:use-markup] properties. a `GtkLabel` the new text to set for the label Sets the number of lines to which an ellipsized, wrapping label should be limited. This has no effect if the label is not wrapping or ellipsized. Set this to -1 if you don’t want to limit the number of lines. a `GtkLabel` the desired number of lines, or -1 Sets the labels text and attributes from markup. The string must be marked up with Pango markup (see [func@Pango.parse_markup]). If the @str is external data, you may need to escape it with g_markup_escape_text() or g_markup_printf_escaped(): ```c GtkWidget *self = gtk_label_new (NULL); const char *str = "..."; const char *format = "<span style=\"italic\">\%s</span>"; char *markup; markup = g_markup_printf_escaped (format, str); gtk_label_set_markup (GTK_LABEL (self), markup); g_free (markup); ``` This function will set the [property@Gtk.Label:use-markup] property to %TRUE as a side effect. If you set the label contents using the [property@Gtk.Label:label] property you should also ensure that you set the [property@Gtk.Label:use-markup] property accordingly. See also: [method@Gtk.Label.set_text] a `GtkLabel` a markup string Sets the labels text, attributes and mnemonic from markup. Parses @str which is marked up with Pango markup (see [func@Pango.parse_markup]), setting the label’s text and attribute list based on the parse results. If characters in @str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. a `GtkLabel` a markup string Sets the desired maximum width in characters of @label to @n_chars. a `GtkLabel` the new desired maximum width, in characters. Associate the label with its mnemonic target. If the label has been set so that it has a mnemonic key (using i.e. [method@Gtk.Label.set_markup_with_mnemonic], [method@Gtk.Label.set_text_with_mnemonic], [ctor@Gtk.Label.new_with_mnemonic] or the [property@Gtk.Label:use_underline] property) the label can be associated with a widget that is the target of the mnemonic. When the label is inside a widget (like a [class@Gtk.Button] or a [class@Gtk.Notebook] tab) it is automatically associated with the correct widget, but sometimes (i.e. when the target is a [class@Gtk.Entry] next to the label) you need to set it explicitly using this function. The target widget will be accelerated by emitting the [signal@Gtk.Widget::mnemonic-activate] signal on it. The default handler for this signal will activate the widget if there are no mnemonic collisions and toggle focus between the colliding widgets otherwise. a `GtkLabel` the target `GtkWidget`, or %NULL to unset Select the line wrapping for the natural size request. This only affects the natural size requested, for the actual wrapping used, see the [property@Gtk.Label:wrap-mode] property. a `GtkLabel` the line wrapping mode Makes text in the label selectable. Selectable labels allow the user to select text from the label, for copy-and-paste. a `GtkLabel` %TRUE to allow selecting text in the label Sets whether the label is in single line mode. a `GtkLabel` %TRUE if the label should be in single line mode Sets the default tab stops for paragraphs in @self. a `GtkLabel` tabs as a `PangoTabArray` Sets the text within the `GtkLabel` widget. It overwrites any text that was there before. This function will clear any previously set mnemonic accelerators, and set the [property@Gtk.Label:use-underline] property to %FALSE as a side effect. This function will set the [property@Gtk.Label:use-markup] property to %FALSE as a side effect. See also: [method@Gtk.Label.set_markup] a `GtkLabel` The text you want to set Sets the label’s text from the string @str. If characters in @str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. The mnemonic key can be used to activate another widget, chosen automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. a `GtkLabel` a string Sets whether the text of the label contains markup. See [method@Gtk.Label.set_markup]. a `GtkLabel` %TRUE if the label’s text should be parsed for markup. Sets whether underlines in the text indicate mnemonics. a `GtkLabel` %TRUE if underlines in the text indicate mnemonics Sets the desired width in characters of @label to @n_chars. a `GtkLabel` the new desired width, in characters. Toggles line wrapping within the `GtkLabel` widget. %TRUE makes it break lines if text exceeds the widget’s size. %FALSE lets the text get cut off by the edge of the widget if it exceeds the widget size. Note that setting line wrapping to %TRUE does not make the label wrap at its parent container’s width, because GTK widgets conceptually can’t make their requisition depend on the parent container’s size. For a label that wraps at a specific position, set the label’s width using [method@Gtk.Widget.set_size_request]. a `GtkLabel` the setting Controls how line wrapping is done. This only affects the label if line wrapping is on. (See [method@Gtk.Label.set_wrap]) The default is %PANGO_WRAP_WORD which means wrap on word boundaries. For sizing behavior, also consider the [property@Gtk.Label:natural-wrap-mode] property. a `GtkLabel` the line wrapping mode Sets the `xalign` of the label. See the [property@Gtk.Label:xalign] property. a `GtkLabel` the new xalign value, between 0 and 1 Sets the `yalign` of the label. See the [property@Gtk.Label:yalign] property. a `GtkLabel` the new yalign value, between 0 and 1 A list of style attributes to apply to the text of the label. The preferred place to ellipsize the string, if the label does not have enough room to display the entire string. Note that setting this property to a value other than %PANGO_ELLIPSIZE_NONE has the side-effect that the label requests only enough space to display the ellipsis "...". In particular, this means that ellipsizing labels do not work well in notebook tabs, unless the [property@Gtk.NotebookPage:tab-expand] child property is set to %TRUE. Other ways to set a label's width are [method@Gtk.Widget.set_size_request] and [method@Gtk.Label.set_width_chars]. A menu model whose contents will be appended to the context menu. The alignment of the lines in the text of the label, relative to each other. This does *not* affect the alignment of the label within its allocation. See [property@Gtk.Label:xalign] for that. The contents of the label. If the string contains Pango markup (see [func@Pango.parse_markup]), you will have to set the [property@Gtk.Label:use-markup] property to %TRUE in order for the label to display the markup attributes. See also [method@Gtk.Label.set_markup] for a convenience function that sets both this property and the [property@Gtk.Label:use-markup] property at the same time. If the string contains underlines acting as mnemonics, you will have to set the [property@Gtk.Label:use-underline] property to %TRUE in order for the label to display them. The number of lines to which an ellipsized, wrapping label should be limited. This property has no effect if the label is not wrapping or ellipsized. Set this property to -1 if you don't want to limit the number of lines. The desired maximum width of the label, in characters. If this property is set to -1, the width will be calculated automatically. See the section on [text layout](class.Label.html#text-layout) for details of how [property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] determine the width of ellipsized and wrapped labels. The mnemonic accelerator key for the label. The widget to be activated when the labels mnemonic key is pressed. Select the line wrapping for the natural size request. This only affects the natural size requested. For the actual wrapping used, see the [property@Gtk.Label:wrap-mode] property. The default is %GTK_NATURAL_WRAP_INHERIT, which inherits the behavior of the [property@Gtk.Label:wrap-mode] property. Whether the label text can be selected with the mouse. Whether the label is in single line mode. In single line mode, the height of the label does not depend on the actual text, it is always set to ascent + descent of the font. This can be an advantage in situations where resizing the label because of text changes would be distracting, e.g. in a statusbar. Custom tabs for this label. %TRUE if the text of the label includes Pango markup. See [func@Pango.parse_markup]. %TRUE if the text of the label indicates a mnemonic with an _ before the mnemonic character. The desired width of the label, in characters. If this property is set to -1, the width will be calculated automatically. See the section on [text layout](class.Label.html#text-layout) for details of how [property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] determine the width of ellipsized and wrapped labels. %TRUE if the label text will wrap if it gets too wide. Controls how the line wrapping is done. This only affects the formatting if line wrapping is on (see the [property@Gtk.Label:wrap] property). The default is %PANGO_WRAP_WORD, which means wrap on word boundaries. For sizing behavior, also consider the [property@Gtk.Label:natural-wrap-mode] property. The horizontal alignment of the label text inside its size allocation. Compare this to [property@Gtk.Widget:halign], which determines how the labels size allocation is positioned in the space available for the label. The vertical alignment of the label text inside its size allocation. Compare this to [property@Gtk.Widget:valign], which determines how the labels size allocation is positioned in the space available for the label. Gets emitted when the user activates a link in the label. The ::activate-current-link is a [keybinding signal](class.SignalAction.html). Applications may also emit the signal with g_signal_emit_by_name() if they need to control activation of URIs programmatically. The default bindings for this signal are all forms of the <kbd>Enter</kbd> key. Gets emitted to activate a URI. Applications may connect to it to override the default behaviour, which is to call [method@Gtk.FileLauncher.launch]. %TRUE if the link has been activated the URI that is activated Gets emitted to copy the selection to the clipboard. The ::copy-clipboard signal is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Ctrl</kbd>+<kbd>c</kbd>. Gets emitted when the user initiates a cursor movement. The ::move-cursor signal is a [keybinding signal](class.SignalAction.html). If the cursor is not visible in @entry, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the <kbd>Shift</kbd> modifier extends the selection, the variant without the <kbd>Shift</kbd> modifier does not. There are too many key combinations to list them all here. - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move by individual characters/lines - <kbd>Ctrl</kbd>+<kbd>←</kbd>, etc. move by words/paragraphs - <kbd>Home</kbd> and <kbd>End</kbd> move to the ends of the buffer the granularity of the move, as a `GtkMovementStep` the number of @step units to move %TRUE if the move should extend the selection `GtkLayoutChild` is the base class for objects that are meant to hold layout properties. If a `GtkLayoutManager` has per-child properties, like their packing type, or the horizontal and vertical span, or the icon name, then the layout manager should use a `GtkLayoutChild` implementation to store those properties. A `GtkLayoutChild` instance is only ever valid while a widget is part of a layout. Retrieves the `GtkWidget` associated to the given @layout_child. a `GtkWidget` a `GtkLayoutChild` Retrieves the `GtkLayoutManager` instance that created the given @layout_child. a `GtkLayoutManager` a `GtkLayoutChild` The widget that is associated to the `GtkLayoutChild` instance. The layout manager that created the `GtkLayoutChild` instance. Layout managers are delegate classes that handle the preferred size and the allocation of a widget. You typically subclass `GtkLayoutManager` if you want to implement a layout policy for the children of a widget, or if you want to determine the size of a widget depending on its contents. Each `GtkWidget` can only have a `GtkLayoutManager` instance associated to it at any given time; it is possible, though, to replace the layout manager instance using [method@Gtk.Widget.set_layout_manager]. ## Layout properties A layout manager can expose properties for controlling the layout of each child, by creating an object type derived from [class@Gtk.LayoutChild] and installing the properties on it as normal `GObject` properties. Each `GtkLayoutChild` instance storing the layout properties for a specific child is created through the [method@Gtk.LayoutManager.get_layout_child] method; a `GtkLayoutManager` controls the creation of its `GtkLayoutChild` instances by overriding the GtkLayoutManagerClass.create_layout_child() virtual function. The typical implementation should look like: ```c static GtkLayoutChild * create_layout_child (GtkLayoutManager *manager, GtkWidget *container, GtkWidget *child) { return g_object_new (your_layout_child_get_type (), "layout-manager", manager, "child-widget", child, NULL); } ``` The [property@Gtk.LayoutChild:layout-manager] and [property@Gtk.LayoutChild:child-widget] properties on the newly created `GtkLayoutChild` instance are mandatory. The `GtkLayoutManager` will cache the newly created `GtkLayoutChild` instance until the widget is removed from its parent, or the parent removes the layout manager. Each `GtkLayoutManager` instance creating a `GtkLayoutChild` should use [method@Gtk.LayoutManager.get_layout_child] every time it needs to query the layout properties; each `GtkLayoutChild` instance should call [method@Gtk.LayoutManager.layout_changed] every time a property is updated, in order to queue a new size measuring and allocation. Assigns the given @width, @height, and @baseline to a @widget, and computes the position and sizes of the children of the @widget using the layout management policy of @manager. a `GtkLayoutManager` the `GtkWidget` using @manager the new width of the @widget the new height of the @widget the baseline position of the @widget, or -1 Create a `GtkLayoutChild` instance for the given @for_child widget. a `GtkLayoutChild` the `GtkLayoutManager` the widget using the @manager the child of @widget a virtual function, used to return the preferred request mode for the layout manager; for instance, "width for height" or "height for width"; see `GtkSizeRequestMode` Measures the size of the @widget using @manager, for the given @orientation and size. See the [class@Gtk.Widget] documentation on layout management for more details. a `GtkLayoutManager` the `GtkWidget` using @manager the orientation to measure Size for the opposite of @orientation; for instance, if the @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height of the widget; if the @orientation is %GTK_ORIENTATION_VERTICAL, this is the width of the widget. This allows to measure the height for the given width, and the width for the given height. Use -1 if the size is not known the minimum size for the given size and orientation the natural, or preferred size for the given size and orientation the baseline position for the minimum size the baseline position for the natural size a virtual function, called when the widget using the layout manager is attached to a `GtkRoot` a virtual function, called when the widget using the layout manager is detached from a `GtkRoot` Assigns the given @width, @height, and @baseline to a @widget, and computes the position and sizes of the children of the @widget using the layout management policy of @manager. a `GtkLayoutManager` the `GtkWidget` using @manager the new width of the @widget the new height of the @widget the baseline position of the @widget, or -1 Retrieves a `GtkLayoutChild` instance for the `GtkLayoutManager`, creating one if necessary. The @child widget must be a child of the widget using @manager. The `GtkLayoutChild` instance is owned by the `GtkLayoutManager`, and is guaranteed to exist as long as @child is a child of the `GtkWidget` using the given `GtkLayoutManager`. a `GtkLayoutChild` a `GtkLayoutManager` a `GtkWidget` Retrieves the request mode of @manager. a `GtkSizeRequestMode` a `GtkLayoutManager` Retrieves the `GtkWidget` using the given `GtkLayoutManager`. a `GtkWidget` a `GtkLayoutManager` Queues a resize on the `GtkWidget` using @manager, if any. This function should be called by subclasses of `GtkLayoutManager` in response to changes to their layout management policies. a `GtkLayoutManager` Measures the size of the @widget using @manager, for the given @orientation and size. See the [class@Gtk.Widget] documentation on layout management for more details. a `GtkLayoutManager` the `GtkWidget` using @manager the orientation to measure Size for the opposite of @orientation; for instance, if the @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height of the widget; if the @orientation is %GTK_ORIENTATION_VERTICAL, this is the width of the widget. This allows to measure the height for the given width, and the width for the given height. Use -1 if the size is not known the minimum size for the given size and orientation the natural, or preferred size for the given size and orientation the baseline position for the minimum size the baseline position for the natural size The `GtkLayoutManagerClass` structure contains only private data, and should only be accessed through the provided API, or when subclassing `GtkLayoutManager`. a virtual function, used to return the preferred request mode for the layout manager; for instance, "width for height" or "height for width"; see `GtkSizeRequestMode` a virtual function, used to measure the minimum and preferred sizes of the widget using the layout manager for a given orientation a `GtkLayoutManager` the `GtkWidget` using @manager the orientation to measure Size for the opposite of @orientation; for instance, if the @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height of the widget; if the @orientation is %GTK_ORIENTATION_VERTICAL, this is the width of the widget. This allows to measure the height for the given width, and the width for the given height. Use -1 if the size is not known the minimum size for the given size and orientation the natural, or preferred size for the given size and orientation the baseline position for the minimum size the baseline position for the natural size a virtual function, used to allocate the size of the widget using the layout manager a `GtkLayoutManager` the `GtkWidget` using @manager the new width of the @widget the new height of the @widget the baseline position of the @widget, or -1 the type of `GtkLayoutChild` used by this layout manager a virtual function, used to create a `GtkLayoutChild` meta object for the layout properties a `GtkLayoutChild` the `GtkLayoutManager` the widget using the @manager the child of @widget a virtual function, called when the widget using the layout manager is attached to a `GtkRoot` a virtual function, called when the widget using the layout manager is detached from a `GtkRoot` `GtkLevelBar` is a widget that can be used as a level indicator. Typical use cases are displaying the strength of a password, or showing the charge level of a battery.  Use [method@Gtk.LevelBar.set_value] to set the current value, and [method@Gtk.LevelBar.add_offset_value] to set the value offsets at which the bar will be considered in a different state. GTK will add a few offsets by default on the level bar: %GTK_LEVEL_BAR_OFFSET_LOW, %GTK_LEVEL_BAR_OFFSET_HIGH and %GTK_LEVEL_BAR_OFFSET_FULL, with values 0.25, 0.75 and 1.0 respectively. Note that it is your responsibility to update preexisting offsets when changing the minimum or maximum value. GTK will simply clamp them to the new range. ## Adding a custom offset on the bar ```c static GtkWidget * create_level_bar (void) { GtkWidget *widget; GtkLevelBar *bar; widget = gtk_level_bar_new (); bar = GTK_LEVEL_BAR (widget); // This changes the value of the default low offset gtk_level_bar_add_offset_value (bar, GTK_LEVEL_BAR_OFFSET_LOW, 0.10); // This adds a new offset to the bar; the application will // be able to change its color CSS like this: // // levelbar block.my-offset { // background-color: magenta; // border-style: solid; // border-color: black; // border-width: 1px; // } gtk_level_bar_add_offset_value (bar, "my-offset", 0.60); return widget; } ``` The default interval of values is between zero and one, but it’s possible to modify the interval using [method@Gtk.LevelBar.set_min_value] and [method@Gtk.LevelBar.set_max_value]. The value will be always drawn in proportion to the admissible interval, i.e. a value of 15 with a specified interval between 10 and 20 is equivalent to a value of 0.5 with an interval between 0 and 1. When %GTK_LEVEL_BAR_MODE_DISCRETE is used, the bar level is rendered as a finite number of separated blocks instead of a single one. The number of blocks that will be rendered is equal to the number of units specified by the admissible interval. For instance, to build a bar rendered with five blocks, it’s sufficient to set the minimum value to 0 and the maximum value to 5 after changing the indicator mode to discrete. # GtkLevelBar as GtkBuildable The `GtkLevelBar` implementation of the `GtkBuildable` interface supports a custom `<offsets>` element, which can contain any number of `<offset>` elements, each of which must have "name" and "value" attributes. # CSS nodes ``` levelbar[.discrete] ╰── trough ├── block.filled.level-name ┊ ├── block.empty ┊ ``` `GtkLevelBar` has a main CSS node with name levelbar and one of the style classes .discrete or .continuous and a subnode with name trough. Below the trough node are a number of nodes with name block and style class .filled or .empty. In continuous mode, there is exactly one node of each, in discrete mode, the number of filled and unfilled nodes corresponds to blocks that are drawn. The block.filled nodes also get a style class .level-name corresponding to the level for the current value. In horizontal orientation, the nodes are always arranged from left to right, regardless of text direction. # Accessibility `GtkLevelBar` uses the %GTK_ACCESSIBLE_ROLE_METER role. Creates a new `GtkLevelBar`. a `GtkLevelBar`. Creates a new `GtkLevelBar` for the specified interval. a `GtkLevelBar` a positive value a positive value Adds a new offset marker on @self at the position specified by @value. When the bar value is in the interval topped by @value (or between @value and [property@Gtk.LevelBar:max-value] in case the offset is the last one on the bar) a style class named `level-`@name will be applied when rendering the level bar fill. If another offset marker named @name exists, its value will be replaced by @value. a `GtkLevelBar` the name of the new offset the value for the new offset Returns whether the levelbar is inverted. %TRUE if the level bar is inverted a `GtkLevelBar` Returns the `max-value` of the `GtkLevelBar`. a positive value a `GtkLevelBar` Returns the `min-value` of the `GtkLevelBar`. a positive value a `GtkLevelBar` Returns the `mode` of the `GtkLevelBar`. a `GtkLevelBarMode` a `GtkLevelBar` Fetches the value specified for the offset marker @name in @self. %TRUE if the specified offset is found a `GtkLevelBar` the name of an offset in the bar location where to store the value Returns the `value` of the `GtkLevelBar`. a value in the interval between [property@Gtk.LevelBar:min-value] and [property@Gtk.LevelBar:max-value] a `GtkLevelBar` Removes an offset marker from a `GtkLevelBar`. The marker must have been previously added with [method@Gtk.LevelBar.add_offset_value]. a `GtkLevelBar` the name of an offset in the bar Sets whether the `GtkLevelBar` is inverted. a `GtkLevelBar` %TRUE to invert the level bar Sets the `max-value` of the `GtkLevelBar`. You probably want to update preexisting level offsets after calling this function. a `GtkLevelBar` a positive value Sets the `min-value` of the `GtkLevelBar`. You probably want to update preexisting level offsets after calling this function. a `GtkLevelBar` a positive value Sets the `mode` of the `GtkLevelBar`. a `GtkLevelBar` a `GtkLevelBarMode` Sets the value of the `GtkLevelBar`. a `GtkLevelBar` a value in the interval between [property@Gtk.LevelBar:min-value] and [property@Gtk.LevelBar:max-value] Whether the `GtkLeveBar` is inverted. Level bars normally grow from top to bottom or left to right. Inverted level bars grow in the opposite direction. Determines the maximum value of the interval that can be displayed by the bar. Determines the minimum value of the interval that can be displayed by the bar. Determines the way `GtkLevelBar` interprets the value properties to draw the level fill area. Specifically, when the value is %GTK_LEVEL_BAR_MODE_CONTINUOUS, `GtkLevelBar` will draw a single block representing the current value in that area; when the value is %GTK_LEVEL_BAR_MODE_DISCRETE, the widget will draw a succession of separate blocks filling the draw area, with the number of blocks being equal to the units separating the integral roundings of [property@Gtk.LevelBar:min-value] and [property@Gtk.LevelBar:max-value]. Determines the currently filled value of the level bar. Emitted when an offset specified on the bar changes value. This typically is the result of a [method@Gtk.LevelBar.add_offset_value] call. The signal supports detailed connections; you can connect to the detailed signal "changed::x" in order to only receive callbacks when the value of offset "x" changes. the name of the offset that changed value Describes how [class@LevelBar] contents should be rendered. Note that this enumeration could be extended with additional modes in the future. the bar has a continuous mode the bar has a discrete mode The type of license for an application. This enumeration can be expanded at later date. No license specified A license text is going to be specified by the developer The GNU General Public License, version 2.0 or later The GNU General Public License, version 3.0 or later The GNU Lesser General Public License, version 2.1 or later The GNU Lesser General Public License, version 3.0 or later The BSD standard license The MIT/X11 standard license The Artistic License, version 2.0 The GNU General Public License, version 2.0 only The GNU General Public License, version 3.0 only The GNU Lesser General Public License, version 2.1 only The GNU Lesser General Public License, version 3.0 only The GNU Affero General Public License, version 3.0 or later The GNU Affero General Public License, version 3.0 only The 3-clause BSD licence The Apache License, version 2.0 The Mozilla Public License, version 2.0 Zero-Clause BSD license A `GtkLinkButton` is a button with a hyperlink.  It is useful to show quick links to resources. A link button is created by calling either [ctor@Gtk.LinkButton.new] or [ctor@Gtk.LinkButton.new_with_label]. If using the former, the URI you pass to the constructor is used as a label for the widget. The URI bound to a `GtkLinkButton` can be set specifically using [method@Gtk.LinkButton.set_uri]. By default, `GtkLinkButton` calls [method@Gtk.FileLauncher.launch] when the button is clicked. This behaviour can be overridden by connecting to the [signal@Gtk.LinkButton::activate-link] signal and returning %TRUE from the signal handler. # Shortcuts and Gestures `GtkLinkButton` supports the following keyboard shortcuts: - <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. # Actions `GtkLinkButton` defines a set of built-in actions: - `clipboard.copy` copies the url to the clipboard. - `menu.popup` opens the context menu. # CSS nodes `GtkLinkButton` has a single CSS node with name button. To differentiate it from a plain `GtkButton`, it gets the .link style class. # Accessibility `GtkLinkButton` uses the %GTK_ACCESSIBLE_ROLE_LINK role. Creates a new `GtkLinkButton` with the URI as its text. a new link button widget. a valid URI Creates a new `GtkLinkButton` containing a label. a new link button widget. a valid URI the text of the button Retrieves the URI of the `GtkLinkButton`. a valid URI. The returned string is owned by the link button and should not be modified or freed. a `GtkLinkButton` Retrieves the “visited” state of the `GtkLinkButton`. The button becomes visited when it is clicked. If the URI is changed on the button, the “visited” state is unset again. The state may also be changed using [method@Gtk.LinkButton.set_visited]. %TRUE if the link has been visited, %FALSE otherwise a `GtkLinkButton` Sets @uri as the URI where the `GtkLinkButton` points. As a side-effect this unsets the “visited” state of the button. a `GtkLinkButton` a valid URI Sets the “visited” state of the `GtkLinkButton`. See [method@Gtk.LinkButton.get_visited] for more details. a `GtkLinkButton` the new “visited” state The URI bound to this button. The 'visited' state of this button. A visited link is drawn in a different color. Emitted each time the `GtkLinkButton` is clicked. The default handler will call [method@Gtk.FileLauncher.launch] with the URI stored inside the [property@Gtk.LinkButton:uri] property. To override the default behavior, you can connect to the ::activate-link signal and stop the propagation of the signal by returning %TRUE from your handler. %TRUE if the signal has been handled `GtkListBase` is the abstract base class for GTK's list widgets. # Shortcuts and Gestures `GtkListBase` supports the following keyboard shortcuts: - <kbd>Ctrl</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&sol;</kbd> selects all items. - <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&bsol;</kbd> unselects all items. The focused item is controlled by the navigation keys below, combined with the <kbd>Ctrl</kbd> modifier to prevent moving the selection, and the <kbd>Shift</kbd> modifier to extend the current selection. - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move the focus on the next item in the designed direction. - <kbd>Home</kbd> and <kbd>End</kbd> focus the first or last item. - <kbd>PgUp</kbd> and <kbd>PgDn</kbd> move the focus one page up or down. List item widgets support the following keyboard shortcuts: - <kbd>Enter</kbd> activates the item. - <kbd>␣</kbd> selects the item, with the same <kbd>Ctrl</kbd> and <kbd>Shift</kbd> modifiers combinations as the navigation keys. # Actions `GtkListBase` defines a set of built-in actions: - `list.scroll-to-item` moves the visible area to the item at given position with the minimum amount of scrolling required. If the item is already visible, nothing happens. - `list.select-item` changes the selection. - `list.select-all` selects all items in the model, if the selection model supports it. - `list.unselect-all` unselects all items in the model, if the selection model supports it. List item widgets install the following actions: - `listitem.select` changes selection if the item is selectable. - `listitem.scroll-to` moves the visible area of the list to this item with the minimum amount of scrolling required. The orientation of the list. See GtkOrientable:orientation for details. `GtkListBox` is a vertical list. A `GtkListBox` only contains `GtkListBoxRow` children. These rows can by dynamically sorted and filtered, and headers can be added dynamically depending on the row content. It also allows keyboard and mouse navigation and selection like a typical list. Using `GtkListBox` is often an alternative to `GtkTreeView`, especially when the list contents has a more complicated layout than what is allowed by a `GtkCellRenderer`, or when the contents is interactive (i.e. has a button in it). Although a `GtkListBox` must have only `GtkListBoxRow` children, you can add any kind of widget to it via [method@Gtk.ListBox.prepend], [method@Gtk.ListBox.append] and [method@Gtk.ListBox.insert] and a `GtkListBoxRow` widget will automatically be inserted between the list and the widget. `GtkListBoxRows` can be marked as activatable or selectable. If a row is activatable, [signal@Gtk.ListBox::row-activated] will be emitted for it when the user tries to activate it. If it is selectable, the row will be marked as selected when the user tries to select it. # GtkListBox as GtkBuildable The `GtkListBox` implementation of the `GtkBuildable` interface supports setting a child as the placeholder by specifying “placeholder” as the “type” attribute of a `<child>` element. See [method@Gtk.ListBox.set_placeholder] for info. # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.ListBox::move-cursor] - [signal@Gtk.ListBox::select-all] - [signal@Gtk.ListBox::toggle-cursor-row] - [signal@Gtk.ListBox::unselect-all] # CSS nodes |[<!-- language="plain" --> list[.separators][.rich-list][.navigation-sidebar][.boxed-list] ╰── row[.activatable] ]| `GtkListBox` uses a single CSS node named list. It may carry the .separators style class, when the [property@Gtk.ListBox:show-separators] property is set. Each `GtkListBoxRow` uses a single CSS node named row. The row nodes get the .activatable style class added when appropriate. It may also carry the .boxed-list style class. In this case, the list will be automatically surrounded by a frame and have separators. The main list node may also carry style classes to select the style of [list presentation](section-list-widget.html#list-styles): .rich-list, .navigation-sidebar or .data-table. # Accessibility `GtkListBox` uses the %GTK_ACCESSIBLE_ROLE_LIST role and `GtkListBoxRow` uses the %GTK_ACCESSIBLE_ROLE_LIST_ITEM role. Creates a new `GtkListBox` container. a new `GtkListBox` Append a widget to the list. If a sort function is set, the widget will actually be inserted at the calculated position. a `GtkListBox` the `GtkWidget` to add Binds @model to @box. If @box was already bound to a model, that previous binding is destroyed. The contents of @box are cleared and then filled with widgets that represent items from @model. @box is updated whenever @model changes. If @model is %NULL, @box is left empty. It is undefined to add or remove widgets directly (for example, with [method@Gtk.ListBox.insert]) while @box is bound to a model. Note that using a model is incompatible with the filtering and sorting functionality in `GtkListBox`. When using a model, filtering and sorting should be implemented by the model. a `GtkListBox` the `GListModel` to be bound to @box a function that creates widgets for items or %NULL in case you also passed %NULL as @model user data passed to @create_widget_func function for freeing @user_data Add a drag highlight to a row. This is a helper function for implementing DnD onto a `GtkListBox`. The passed in @row will be highlighted by setting the %GTK_STATE_FLAG_DROP_ACTIVE state and any previously highlighted row will be unhighlighted. The row will also be unhighlighted when the widget gets a drag leave event. a `GtkListBox` a `GtkListBoxRow` If a row has previously been highlighted via gtk_list_box_drag_highlight_row(), it will have the highlight removed. a `GtkListBox` Returns whether rows activate on single clicks. %TRUE if rows are activated on single click, %FALSE otherwise a `GtkListBox` Gets the adjustment (if any) that the widget uses to for vertical scrolling. the adjustment a `GtkListBox` Gets the n-th child in the list (not counting headers). If @index_ is negative or larger than the number of items in the list, %NULL is returned. the child `GtkWidget` a `GtkListBox` the index of the row Gets the row at the @y position. the row a `GtkListBox` position Gets the selected row, or %NULL if no rows are selected. Note that the box may allow multiple selection, in which case you should use [method@Gtk.ListBox.selected_foreach] to find all selected rows. the selected row a `GtkListBox` Creates a list of all selected children. A `GList` containing the `GtkWidget` for each selected child. Free with g_list_free() when done. a `GtkListBox` Gets the selection mode of the listbox. a `GtkSelectionMode` a `GtkListBox` Returns whether the list box should show separators between rows. %TRUE if the list box shows separators a `GtkListBox` Insert the @child into the @box at @position. If a sort function is set, the widget will actually be inserted at the calculated position. If @position is -1, or larger than the total number of items in the @box, then the @child will be appended to the end. a `GtkListBox` the `GtkWidget` to add the position to insert @child in Update the filtering for all rows. Call this when result of the filter function on the @box is changed due to an external factor. For instance, this would be used if the filter function just looked for a specific search string and the entry with the search string has changed. a `GtkListBox` Update the separators for all rows. Call this when result of the header function on the @box is changed due to an external factor. a `GtkListBox` Update the sorting for all rows. Call this when result of the sort function on the @box is changed due to an external factor. a `GtkListBox` Prepend a widget to the list. If a sort function is set, the widget will actually be inserted at the calculated position. a `GtkListBox` the `GtkWidget` to add Removes a child from @box. a `GtkListBox` the child to remove Removes all rows from @box. This function does nothing if @box is backed by a model. a `GtkListBox` Select all children of @box, if the selection mode allows it. a `GtkListBox` Make @row the currently selected row. a `GtkListBox` The row to select Calls a function for each selected child. Note that the selection cannot be modified from within this function. a `GtkListBox` the function to call for each selected child user data to pass to the function If @single is %TRUE, rows will be activated when you click on them, otherwise you need to double-click. a `GtkListBox` a boolean Sets the adjustment (if any) that the widget uses to for vertical scrolling. For instance, this is used to get the page size for PageUp/Down key handling. In the normal case when the @box is packed inside a `GtkScrolledWindow` the adjustment from that will be picked up automatically, so there is no need to manually do that. a `GtkListBox` the adjustment By setting a filter function on the @box one can decide dynamically which of the rows to show. For instance, to implement a search function on a list that filters the original list to only show the matching rows. The @filter_func will be called for each row after the call, and it will continue to be called each time a row changes (via [method@Gtk.ListBoxRow.changed]) or when [method@Gtk.ListBox.invalidate_filter] is called. Note that using a filter function is incompatible with using a model (see [method@Gtk.ListBox.bind_model]). a `GtkListBox` callback that lets you filter which rows to show user data passed to @filter_func destroy notifier for @user_data Sets a header function. By setting a header function on the @box one can dynamically add headers in front of rows, depending on the contents of the row and its position in the list. For instance, one could use it to add headers in front of the first item of a new kind, in a list sorted by the kind. The @update_header can look at the current header widget using [method@Gtk.ListBoxRow.get_header] and either update the state of the widget as needed, or set a new one using [method@Gtk.ListBoxRow.set_header]. If no header is needed, set the header to %NULL. Note that you may get many calls @update_header to this for a particular row when e.g. changing things that don’t affect the header. In this case it is important for performance to not blindly replace an existing header with an identical one. The @update_header function will be called for each row after the call, and it will continue to be called each time a row changes (via [method@Gtk.ListBoxRow.changed]) and when the row before changes (either by [method@Gtk.ListBoxRow.changed] on the previous row, or when the previous row becomes a different row). It is also called for all rows when [method@Gtk.ListBox.invalidate_headers] is called. a `GtkListBox` callback that lets you add row headers user data passed to @update_header destroy notifier for @user_data Sets the placeholder widget that is shown in the list when it doesn't display any visible children. a `GtkListBox` a `GtkWidget` Sets how selection works in the listbox. a `GtkListBox` The `GtkSelectionMode` Sets whether the list box should show separators between rows. a `GtkListBox` %TRUE to show separators Sets a sort function. By setting a sort function on the @box one can dynamically reorder the rows of the list, based on the contents of the rows. The @sort_func will be called for each row after the call, and will continue to be called each time a row changes (via [method@Gtk.ListBoxRow.changed]) and when [method@Gtk.ListBox.invalidate_sort] is called. Note that using a sort function is incompatible with using a model (see [method@Gtk.ListBox.bind_model]). a `GtkListBox` the sort function user data passed to @sort_func destroy notifier for @user_data Unselect all children of @box, if the selection mode allows it. a `GtkListBox` Unselects a single row of @box, if the selection mode allows it. a `GtkListBox` the row to unselect Whether to accept unpaired release events. Determines whether children can be activated with a single click, or require a double-click. The selection mode used by the list box. Whether to show separators between rows. Emitted when the cursor row is activated. Emitted when the user initiates a cursor movement. The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifier does not. There are too many key combinations to list them all here. - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move by individual children - <kbd>Home</kbd>, <kbd>End</kbd> move to the ends of the box - <kbd>PgUp</kbd>, <kbd>PgDn</kbd> move vertically by pages the granularity of the move, as a `GtkMovementStep` the number of @step units to move whether to extend the selection whether to modify the selection Emitted when a row has been activated by the user. the activated row Emitted when a new row is selected, or (with a %NULL @row) when the selection is cleared. When the @box is using %GTK_SELECTION_MULTIPLE, this signal will not give you the full picture of selection changes, and you should use the [signal@Gtk.ListBox::selected-rows-changed] signal instead. the selected row Emitted to select all children of the box, if the selection mode permits it. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Ctrl</kbd>-<kbd>a</kbd>. Emitted when the set of selected rows changes. Emitted when the cursor row is toggled. The default bindings for this signal is <kbd>Ctrl</kbd>+<kbd>␣</kbd>. Emitted to unselect all children of the box, if the selection mode permits it. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Ctrl</kbd>-<kbd>Shift</kbd>-<kbd>a</kbd>. Called for list boxes that are bound to a `GListModel` with gtk_list_box_bind_model() for each item that gets added to the model. If the widget returned is not a #GtkListBoxRow widget, then the widget will be inserted as the child of an intermediate #GtkListBoxRow. a `GtkWidget` that represents @item the item from the model for which to create a widget for user data Will be called whenever the row changes or is added and lets you control if the row should be visible or not. %TRUE if the row should be visible, %FALSE otherwise the row that may be filtered user data A function used by gtk_list_box_selected_foreach(). It will be called on every selected child of the @box. a `GtkListBox` a `GtkListBoxRow` user data `GtkListBoxRow` is the kind of widget that can be added to a `GtkListBox`. Creates a new `GtkListBoxRow`. a new `GtkListBoxRow` Marks @row as changed, causing any state that depends on this to be updated. This affects sorting, filtering and headers. Note that calls to this method must be in sync with the data used for the row functions. For instance, if the list is mirroring some external data set, and *two* rows changed in the external data set then when you call gtk_list_box_row_changed() on the first row the sort function must only read the new data for the first of the two changed rows, otherwise the resorting of the rows will be wrong. This generally means that if you don’t fully control the data model you have to duplicate the data that affects the listbox row functions into the row widgets themselves. Another alternative is to call [method@Gtk.ListBox.invalidate_sort] on any model change, but that is more expensive. a `GtkListBoxRow` Gets whether the row is activatable. %TRUE if the row is activatable a `GtkListBoxRow` Gets the child widget of @row. the child widget of @row a `GtkListBoxRow` Returns the current header of the @row. This can be used in a [callback@Gtk.ListBoxUpdateHeaderFunc] to see if there is a header set already, and if so to update the state of it. the current header a `GtkListBoxRow` Gets the current index of the @row in its `GtkListBox` container. the index of the @row, or -1 if the @row is not in a listbox a `GtkListBoxRow` Gets whether the row can be selected. %TRUE if the row is selectable a `GtkListBoxRow` Returns whether the child is currently selected in its `GtkListBox` container. %TRUE if @row is selected a `GtkListBoxRow` Set whether the row is activatable. a `GtkListBoxRow` %TRUE to mark the row as activatable Sets the child widget of @self. a `GtkListBoxRow` the child widget Sets the current header of the @row. This is only allowed to be called from a [callback@Gtk.ListBoxUpdateHeaderFunc]. It will replace any existing header in the row, and be shown in front of the row in the listbox. a `GtkListBoxRow` the header Set whether the row can be selected. a `GtkListBoxRow` %TRUE to mark the row as selectable Determines whether the ::row-activated signal will be emitted for this row. The child widget. Determines whether this row can be selected. This is a keybinding signal, which will cause this row to be activated. If you want to be notified when the user activates a row (by key or not), use the [signal@Gtk.ListBox::row-activated] signal on the row’s parent `GtkListBox`. The parent class. Compare two rows to determine which should be first. < 0 if @row1 should be before @row2, 0 if they are equal and > 0 otherwise the first row the second row user data Whenever @row changes or which row is before @row changes this is called, which lets you update the header on @row. You may remove or set a new one via [method@Gtk.ListBoxRow.set_header] or just change the state of the current header widget. the row to update the row before @row, or %NULL if it is first user data `GtkListHeader` is used by list widgets to represent the headers they display. `GtkListHeader` objects are managed just like [class@Gtk.ListItem] objects via their factory, but provide a different set of properties suitable for managing the header instead of individual items. Gets the child previously set via gtk_list_header_set_child() or %NULL if none was set. The child a `GtkListHeader` Gets the end position in the model of the section that @self is currently the header for. If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. The end position of the section a `GtkListHeader` Gets the model item at the start of the section. This is the item that occupies the list model at position [property@Gtk.ListHeader:start]. If @self is unbound, this function returns %NULL. The item displayed a `GtkListHeader` Gets the the number of items in the section. If @self is unbound, 0 is returned. The number of items in the section a `GtkListHeader` Gets the start position in the model of the section that @self is currently the header for. If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. The start position of the section a `GtkListHeader` Sets the child to be used for this listitem. This function is typically called by applications when setting up a header so that the widget can be reused when binding it multiple times. a `GtkListHeader` The list item's child or %NULL to unset Widget used for display. The first position no longer part of this section. The item at the start of the section. Number of items in this section. First position of items in this section. `GtkListItem` is used by list widgets to represent items in a [iface@Gio.ListModel]. `GtkListItem` objects are managed by the list widget (with its factory) and cannot be created by applications, but they need to be populated by application code. This is done by calling [method@Gtk.ListItem.set_child]. `GtkListItem` objects exist in 2 stages: 1. The unbound stage where the listitem is not currently connected to an item in the list. In that case, the [property@Gtk.ListItem:item] property is set to %NULL. 2. The bound stage where the listitem references an item from the list. The [property@Gtk.ListItem:item] property is not %NULL. Gets the accessible description of @self. the accessible description a `GtkListItem` Gets the accessible label of @self. the accessible label a `GtkListItem` Checks if a list item has been set to be activatable via gtk_list_item_set_activatable(). %TRUE if the item is activatable a `GtkListItem` Gets the child previously set via gtk_list_item_set_child() or %NULL if none was set. The child a `GtkListItem` Checks if a list item has been set to be focusable via gtk_list_item_set_focusable(). %TRUE if the item is focusable a `GtkListItem` Gets the model item that associated with @self. If @self is unbound, this function returns %NULL. The item displayed a `GtkListItem` Gets the position in the model that @self currently displays. If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. The position of this item a `GtkListItem` Checks if a list item has been set to be selectable via gtk_list_item_set_selectable(). Do not confuse this function with [method@Gtk.ListItem.get_selected]. %TRUE if the item is selectable a `GtkListItem` Checks if the item is displayed as selected. The selected state is maintained by the liste widget and its model and cannot be set otherwise. %TRUE if the item is selected. a `GtkListItem` Sets the accessible description for the list item, which may be used by e.g. screen readers. a `GtkListItem` the description Sets the accessible label for the list item, which may be used by e.g. screen readers. a `GtkListItem` the label Sets @self to be activatable. If an item is activatable, double-clicking on the item, using the Return key or calling gtk_widget_activate() will activate the item. Activating instructs the containing view to handle activation. `GtkListView` for example will be emitting the [signal@Gtk.ListView::activate] signal. By default, list items are activatable. a `GtkListItem` if the item should be activatable Sets the child to be used for this listitem. This function is typically called by applications when setting up a listitem so that the widget can be reused when binding it multiple times. a `GtkListItem` The list item's child or %NULL to unset Sets @self to be focusable. If an item is focusable, it can be focused using the keyboard. This works similar to [method@Gtk.Widget.set_focusable]. Note that if items are not focusable, the keyboard cannot be used to activate them and selecting only works if one of the listitem's children is focusable. By default, list items are focusable. a `GtkListItem` if the item should be focusable Sets @self to be selectable. If an item is selectable, clicking on the item or using the keyboard will try to select or unselect the item. If this succeeds is up to the model to determine, as it is managing the selected state. Note that this means that making an item non-selectable has no influence on the selected state at all. A non-selectable item may still be selected. By default, list items are selectable. When rebinding them to a new item, they will also be reset to be selectable by GTK. a `GtkListItem` if the item should be selectable The accessible description to set on the list item. The accessible label to set on the list item. If the item can be activated by the user. Widget used for display. If the item can be focused with the keyboard. Displayed item. Position of the item. If the item can be selected by the user. If the item is currently selected. A `GtkListItemFactory` creates widgets for the items taken from a `GListModel`. This is one of the core concepts of handling list widgets such as [class@Gtk.ListView] or [class@Gtk.GridView]. The `GtkListItemFactory` is tasked with creating widgets for items taken from the model when the views need them and updating them as the items displayed by the view change. A view is usually only able to display anything after both a factory and a model have been set on the view. So it is important that you do not skip this step when setting up your first view. Because views do not display the whole list at once but only a few items, they only need to maintain a few widgets at a time. They will instruct the `GtkListItemFactory` to create these widgets and bind them to the items that are currently displayed. As the list model changes or the user scrolls to the list, the items will change and the view will instruct the factory to bind the widgets to those new items. The actual widgets used for displaying those widgets is provided by you. When the factory needs widgets created, it will create a `GtkListItem` and hand it to your code to set up a widget for. This list item will provide various properties with information about what item to display and provide you with some opportunities to configure its behavior. See the [class@Gtk.ListItem] documentation for further details. Various implementations of `GtkListItemFactory` exist to allow you different ways to provide those widgets. The most common implementations are [class@Gtk.BuilderListItemFactory] which takes a `GtkBuilder` .ui file and then creates widgets and manages everything automatically from the information in that file and [class@Gtk.SignalListItemFactory] which allows you to connect to signals with your own code and retain full control over how the widgets are setup and managed. A `GtkListItemFactory` is supposed to be final - that means its behavior should not change and the first widget created from it should behave the same way as the last widget created from it. If you intend to do changes to the behavior, it is recommended that you create a new `GtkListItemFactory` which will allow the views to recreate its widgets. Once you have chosen your factory and created it, you need to set it on the view widget you want to use it with, such as via [method@Gtk.ListView.set_factory]. Reusing factories across different views is allowed, but very uncommon. List of actions to perform when scrolling to items in a list widget. Don't do anything extra Focus the target item Select the target item and unselect all other items. A list-like data structure that can be used with the [class@Gtk.TreeView]. The `GtkListStore` object is a list model for use with a `GtkTreeView` widget. It implements the `GtkTreeModel` interface, and consequentialy, can use all of the methods available there. It also implements the `GtkTreeSortable` interface so it can be sorted by the view. Finally, it also implements the tree [drag](iface.TreeDragSource.html) and [drop](iface.TreeDragDest.html) interfaces. The `GtkListStore` can accept most `GType`s as a column type, though it can’t accept all custom types. Internally, it will keep a copy of data passed in (such as a string or a boxed pointer). Columns that accept `GObject`s are handled a little differently. The `GtkListStore` will keep a reference to the object instead of copying the value. As a result, if the object is modified, it is up to the application writer to call [method@Gtk.TreeModel.row_changed] to emit the [signal@Gtk.TreeModel::row_changed] signal. This most commonly affects lists with [class@Gdk.Texture]s stored. An example for creating a simple list store: ```c enum { COLUMN_STRING, COLUMN_INT, COLUMN_BOOLEAN, N_COLUMNS }; { GtkListStore *list_store; GtkTreePath *path; GtkTreeIter iter; int i; list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT, G_TYPE_BOOLEAN); for (i = 0; i < 10; i++) { char *some_data; some_data = get_some_data (i); // Add a new row to the model gtk_list_store_append (list_store, &iter); gtk_list_store_set (list_store, &iter, COLUMN_STRING, some_data, COLUMN_INT, i, COLUMN_BOOLEAN, FALSE, -1); // As the store will keep a copy of the string internally, // we free some_data. g_free (some_data); } // Modify a particular row path = gtk_tree_path_new_from_string ("4"); gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store), &iter, path); gtk_tree_path_free (path); gtk_list_store_set (list_store, &iter, COLUMN_BOOLEAN, TRUE, -1); } ``` `GtkListStore` is deprecated since GTK 4.10, and should not be used in newly written code. You should use [class@Gio.ListStore] instead, and the various list models provided by GTK. ## Performance Considerations Internally, the `GtkListStore` was originally implemented with a linked list with a tail pointer. As a result, it was fast at data insertion and deletion, and not fast at random data access. The `GtkListStore` sets the `GTK_TREE_MODEL_ITERS_PERSIST` flag, which means that `GtkTreeIter`s can be cached while the row exists. Thus, if access to a particular row is needed often and your code is expected to run on older versions of GTK, it is worth keeping the iter around. ## Atomic Operations It is important to note that only the methods gtk_list_store_insert_with_values() and gtk_list_store_insert_with_valuesv() are atomic, in the sense that the row is being appended to the store and the values filled in in a single operation with regard to `GtkTreeModel` signaling. In contrast, using e.g. gtk_list_store_append() and then gtk_list_store_set() will first create a row, which triggers the `GtkTreeModel::row-inserted` signal on `GtkListStore`. The row, however, is still empty, and any signal handler connecting to `GtkTreeModel::row-inserted` on this particular store should be prepared for the situation that the row might be empty. This is especially important if you are wrapping the `GtkListStore` inside a `GtkTreeModel`Filter and are using a `GtkTreeModel`FilterVisibleFunc. Using any of the non-atomic operations to append rows to the `GtkListStore` will cause the `GtkTreeModel`FilterVisibleFunc to be visited with an empty row first; the function must be prepared for that. ## GtkListStore as GtkBuildable The GtkListStore implementation of the [iface@Gtk.Buildable] interface allows to specify the model columns with a `<columns>` element that may contain multiple `<column>` elements, each specifying one model column. The “type” attribute specifies the data type for the column. Additionally, it is possible to specify content for the list store in the UI definition, with the `<data>` element. It can contain multiple `<row>` elements, each specifying to content for one row of the list model. Inside a `<row>`, the `<col>` elements specify the content for individual cells. Note that it is probably more common to define your models in the code, and one might consider it a layering violation to specify the content of a list store in a UI definition, data, not presentation, and common wisdom is to separate the two, as far as possible. An example of a UI Definition fragment for a list store: ```xml <object class="GtkListStore"> <columns> <column type="gchararray"/> <column type="gchararray"/> <column type="gint"/> </columns> <data> <row> <col id="0">John</col> <col id="1">Doe</col> <col id="2">25</col> </row> <row> <col id="0">Johan</col> <col id="1">Dahlin</col> <col id="2">50</col> </row> </data> </object> ``` Use [class@Gio.ListStore] instead Creates a new list store. The list store will have @n_columns columns, with each column using the given type passed to this function. Note that only types derived from standard GObject fundamental types are supported. As an example: ```c gtk_list_store_new (3, G_TYPE_INT, G_TYPE_STRING, GDK_TYPE_TEXTURE); ``` will create a new `GtkListStore` with three columns, of type `int`, `gchararray` and `GdkTexture`, respectively. Use [class@Gio.ListStore] instead a new `GtkListStore` number of columns in the list store all `GType` types for the columns, from first to last Creates a new `GtkListStore`. This function is meant to be used by language bindings. Use [class@Gio.ListStore] instead a new `GtkListStore` number of columns in the list store an array of `GType` types for the columns, from first to last Appends a new row to @list_store. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the appended row Removes all rows from the list store. Use list models a `GtkListStore`. Creates a new row at @position. @iter will be changed to point to this new row. If @position is -1 or is larger than the number of rows on the list, then the new row will be appended to the list. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the new row position to insert the new row, or -1 for last Inserts a new row after @sibling. If @sibling is %NULL, then the row will be prepended to the beginning of the list. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the new row A valid `GtkTreeIter` Inserts a new row before @sibling. If @sibling is %NULL, then the row will be appended to the end of the list. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the new row A valid `GtkTreeIter` Creates a new row at @position. @iter will be changed to point to this new row. If @position is -1, or larger than the number of rows in the list, then the new row will be appended to the list. The row will be filled with the values given to this function. Calling `gtk_list_store_insert_with_values (list_store, iter, position...)` has the same effect as calling: |[<!-- language="C" --> static void insert_value (GtkListStore *list_store, GtkTreeIter *iter, int position) { gtk_list_store_insert (list_store, iter, position); gtk_list_store_set (list_store, iter // ... ); } ]| with the difference that the former will only emit `GtkTreeModel`::row-inserted once, while the latter will emit `GtkTreeModel`::row-inserted, `GtkTreeModel`::row-changed and, if the list store is sorted, `GtkTreeModel`::rows-reordered for every inserted value. Since emitting the `GtkTreeModel::rows-reordered` signal repeatedly can affect the performance of the program, gtk_list_store_insert_with_values() should generally be preferred when inserting rows in a sorted list store. Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the new row position to insert the new row, or -1 to append after existing rows pairs of column number and value, terminated with -1 A variant of gtk_list_store_insert_with_values() which takes the columns and values as two arrays, instead of varargs. This function is mainly intended for language-bindings. Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the new row position to insert the new row, or -1 for last an array of column numbers an array of GValues the length of the @columns and @values arrays Checks if the given iter is a valid iter for this `GtkListStore`. This function is slow. Only use it for debugging and/or testing purposes. Use list models %TRUE if the iter is valid, %FALSE if the iter is invalid. a list store the iterator to check Moves @iter in @store to the position after @position. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the start of the list. Use list models A `GtkListStore`. A `GtkTreeIter` A `GtkTreeIter` Moves @iter in @store to the position before @position. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the end of the list. Use list models A `GtkListStore`. A `GtkTreeIter` A `GtkTreeIter` Prepends a new row to @list_store. @iter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_list_store_set() or gtk_list_store_set_value(). Use list models A `GtkListStore` An unset `GtkTreeIter` to set to the prepend row Removes the given row from the list store. After being removed, @iter is set to be the next valid row, or invalidated if it pointed to the last row in @list_store. Use list models %TRUE if @iter is valid, %FALSE if not. A `GtkListStore` A valid `GtkTreeIter` Reorders @store to follow the order indicated by @new_order. Note that this function only works with unsorted stores. Use list models A `GtkListStore`. an array of integers mapping the new position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos`. It must have exactly as many items as the list store’s length. Sets the value of one or more cells in the row referenced by @iter. The variable argument list should contain integer column numbers, each column number followed by the value to be set. The list is terminated by a -1. For example, to set column 0 with type %G_TYPE_STRING to “Foo”, you would write `gtk_list_store_set (store, iter, 0, "Foo", -1)`. The value will be referenced by the store if it is a %G_TYPE_OBJECT, and it will be copied if it is a %G_TYPE_STRING or %G_TYPE_BOXED. Use list models a `GtkListStore` row iterator pairs of column number and value, terminated with -1 Sets the types of the columns of a list store. This function is meant primarily for objects that inherit from `GtkListStore`, and should only be used when constructing a new instance. This function cannot be called after a row has been added, or a method on the `GtkTreeModel` interface is called. Use list models A `GtkListStore` Number of columns for the list store An array length n of `GType`s See gtk_list_store_set(); this version takes a va_list for use by language bindings. Use list models A `GtkListStore` A valid `GtkTreeIter` for the row being modified va_list of column/value pairs Sets the data in the cell specified by @iter and @column. The type of @value must be convertible to the type of the column. Use list models A `GtkListStore` A valid `GtkTreeIter` for the row being modified column number to modify new value for the cell A variant of gtk_list_store_set_valist() which takes the columns and values as two arrays, instead of varargs. This function is mainly intended for language-bindings and in case the number of columns to change is not known until run-time. Use list models A `GtkListStore` A valid `GtkTreeIter` for the row being modified an array of column numbers an array of GValues the length of the @columns and @values arrays Swaps @a and @b in @store. Note that this function only works with unsorted stores. Use list models A `GtkListStore`. A `GtkTreeIter` Another `GtkTreeIter` Used to configure the focus behavior in the `GTK_DIR_TAB_FORWARD` and `GTK_DIR_TAB_BACKWARD` direction, like the <kbd>Tab</kbd> key in a [class@Gtk.ListView]. Cycle through all focusable items of the list Cycle through a single list element, then move focus out of the list. Moving focus between items needs to be done with the arrow keys. Cycle only through a single cell, then move focus out of the list. Moving focus between cells needs to be done with the arrow keys. This is only relevant for cell-based widgets like #GtkColumnView, otherwise it behaves like `GTK_LIST_TAB_ITEM`. `GtkListView` presents a large dynamic list of items. `GtkListView` uses its factory to generate one row widget for each visible item and shows them in a linear display, either vertically or horizontally. The [property@Gtk.ListView:show-separators] property offers a simple way to display separators between the rows. `GtkListView` allows the user to select items according to the selection characteristics of the model. For models that allow multiple selected items, it is possible to turn on _rubberband selection_, using [property@Gtk.ListView:enable-rubberband]. If you need multiple columns with headers, see [class@Gtk.ColumnView]. To learn more about the list widget framework, see the [overview](section-list-widget.html). An example of using `GtkListView`: ```c static void setup_listitem_cb (GtkListItemFactory *factory, GtkListItem *list_item) { GtkWidget *image; image = gtk_image_new (); gtk_image_set_icon_size (GTK_IMAGE (image), GTK_ICON_SIZE_LARGE); gtk_list_item_set_child (list_item, image); } static void bind_listitem_cb (GtkListItemFactory *factory, GtkListItem *list_item) { GtkWidget *image; GAppInfo *app_info; image = gtk_list_item_get_child (list_item); app_info = gtk_list_item_get_item (list_item); gtk_image_set_from_gicon (GTK_IMAGE (image), g_app_info_get_icon (app_info)); } static void activate_cb (GtkListView *list, guint position, gpointer unused) { GAppInfo *app_info; app_info = g_list_model_get_item (G_LIST_MODEL (gtk_list_view_get_model (list)), position); g_app_info_launch (app_info, NULL, NULL, NULL); g_object_unref (app_info); } ... model = create_application_list (); factory = gtk_signal_list_item_factory_new (); g_signal_connect (factory, "setup", G_CALLBACK (setup_listitem_cb), NULL); g_signal_connect (factory, "bind", G_CALLBACK (bind_listitem_cb), NULL); list = gtk_list_view_new (GTK_SELECTION_MODEL (gtk_single_selection_new (model)), factory); g_signal_connect (list, "activate", G_CALLBACK (activate_cb), NULL); gtk_scrolled_window_set_child (GTK_SCROLLED_WINDOW (sw), list); ``` # Actions `GtkListView` defines a set of built-in actions: - `list.activate-item` activates the item at given position by emitting the [signal@Gtk.ListView::activate] signal. # CSS nodes ``` listview[.separators][.rich-list][.navigation-sidebar][.data-table] ├── row[.activatable] │ ├── row[.activatable] │ ┊ ╰── [rubberband] ``` `GtkListView` uses a single CSS node named `listview`. It may carry the `.separators` style class, when [property@Gtk.ListView:show-separators] property is set. Each child widget uses a single CSS node named `row`. If the [property@Gtk.ListItem:activatable] property is set, the corresponding row will have the `.activatable` style class. For rubberband selection, a node with name `rubberband` is used. The main listview node may also carry style classes to select the style of [list presentation](ListContainers.html#list-styles): .rich-list, .navigation-sidebar or .data-table. # Accessibility `GtkListView` uses the %GTK_ACCESSIBLE_ROLE_LIST role, and the list items use the %GTK_ACCESSIBLE_ROLE_LIST_ITEM role. Creates a new `GtkListView` that uses the given @factory for mapping items to widgets. The function takes ownership of the arguments, so you can write code like ```c list_view = gtk_list_view_new (create_model (), gtk_builder_list_item_factory_new_from_resource ("/resource.ui")); ``` a new `GtkListView` using the given @model and @factory the model to use The factory to populate items with Returns whether rows can be selected by dragging with the mouse. %TRUE if rubberband selection is enabled a `GtkListView` Gets the factory that's currently used to populate list items. The factory in use a `GtkListView` Gets the factory that's currently used to populate section headers. The factory in use a `GtkListView` Gets the model that's currently used to read the items displayed. The model in use a `GtkListView` Returns whether the list box should show separators between rows. %TRUE if the list box shows separators a `GtkListView` Returns whether rows will be activated on single click and selected on hover. %TRUE if rows are activated on single click a `GtkListView` Gets the behavior set for the <kbd>Tab</kbd> key. The behavior of the <kbd>Tab</kbd> key a `GtkListView` Scrolls to the item at the given position and performs the actions specified in @flags. This function works no matter if the listview is shown or focused. If it isn't, then the changes will take effect once that happens. The listview to scroll in position of the item. Must be less than the number of items in the view. actions to perform details of how to perform the scroll operation or %NULL to scroll into view Sets whether selections can be changed by dragging with the mouse. a `GtkListView` %TRUE to enable rubberband selection Sets the `GtkListItemFactory` to use for populating list items. a `GtkListView` the factory to use Sets the `GtkListItemFactory` to use for populating the [class@Gtk.ListHeader] objects used in section headers. If this factory is set to %NULL, the list will not show section headers. a `GtkListView` the factory to use Sets the model to use. This must be a [iface@Gtk.SelectionModel] to use. a `GtkListView` the model to use Sets whether the list box should show separators between rows. a `GtkListView` %TRUE to show separators Sets whether rows should be activated on single click and selected on hover. a `GtkListView` %TRUE to activate items on single click Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. a `GtkListView` The desired tab behavior Allow rubberband selection. Factory for populating list items. The factory must be for configuring [class@Gtk.ListItem] objects. Factory for creating header widgets. The factory must be for configuring [class@Gtk.ListHeader] objects. Model for the items displayed. Show separators between rows. Activate rows on single click and select them on hover. Behavior of the <kbd>Tab</kbd> key Emitted when a row has been activated by the user, usually via activating the GtkListView|list.activate-item action. This allows for a convenient way to handle activation in a listview. See [method@Gtk.ListItem.set_activatable] for details on how to use this signal. position of item to activate `GtkLockButton` is a widget to obtain and revoke authorizations needed to operate the controls.  It is typically used in preference dialogs or control panels. The required authorization is represented by a `GPermission` object. Concrete implementations of `GPermission` may use PolicyKit or some other authorization framework. To obtain a PolicyKit-based `GPermission`, use `polkit_permission_new()`. If the user is not currently allowed to perform the action, but can obtain the permission, the widget looks like this:  and the user can click the button to request the permission. Depending on the platform, this may pop up an authentication dialog or ask the user to authenticate in some other way. Once the user has obtained the permission, the widget changes to this:  and the permission can be dropped again by clicking the button. If the user is not able to obtain the permission at all, the widget looks like this:  If the user has the permission and cannot drop it, the button is hidden. The text (and tooltips) that are shown in the various cases can be adjusted with the [property@Gtk.LockButton:text-lock], [property@Gtk.LockButton:text-unlock], [property@Gtk.LockButton:tooltip-lock], [property@Gtk.LockButton:tooltip-unlock] and [property@Gtk.LockButton:tooltip-not-authorized] properties. This widget will be removed in GTK 5 Creates a new lock button which reflects the @permission. This widget will be removed in GTK 5 a new `GtkLockButton` a `GPermission` Obtains the `GPermission` object that controls @button. This widget will be removed in GTK 5 the `GPermission` of @button a `GtkLockButton` Sets the `GPermission` object that controls @button. This widget will be removed in GTK 5 a `GtkLockButton` a `GPermission` object The `GPermission object controlling this button. This widget will be removed in GTK 5 The text to display when prompting the user to lock. This widget will be removed in GTK 5 The text to display when prompting the user to unlock. This widget will be removed in GTK 5 The tooltip to display when prompting the user to lock. This widget will be removed in GTK 5 The tooltip to display when the user cannot obtain authorization. This widget will be removed in GTK 5 The tooltip to display when prompting the user to unlock. This widget will be removed in GTK 5 Like [func@get_major_version], but from the headers used at application compile time, rather than from the library linked against at application run time. Evaluates to the maximum length of a compose sequence. This macro is longer used by GTK. The default extension point name for media file. Like [func@get_micro_version], but from the headers used at application compile time, rather than from the library linked against at application run time. Like [func@get_minor_version], but from the headers used at application compile time, rather than from the library linked against at application run time. A `GtkMapListModel` maps the items in a list model to different items. `GtkMapListModel` uses a [callback@Gtk.MapListModelMapFunc]. Example: Create a list of `GtkEventControllers` ```c static gpointer map_to_controllers (gpointer widget, gpointer data) { gpointer result = gtk_widget_observe_controllers (widget); g_object_unref (widget); return result; } widgets = gtk_widget_observe_children (widget); controllers = gtk_map_list_model_new (widgets, map_to_controllers, NULL, NULL); model = gtk_flatten_list_model_new (GTK_TYPE_EVENT_CONTROLLER, controllers); ``` `GtkMapListModel` will attempt to discard the mapped objects as soon as they are no longer needed and recreate them if necessary. `GtkMapListModel` passes through sections from the underlying model. Creates a new `GtkMapListModel` for the given arguments. a new `GtkMapListModel` The model to map map function user data passed to @map_func destroy notifier for @user_data Gets the model that is currently being mapped or %NULL if none. The model that gets mapped a `GtkMapListModel` Checks if a map function is currently set on @self. %TRUE if a map function is set a `GtkMapListModel` Sets the function used to map items. The function will be called whenever an item needs to be mapped and must return the item to use for the given input item. Note that `GtkMapListModel` may call this function multiple times on the same item, because it may delete items it doesn't need anymore. GTK makes no effort to ensure that @map_func conforms to the item type of @self. It assumes that the caller knows what they are doing and the map function returns items of the appropriate type. a `GtkMapListModel` map function user data passed to @map_func destroy notifier for @user_data Sets the model to be mapped. GTK makes no effort to ensure that @model conforms to the item type expected by the map function. It assumes that the caller knows what they are doing and have set up an appropriate map function. a `GtkMapListModel` The model to be mapped If a map is set for this model The type of items. See [method@Gio.ListModel.get_item_type]. The model being mapped. The number of items. See [method@Gio.ListModel.get_n_items]. User function that is called to map an @item of the original model to an item expected by the map model. The returned items must conform to the item type of the model they are used with. The item to map to The item to map user data `GtkMediaControls` is a widget to show controls for a video.  Usually, `GtkMediaControls` is used as part of [class@Gtk.Video]. Creates a new `GtkMediaControls` managing the @stream passed to it. a new `GtkMediaControls` a `GtkMediaStream` to manage Gets the media stream managed by @controls or %NULL if none. The media stream managed by @controls a `GtkMediaControls` Sets the stream that is controlled by @controls. a `GtkMediaControls` widget a `GtkMediaStream` The media-stream managed by this object or %NULL if none. `GtkMediaFile` implements `GtkMediaStream` for files. This provides a simple way to play back video files with GTK. GTK provides a GIO extension point for `GtkMediaFile` implementations to allow for external implementations using various media frameworks. GTK itself includes an implementation using GStreamer. Creates a new empty media file. a new `GtkMediaFile` Creates a new media file to play @file. a new `GtkMediaFile` playing @file The file to play Creates a new media file for the given filename. This is a utility function that converts the given @filename to a `GFile` and calls [ctor@Gtk.MediaFile.new_for_file]. a new `GtkMediaFile` playing @filename filename to open Creates a new media file to play @stream. If you want the resulting media to be seekable, the stream should implement the `GSeekable` interface. a new `GtkMediaFile` The stream to play Creates a new new media file for the given resource. This is a utility function that converts the given @resource to a `GFile` and calls [ctor@Gtk.MediaFile.new_for_file]. a new `GtkMediaFile` playing @resource_path resource path to open Resets the media file to be empty. a `GtkMediaFile` Returns the file that @self is currently playing from. When @self is not playing or not playing from a file, %NULL is returned. The currently playing file a `GtkMediaFile` Returns the stream that @self is currently playing from. When @self is not playing or not playing from a stream, %NULL is returned. The currently playing stream a `GtkMediaFile` Sets the `GtkMediaFile` to play the given file. If any file is still playing, stop playing it. a `GtkMediaFile` the file to play Sets the `GtkMediaFile to play the given file. This is a utility function that converts the given @filename to a `GFile` and calls [method@Gtk.MediaFile.set_file]. a `GtkMediaFile` name of file to play Sets the `GtkMediaFile` to play the given stream. If anything is still playing, stop playing it. Full control about the @stream is assumed for the duration of playback. The stream will not be closed. a `GtkMediaFile` the stream to play from Sets the `GtkMediaFile to play the given resource. This is a utility function that converts the given @resource_path to a `GFile` and calls [method@Gtk.MediaFile.set_file]. a `GtkMediaFile` path to resource to play The file being played back or %NULL if not playing a file. The stream being played back or %NULL if not playing a stream. This is %NULL when playing a file. `GtkMediaStream` is the integration point for media playback inside GTK. GTK provides an implementation of the `GtkMediaStream` interface that is called [class@Gtk.MediaFile]. Apart from application-facing API for stream playback, `GtkMediaStream` has a number of APIs that are only useful for implementations and should not be used in applications: [method@Gtk.MediaStream.prepared], [method@Gtk.MediaStream.unprepared], [method@Gtk.MediaStream.update], [method@Gtk.MediaStream.ended], [method@Gtk.MediaStream.seek_success], [method@Gtk.MediaStream.seek_failed], [method@Gtk.MediaStream.gerror], [method@Gtk.MediaStream.error], [method@Gtk.MediaStream.error_valist]. Pauses playback of the stream. If the stream is not playing, do nothing. a `GtkMediaStream` Called by users to attach the media stream to a `GdkSurface` they manage. The stream can then access the resources of @surface for its rendering purposes. In particular, media streams might want to create a `GdkGLContext` or sync to the `GdkFrameClock`. Whoever calls this function is responsible for calling [method@Gtk.MediaStream.unrealize] before either the stream or @surface get destroyed. Multiple calls to this function may happen from different users of the video, even with the same @surface. Each of these calls must be followed by its own call to [method@Gtk.MediaStream.unrealize]. It is not required to call this function to make a media stream work. a `GtkMediaStream` a `GdkSurface` Start a seek operation on @self to @timestamp. If @timestamp is out of range, it will be clamped. Seek operations may not finish instantly. While a seek operation is in process, the [property@Gtk.MediaStream:seeking] property will be set. When calling gtk_media_stream_seek() during an ongoing seek operation, the new seek will override any pending seek. a `GtkMediaStream` timestamp to seek to. Undoes a previous call to gtk_media_stream_realize(). This causes the stream to release all resources it had allocated from @surface. a `GtkMediaStream` previously realized the `GdkSurface` the stream was realized with Pauses the media stream and marks it as ended. This is a hint only, calls to [method@Gtk.MediaStream.play] may still happen. The media stream must be prepared when this function is called. Use [method@Gtk.MediaStream.stream_ended] instead a `GtkMediaStream` Sets @self into an error state using a printf()-style format string. This is a utility function that calls [method@Gtk.MediaStream.gerror]. See that function for details. a `GtkMediaStream` error domain error code printf()-style format for error message parameters for message format Sets @self into an error state using a printf()-style format string. This is a utility function that calls [method@Gtk.MediaStream.gerror]. See that function for details. a `GtkMediaStream` error domain error code printf()-style format for error message `va_list` of parameters for the message format Sets @self into an error state. This will pause the stream (you can check for an error via [method@Gtk.MediaStream.get_error] in your GtkMediaStream.pause() implementation), abort pending seeks and mark the stream as prepared. if the stream is already in an error state, this call will be ignored and the existing error will be retained. To unset an error, the stream must be reset via a call to [method@Gtk.MediaStream.unprepared]. a `GtkMediaStream` the `GError` to set Gets the duration of the stream. If the duration is not known, 0 will be returned. the duration of the stream or 0 if not known. a `GtkMediaStream` Returns whether the streams playback is finished. %TRUE if playback is finished a `GtkMediaStream` If the stream is in an error state, returns the `GError` explaining that state. Any type of error can be reported here depending on the implementation of the media stream. A media stream in an error cannot be operated on, calls like [method@Gtk.MediaStream.play] or [method@Gtk.MediaStream.seek] will not have any effect. `GtkMediaStream` itself does not provide a way to unset an error, but implementations may provide options. For example, a [class@Gtk.MediaFile] will unset errors when a new source is set, e.g. with [method@Gtk.MediaFile.set_file]. %NULL if not in an error state or the `GError` of the stream a `GtkMediaStream` Returns whether the stream is set to loop. See [method@Gtk.MediaStream.set_loop] for details. %TRUE if the stream should loop a `GtkMediaStream` Returns whether the audio for the stream is muted. See [method@Gtk.MediaStream.set_muted] for details. %TRUE if the stream is muted a `GtkMediaStream` Return whether the stream is currently playing. %TRUE if the stream is playing a `GtkMediaStream` Returns the current presentation timestamp in microseconds. the timestamp in microseconds a `GtkMediaStream` Returns the volume of the audio for the stream. See [method@Gtk.MediaStream.set_volume] for details. volume of the stream from 0.0 to 1.0 a `GtkMediaStream` Returns whether the stream has audio. %TRUE if the stream has audio a `GtkMediaStream` Returns whether the stream has video. %TRUE if the stream has video a `GtkMediaStream` Returns whether the stream has finished initializing. At this point the existence of audio and video is known. %TRUE if the stream is prepared a `GtkMediaStream` Checks if a stream may be seekable. This is meant to be a hint. Streams may not allow seeking even if this function returns %TRUE. However, if this function returns %FALSE, streams are guaranteed to not be seekable and user interfaces may hide controls that allow seeking. It is allowed to call [method@Gtk.MediaStream.seek] on a non-seekable stream, though it will not do anything. %TRUE if the stream may support seeking a `GtkMediaStream` Checks if there is currently a seek operation going on. %TRUE if a seek operation is ongoing. a `GtkMediaStream` Pauses playback of the stream. If the stream is not playing, do nothing. a `GtkMediaStream` Starts playing the stream. If the stream is in error or already playing, do nothing. a `GtkMediaStream` Same as gtk_media_stream_stream_prepared(). Use [method@Gtk.MediaStream.stream_prepared] instead. a `GtkMediaStream` %TRUE if the stream should advertise audio support %TRUE if the stream should advertise video support %TRUE if the stream should advertise seekability The duration of the stream or 0 if unknown Called by users to attach the media stream to a `GdkSurface` they manage. The stream can then access the resources of @surface for its rendering purposes. In particular, media streams might want to create a `GdkGLContext` or sync to the `GdkFrameClock`. Whoever calls this function is responsible for calling [method@Gtk.MediaStream.unrealize] before either the stream or @surface get destroyed. Multiple calls to this function may happen from different users of the video, even with the same @surface. Each of these calls must be followed by its own call to [method@Gtk.MediaStream.unrealize]. It is not required to call this function to make a media stream work. a `GtkMediaStream` a `GdkSurface` Start a seek operation on @self to @timestamp. If @timestamp is out of range, it will be clamped. Seek operations may not finish instantly. While a seek operation is in process, the [property@Gtk.MediaStream:seeking] property will be set. When calling gtk_media_stream_seek() during an ongoing seek operation, the new seek will override any pending seek. a `GtkMediaStream` timestamp to seek to. Ends a seek operation started via GtkMediaStream.seek() as a failure. This will not cause an error on the stream and will assume that playback continues as if no seek had happened. See [method@Gtk.MediaStream.seek_success] for the other way of ending a seek. a `GtkMediaStream` Ends a seek operation started via GtkMediaStream.seek() successfully. This function will unset the GtkMediaStream:ended property if it was set. See [method@Gtk.MediaStream.seek_failed] for the other way of ending a seek. a `GtkMediaStream` Sets whether the stream should loop. In this case, it will attempt to restart playback from the beginning instead of stopping at the end. Not all streams may support looping, in particular non-seekable streams. Those streams will ignore the loop setting and just end. a `GtkMediaStream` %TRUE if the stream should loop Sets whether the audio stream should be muted. Muting a stream will cause no audio to be played, but it does not modify the volume. This means that muting and then unmuting the stream will restore the volume settings. If the stream has no audio, calling this function will still work but it will not have an audible effect. a `GtkMediaStream` %TRUE if the stream should be muted Starts or pauses playback of the stream. a `GtkMediaStream` whether to start or pause playback Sets the volume of the audio stream. This function call will work even if the stream is muted. The given @volume should range from 0.0 for silence to 1.0 for as loud as possible. Values outside of this range will be clamped to the nearest value. If the stream has no audio or is muted, calling this function will still work but it will not have an immediate audible effect. When the stream is unmuted, the new volume setting will take effect. a `GtkMediaStream` New volume of the stream from 0.0 to 1.0 Pauses the media stream and marks it as ended. This is a hint only, calls to [method@Gtk.MediaStream.play] may still happen. The media stream must be prepared when this function is called. a `GtkMediaStream` Called by `GtkMediaStream` implementations to advertise the stream being ready to play and providing details about the stream. Note that the arguments are hints. If the stream implementation cannot determine the correct values, it is better to err on the side of caution and return %TRUE. User interfaces will use those values to determine what controls to show. This function may not be called again until the stream has been reset via [method@Gtk.MediaStream.stream_unprepared]. a `GtkMediaStream` %TRUE if the stream should advertise audio support %TRUE if the stream should advertise video support %TRUE if the stream should advertise seekability The duration of the stream or 0 if unknown Resets a given media stream implementation. [method@Gtk.MediaStream.stream_prepared] can then be called again. This function will also reset any error state the stream was in. a `GtkMediaStream` Same as gtk_media_stream_stream_unprepared(). Use [method@Gtk.MediaStream.stream_unprepared] instead. a `GtkMediaStream` Undoes a previous call to gtk_media_stream_realize(). This causes the stream to release all resources it had allocated from @surface. a `GtkMediaStream` previously realized the `GdkSurface` the stream was realized with Media stream implementations should regularly call this function to update the timestamp reported by the stream. It is up to implementations to call this at the frequency they deem appropriate. The media stream must be prepared when this function is called. a `GtkMediaStream` the new timestamp The stream's duration in microseconds or 0 if unknown. Set when playback has finished. %NULL for a properly working stream or the `GError` that the stream is in. Whether the stream contains audio. Whether the stream contains video. Try to restart the media from the beginning once it ended. Whether the audio stream should be muted. Whether the stream is currently playing. Whether the stream has finished initializing and existence of audio and video is known. Set unless the stream is known to not support seeking. Set while a seek is in progress. The current presentation timestamp in microseconds. Volume of the audio stream. a `GtkMediaStream` a `GtkMediaStream` timestamp to seek to. a `GtkMediaStream` a `GdkSurface` a `GtkMediaStream` previously realized the `GdkSurface` the stream was realized with The `GtkMenuButton` widget is used to display a popup when clicked.  This popup can be provided either as a `GtkPopover` or as an abstract `GMenuModel`. The `GtkMenuButton` widget can show either an icon (set with the [property@Gtk.MenuButton:icon-name] property) or a label (set with the [property@Gtk.MenuButton:label] property). If neither is explicitly set, a [class@Gtk.Image] is automatically created, using an arrow image oriented according to [property@Gtk.MenuButton:direction] or the generic “open-menu-symbolic” icon if the direction is not set. The positioning of the popup is determined by the [property@Gtk.MenuButton:direction] property of the menu button. For menus, the [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties of the menu are also taken into account. For example, when the direction is %GTK_ARROW_DOWN and the horizontal alignment is %GTK_ALIGN_START, the menu will be positioned below the button, with the starting edge (depending on the text direction) of the menu aligned with the starting edge of the button. If there is not enough space below the button, the menu is popped up above the button instead. If the alignment would move part of the menu offscreen, it is “pushed in”. | | start | center | end | | - | --- | --- | --- | | **down** |  |  |  | | **up** |  |  |  | | **left** |  |  |  | | **right** |  |  |  | # CSS nodes ``` menubutton ╰── button.toggle ╰── <content> ╰── [arrow] ``` `GtkMenuButton` has a single CSS node with name `menubutton` which contains a `button` node with a `.toggle` style class. If the button contains an icon, it will have the `.image-button` style class, if it contains text, it will have `.text-button` style class. If an arrow is visible in addition to an icon, text or a custom child, it will also have `.arrow-button` style class. Inside the toggle button content, there is an `arrow` node for the indicator, which will carry one of the `.none`, `.up`, `.down`, `.left` or `.right` style classes to indicate the direction that the menu will appear in. The CSS is expected to provide a suitable image for each of these cases using the `-gtk-icon-source` property. Optionally, the `menubutton` node can carry the `.circular` style class to request a round appearance. # Accessibility `GtkMenuButton` uses the %GTK_ACCESSIBLE_ROLE_BUTTON role. Creates a new `GtkMenuButton` widget with downwards-pointing arrow as the only child. You can replace the child widget with another `GtkWidget` should you wish to. The newly created `GtkMenuButton` Returns whether the menu button is active. TRUE if the button is active a `GtkMenuButton` Gets whether to show a dropdown arrow even when using an icon or a custom child. whether to show a dropdown arrow even when using an icon or a custom child. a `GtkMenuButton` Retrieves whether the button can be smaller than the natural size of its contents. true if the button can shrink, and false otherwise a button Gets the child widget of @menu_button. the child widget of @menu_button a `GtkMenuButton` Returns the direction the popup will be pointing at when popped up. a `GtkArrowType` value a `GtkMenuButton` Returns whether the button has a frame. %TRUE if the button has a frame a `GtkMenuButton` Gets the name of the icon shown in the button. the name of the icon shown in the button a `GtkMenuButton` Gets the label shown in the button the label shown in the button a `GtkMenuButton` Returns the `GMenuModel` used to generate the popup. a `GMenuModel` a `GtkMenuButton` Returns the `GtkPopover` that pops out of the button. If the button is not using a `GtkPopover`, this function returns %NULL. a `GtkPopover` or %NULL a `GtkMenuButton` Returns whether the menu button acts as a primary menu. %TRUE if the button is a primary menu a `GtkMenuButton` Returns whether an embedded underline in the text indicates a mnemonic. %TRUE whether an embedded underline in the text indicates the mnemonic accelerator keys. a `GtkMenuButton` Dismiss the menu. a `GtkMenuButton` Pop up the menu. a `GtkMenuButton` Sets whether the menu button is active. a `GtkMenuButton` whether the menu button is active Sets whether to show a dropdown arrow even when using an icon or a custom child. a `GtkMenuButton` whether to show a dropdown arrow even when using an icon or a custom child Sets whether the button size can be smaller than the natural size of its contents. For text buttons, setting @can_shrink to true will ellipsize the label. For icon buttons, this function has no effect. a menu button whether the button can shrink Sets the child widget of @menu_button. Setting a child resets [property@Gtk.MenuButton:label] and [property@Gtk.MenuButton:icon-name]. If [property@Gtk.MenuButton:always-show-arrow] is set to `TRUE` and [property@Gtk.MenuButton:direction] is not `GTK_ARROW_NONE`, a dropdown arrow will be shown next to the child. a `GtkMenuButton` the child widget Sets @func to be called when a popup is about to be shown. @func should use one of - [method@Gtk.MenuButton.set_popover] - [method@Gtk.MenuButton.set_menu_model] to set a popup for @menu_button. If @func is non-%NULL, @menu_button will always be sensitive. Using this function will not reset the menu widget attached to @menu_button. Instead, this can be done manually in @func. a `GtkMenuButton` function to call when a popup is about to be shown, but none has been provided via other means, or %NULL to reset to default behavior user data to pass to @func destroy notify for @user_data Sets the direction in which the popup will be popped up. If the button is automatically populated with an arrow icon, its direction will be changed to match. If the does not fit in the available space in the given direction, GTK will its best to keep it inside the screen and fully visible. If you pass %GTK_ARROW_NONE for a @direction, the popup will behave as if you passed %GTK_ARROW_DOWN (although you won’t see any arrows). a `GtkMenuButton` a `GtkArrowType` Sets the style of the button. a `GtkMenuButton` whether the button should have a visible frame Sets the name of an icon to show inside the menu button. Setting icon name resets [property@Gtk.MenuButton:label] and [property@Gtk.MenuButton:child]. If [property@Gtk.MenuButton:always-show-arrow] is set to `TRUE` and [property@Gtk.MenuButton:direction] is not `GTK_ARROW_NONE`, a dropdown arrow will be shown next to the icon. a `GtkMenuButton` the icon name Sets the label to show inside the menu button. Setting a label resets [property@Gtk.MenuButton:icon-name] and [property@Gtk.MenuButton:child]. If [property@Gtk.MenuButton:direction] is not `GTK_ARROW_NONE`, a dropdown arrow will be shown next to the label. a `GtkMenuButton` the label Sets the `GMenuModel` from which the popup will be constructed. If @menu_model is %NULL, the button is disabled. A [class@Gtk.Popover] will be created from the menu model with [ctor@Gtk.PopoverMenu.new_from_model]. Actions will be connected as documented for this function. If [property@Gtk.MenuButton:popover] is already set, it will be dissociated from the @menu_button, and the property is set to %NULL. a `GtkMenuButton` a `GMenuModel`, or %NULL to unset and disable the button Sets the `GtkPopover` that will be popped up when the @menu_button is clicked. If @popover is %NULL, the button is disabled. If [property@Gtk.MenuButton:menu-model] is set, the menu model is dissociated from the @menu_button, and the property is set to %NULL. a `GtkMenuButton` a `GtkPopover`, or %NULL to unset and disable the button Sets whether menu button acts as a primary menu. Primary menus can be opened with the <kbd>F10</kbd> key. a `GtkMenuButton` whether the menubutton should act as a primary menu If true, an underline in the text indicates a mnemonic. a `GtkMenuButton` %TRUE if underlines in the text indicate mnemonics Whether the menu button is active. Whether to show a dropdown arrow even when using an icon or a custom child. Whether the size of the button can be made smaller than the natural size of its contents. The child widget. The `GtkArrowType` representing the direction in which the menu or popover will be popped out. Whether the button has a frame. The name of the icon used to automatically populate the button. The label for the button. The `GMenuModel` from which the popup will be created. See [method@Gtk.MenuButton.set_menu_model] for the interaction with the [property@Gtk.MenuButton:popover] property. The `GtkPopover` that will be popped up when the button is clicked. Whether the menu button acts as a primary menu. Primary menus can be opened using the <kbd>F10</kbd> key If set an underscore in the text indicates a mnemonic. Emitted to when the menu button is activated. The `::activate` signal on `GtkMenuButton` is an action signal and emitting it causes the button to pop up its menu. User-provided callback function to create a popup for a `GtkMenuButton` on demand. This function is called when the popup of @menu_button is shown, but none has been provided via [method@Gtk.MenuButton.set_popover] or [method@Gtk.MenuButton.set_menu_model]. the `GtkMenuButton` User data passed to gtk_menu_button_set_create_popup_func() `GtkMessageDialog` presents a dialog with some message text.  It’s simply a convenience widget; you could construct the equivalent of `GtkMessageDialog` from `GtkDialog` without too much effort, but `GtkMessageDialog` saves typing. The easiest way to do a modal message dialog is to use the %GTK_DIALOG_MODAL flag, which will call [method@Gtk.Window.set_modal] internally. The dialog will prevent interaction with the parent window until it's hidden or destroyed. You can use the [signal@Gtk.Dialog::response] signal to know when the user dismissed the dialog. An example for using a modal dialog: ```c GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT | GTK_DIALOG_MODAL; dialog = gtk_message_dialog_new (parent_window, flags, GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, "Error reading “%s”: %s", filename, g_strerror (errno)); // Destroy the dialog when the user responds to it // (e.g. clicks a button) g_signal_connect (dialog, "response", G_CALLBACK (gtk_window_destroy), NULL); ``` You might do a non-modal `GtkMessageDialog` simply by omitting the %GTK_DIALOG_MODAL flag: ```c GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_message_dialog_new (parent_window, flags, GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, "Error reading “%s”: %s", filename, g_strerror (errno)); // Destroy the dialog when the user responds to it // (e.g. clicks a button) g_signal_connect (dialog, "response", G_CALLBACK (gtk_window_destroy), NULL); ``` # GtkMessageDialog as GtkBuildable The `GtkMessageDialog` implementation of the `GtkBuildable` interface exposes the message area as an internal child with the name “message_area”. Use [class@Gtk.AlertDialog] instead Creates a new message dialog. This is a simple dialog with some text the user may want to see. When the user clicks a button a “response” signal is emitted with response IDs from [enum@Gtk.ResponseType]. See [class@Gtk.Dialog] for more details. Use [class@Gtk.AlertDialog] instead a new `GtkMessageDialog` transient parent flags type of message set of buttons to use printf()-style format string arguments for @message_format Creates a new message dialog. This is a simple dialog with some text that is marked up with Pango markup. When the user clicks a button a “response” signal is emitted with response IDs from [enum@Gtk.ResponseType]. See [class@Gtk.Dialog] for more details. Special XML characters in the printf() arguments passed to this function will automatically be escaped as necessary. (See g_markup_printf_escaped() for how this is implemented.) Usually this is what you want, but if you have an existing Pango markup string that you want to use literally as the label, then you need to use [method@Gtk.MessageDialog.set_markup] instead, since you can’t pass the markup string either as the format (it might contain “%” characters) or as a string argument. ```c GtkWidget *dialog; GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT; dialog = gtk_message_dialog_new (parent_window, flags, GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, NULL); gtk_message_dialog_set_markup (GTK_MESSAGE_DIALOG (dialog), markup); ``` Use [class@Gtk.AlertDialog] instead a new `GtkMessageDialog` transient parent flags type of message set of buttons to use printf()-style format string arguments for @message_format Sets the secondary text of the message dialog. The @message_format is assumed to contain Pango markup. Due to an oversight, this function does not escape special XML characters like [ctor@Gtk.MessageDialog.new_with_markup] does. Thus, if the arguments may contain special XML characters, you should use g_markup_printf_escaped() to escape it. ```c char *msg; msg = g_markup_printf_escaped (message_format, ...); gtk_message_dialog_format_secondary_markup (message_dialog, "%s", msg); g_free (msg); ``` Use [class@Gtk.AlertDialog] instead a `GtkMessageDialog` printf()-style string with Pango markup arguments for @message_format Sets the secondary text of the message dialog. Use [class@Gtk.AlertDialog] instead a `GtkMessageDialog` printf()-style format string arguments for @message_format Returns the message area of the dialog. This is the box where the dialog’s primary and secondary labels are packed. You can add your own extra content to that box and it will appear below those labels. See [method@Gtk.Dialog.get_content_area] for the corresponding function in the parent [class@Gtk.Dialog]. Use [class@Gtk.AlertDialog] instead A `GtkBox` corresponding to the “message area” in the @message_dialog a `GtkMessageDialog` Sets the text of the message dialog. Use [class@Gtk.AlertDialog] instead a `GtkMessageDialog` string with Pango markup Set of buttons to display on the dialog. The `GtkBox` that corresponds to the message area of this dialog. See [method@Gtk.MessageDialog.get_message_area] for a detailed description of this area. The type of the message. The secondary text of the message dialog. %TRUE if the secondary text of the dialog includes Pango markup. See [func@Pango.parse_markup]. The primary text of the message dialog. If the dialog has a secondary text, this will appear as the title. %TRUE if the primary text of the dialog includes Pango markup. See [func@Pango.parse_markup]. The type of message being displayed in a [class@MessageDialog]. Informational message Non-fatal warning message Question requiring a choice Fatal error message None of the above A `GtkShortcutAction` that calls gtk_widget_mnemonic_activate(). Gets the mnemonic action. This is an action that calls gtk_widget_mnemonic_activate() on the given widget upon activation. The mnemonic action A `GtkShortcutTrigger` that triggers when a specific mnemonic is pressed. Mnemonics require a *mnemonic modifier* (typically <kbd>Alt</kbd>) to be pressed together with the mnemonic key. Creates a `GtkShortcutTrigger` that will trigger whenever the key with the given @keyval is pressed and mnemonics have been activated. Mnemonics are activated by calling code when a key event with the right modifiers is detected. A new `GtkShortcutTrigger` The keyval to trigger for Gets the keyval that must be pressed to succeed triggering @self. the keyval a mnemonic `GtkShortcutTrigger` The key value for the trigger. `GtkMountOperation` is an implementation of `GMountOperation`. The functions and objects described here make working with GTK and GIO more convenient. `GtkMountOperation` is needed when mounting volumes: It is an implementation of `GMountOperation` that can be used with GIO functions for mounting volumes such as g_file_mount_enclosing_volume(), g_file_mount_mountable(), g_volume_mount(), g_mount_unmount_with_operation() and others. When necessary, `GtkMountOperation` shows dialogs to let the user enter passwords, ask questions or show processes blocking unmount. Creates a new `GtkMountOperation`. a new `GtkMountOperation` transient parent of the window Gets the display on which windows of the `GtkMountOperation` will be shown. the display on which windows of @op are shown a `GtkMountOperation` Gets the transient parent used by the `GtkMountOperation`. the transient parent for windows shown by @op a `GtkMountOperation` Returns whether the `GtkMountOperation` is currently displaying a window. %TRUE if @op is currently displaying a window a `GtkMountOperation` Sets the display to show windows of the `GtkMountOperation` on. a `GtkMountOperation` a `GdkDisplay` Sets the transient parent for windows shown by the `GtkMountOperation`. a `GtkMountOperation` transient parent of the window The display where dialogs will be shown. Whether a dialog is currently shown. The parent window. The parent class. Passed as argument to various keybinding signals for moving the cursor position. Move forward or back by graphemes Move left or right by graphemes Move forward or back by words Move up or down lines (wrapped lines) Move to either end of a line Move up or down paragraphs (newline-ended lines) Move to either end of a paragraph Move by pages Move to ends of the buffer Move horizontally by pages `GtkMultiFilter` is the base class for filters that combine multiple filters. Adds a @filter to @self to use for matching. a `GtkMultiFilter` A new filter to use Removes the filter at the given @position from the list of filters used by @self. If @position is larger than the number of filters, nothing happens and the function returns. a `GtkMultiFilter` position of filter to remove The type of items. See [method@Gio.ListModel.get_item_type]. The number of items. See [method@Gio.ListModel.get_n_items]. `GtkMultiSelection` is a `GtkSelectionModel` that allows selecting multiple elements. Creates a new selection to handle @model. a new `GtkMultiSelection` the `GListModel` to manage Returns the underlying model of @self. the underlying model a `GtkMultiSelection` Sets the model that @self should wrap. If @model is %NULL, @self will be empty. a `GtkMultiSelection` A `GListModel` to wrap The type of items. See [method@Gio.ListModel.get_item_type]. The list managed by this selection. The number of items. See [method@Gio.ListModel.get_n_items]. `GtkMultiSorter` combines multiple sorters by trying them in turn. If the first sorter compares two items as equal, the second is tried next, and so on. Creates a new multi sorter. This sorter compares items by trying each of the sorters in turn, until one returns non-zero. In particular, if no sorter has been added to it, it will always compare items as equal. a new `GtkMultiSorter` Add @sorter to @self to use for sorting at the end. @self will consult all existing sorters before it will sort with the given @sorter. a `GtkMultiSorter` a sorter to add Removes the sorter at the given @position from the list of sorter used by @self. If @position is larger than the number of sorters, nothing happens. a `GtkMultiSorter` position of sorter to remove The type of items. See [method@Gio.ListModel.get_item_type]. The number of items. See [method@Gio.ListModel.get_n_items]. A `GtkShortcutAction` that activates an action by name. Creates an action that when activated, activates the named action on the widget. It also passes the given arguments to it. See [method@Gtk.Widget.insert_action_group] for how to add actions to widgets. a new `GtkShortcutAction` the detailed name of the action Returns the name of the action that will be activated. the name of the action to activate a named action The name of the action to activate. `GtkNative` is the interface implemented by all widgets that have their own `GdkSurface`. The obvious example of a `GtkNative` is `GtkWindow`. Every widget that is not itself a `GtkNative` is contained in one, and you can get it with [method@Gtk.Widget.get_native]. To get the surface of a `GtkNative`, use [method@Gtk.Native.get_surface]. It is also possible to find the `GtkNative` to which a surface belongs, with [func@Gtk.Native.get_for_surface]. In addition to a [class@Gdk.Surface], a `GtkNative` also provides a [class@Gsk.Renderer] for rendering on that surface. To get the renderer, use [method@Gtk.Native.get_renderer]. Finds the `GtkNative` associated with the surface. the `GtkNative` that is associated with @surface a `GdkSurface` Returns the renderer that is used for this `GtkNative`. the renderer for @self a `GtkNative` Returns the surface of this `GtkNative`. the surface of @self a `GtkNative` Retrieves the surface transform of @self. This is the translation from @self's surface coordinates into @self's widget coordinates. a `GtkNative` return location for the x coordinate return location for the y coordinate Realizes a `GtkNative`. This should only be used by subclasses. a `GtkNative` Unrealizes a `GtkNative`. This should only be used by subclasses. a `GtkNative` Native dialogs are platform dialogs that don't use `GtkDialog`. They are used in order to integrate better with a platform, by looking the same as other native applications and supporting platform specific features. The [class@Gtk.Dialog] functions cannot be used on such objects, but we need a similar API in order to drive them. The `GtkNativeDialog` object is an API that allows you to do this. It allows you to set various common properties on the dialog, as well as show and hide it and get a [signal@Gtk.NativeDialog::response] signal when the user finished with the dialog. Note that unlike `GtkDialog`, `GtkNativeDialog` objects are not toplevel widgets, and GTK does not keep them alive. It is your responsibility to keep a reference until you are done with the object. Hides the dialog if it is visible, aborting any interaction. Once this is called the [signal@Gtk.NativeDialog::response] signal will *not* be emitted until after the next call to [method@Gtk.NativeDialog.show]. If the dialog is not visible this does nothing. a `GtkNativeDialog` class handler for the `GtkNativeDialog::response` signal Shows the dialog on the display. When the user accepts the state of the dialog the dialog will be automatically hidden and the [signal@Gtk.NativeDialog::response] signal will be emitted. Multiple calls while the dialog is visible will be ignored. a `GtkNativeDialog` Destroys a dialog. When a dialog is destroyed, it will break any references it holds to other objects. If it is visible it will be hidden and any underlying window system resources will be destroyed. Note that this does not release any reference to the object (as opposed to destroying a `GtkWindow`) because there is no reference from the windowing system to the `GtkNativeDialog`. a `GtkNativeDialog` Returns whether the dialog is modal. %TRUE if the dialog is set to be modal a `GtkNativeDialog` Gets the title of the `GtkNativeDialog`. the title of the dialog, or %NULL if none has been set explicitly. The returned string is owned by the widget and must not be modified or freed. a `GtkNativeDialog` Fetches the transient parent for this window. the transient parent for this window, or %NULL if no transient parent has been set. a `GtkNativeDialog` Determines whether the dialog is visible. %TRUE if the dialog is visible a `GtkNativeDialog` Hides the dialog if it is visible, aborting any interaction. Once this is called the [signal@Gtk.NativeDialog::response] signal will *not* be emitted until after the next call to [method@Gtk.NativeDialog.show]. If the dialog is not visible this does nothing. a `GtkNativeDialog` Sets a dialog modal or non-modal. Modal dialogs prevent interaction with other windows in the same application. To keep modal dialogs on top of main application windows, use [method@Gtk.NativeDialog.set_transient_for] to make the dialog transient for the parent; most window managers will then disallow lowering the dialog below the parent. a `GtkNativeDialog` whether the window is modal Sets the title of the `GtkNativeDialog.` a `GtkNativeDialog` title of the dialog Dialog windows should be set transient for the main application window they were spawned from. This allows window managers to e.g. keep the dialog on top of the main window, or center the dialog over the main window. Passing %NULL for @parent unsets the current transient window. a `GtkNativeDialog` parent window Shows the dialog on the display. When the user accepts the state of the dialog the dialog will be automatically hidden and the [signal@Gtk.NativeDialog::response] signal will be emitted. Multiple calls while the dialog is visible will be ignored. a `GtkNativeDialog` Whether the window should be modal with respect to its transient parent. The title of the dialog window The transient parent of the dialog, or %NULL for none. Whether the window is currently visible. Emitted when the user responds to the dialog. When this is called the dialog has been hidden. If you call [method@Gtk.NativeDialog.hide] before the user responds to the dialog this signal will not be emitted. the response ID Class structure for `GtkNativeDialog`. class handler for the `GtkNativeDialog::response` signal a `GtkNativeDialog` a `GtkNativeDialog` Options for selecting a different wrap mode for natural size requests. See for example the [property@Gtk.Label:natural-wrap-mode] property. Inherit the minimum size request. In particular, this should be used with %PANGO_WRAP_CHAR. Try not to wrap the text. This mode is the closest to GTK3's behavior but can lead to a wide label leaving lots of empty space below the text. Attempt to wrap at word boundaries. This is useful in particular when using %PANGO_WRAP_WORD_CHAR as the wrap mode. A `GtkShortcutTrigger` that never triggers. Gets the never trigger. This is a singleton for a trigger that never triggers. Use this trigger instead of %NULL because it implements all virtual functions. The never trigger `GtkNoSelection` is a `GtkSelectionModel` that does not allow selecting anything. This model is meant to be used as a simple wrapper around a `GListModel` when a `GtkSelectionModel` is required. `GtkNoSelection` passes through sections from the underlying model. Creates a new selection to handle @model. a new `GtkNoSelection` the `GListModel` to manage Gets the model that @self is wrapping. The model being wrapped a `GtkNoSelection` Sets the model that @self should wrap. If @model is %NULL, this model will be empty. a `GtkNoSelection` A `GListModel` to wrap The type of items. See [method@Gio.ListModel.get_item_type]. The model being managed. The number of items. See [method@Gio.ListModel.get_n_items]. `GtkNotebook` is a container whose children are pages switched between using tabs.  There are many configuration options for `GtkNotebook`. Among other things, you can choose on which edge the tabs appear (see [method@Gtk.Notebook.set_tab_pos]), whether, if there are too many tabs to fit the notebook should be made bigger or scrolling arrows added (see [method@Gtk.Notebook.set_scrollable]), and whether there will be a popup menu allowing the users to switch pages. (see [method@Gtk.Notebook.popup_enable]). # GtkNotebook as GtkBuildable The `GtkNotebook` implementation of the `GtkBuildable` interface supports placing children into tabs by specifying “tab” as the “type” attribute of a `<child>` element. Note that the content of the tab must be created before the tab can be filled. A tab child can be specified without specifying a `<child>` type attribute. To add a child widget in the notebooks action area, specify "action-start" or “action-end” as the “type” attribute of the `<child>` element. An example of a UI definition fragment with `GtkNotebook`: ```xml <object class="GtkNotebook"> <child> <object class="GtkLabel" id="notebook-content"> <property name="label">Content</property> </object> </child> <child type="tab"> <object class="GtkLabel" id="notebook-tab"> <property name="label">Tab</property> </object> </child> </object> ``` # Shortcuts and Gestures `GtkNotebook` supports the following keyboard shortcuts: - <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. - <kbd>Home</kbd> moves the focus to the first tab. - <kbd>End</kbd> moves the focus to the last tab. Additionally, the following signals have default keybindings: - [signal@Gtk.Notebook::change-current-page] - [signal@Gtk.Notebook::focus-tab] - [signal@Gtk.Notebook::move-focus-out] - [signal@Gtk.Notebook::reorder-tab] - [signal@Gtk.Notebook::select-page] Tabs support drag-and-drop between notebooks sharing the same `group-name`, or to new windows by handling the `::create-window` signal. # Actions `GtkNotebook` defines a set of built-in actions: - `menu.popup` opens the tabs context menu. # CSS nodes ``` notebook ├── header.top │ ├── [<action widget>] │ ├── tabs │ │ ├── [arrow] │ │ ├── tab │ │ │ ╰── <tab label> ┊ ┊ ┊ │ │ ├── tab[.reorderable-page] │ │ │ ╰── <tab label> │ │ ╰── [arrow] │ ╰── [<action widget>] │ ╰── stack ├── <child> ┊ ╰── <child> ``` `GtkNotebook` has a main CSS node with name `notebook`, a subnode with name `header` and below that a subnode with name `tabs` which contains one subnode per tab with name `tab`. If action widgets are present, their CSS nodes are placed next to the `tabs` node. If the notebook is scrollable, CSS nodes with name `arrow` are placed as first and last child of the `tabs` node. The main node gets the `.frame` style class when the notebook has a border (see [method@Gtk.Notebook.set_show_border]). The header node gets one of the style class `.top`, `.bottom`, `.left` or `.right`, depending on where the tabs are placed. For reorderable pages, the tab node gets the `.reorderable-page` class. A `tab` node gets the `.dnd` style class while it is moved with drag-and-drop. The nodes are always arranged from left-to-right, regardless of text direction. # Accessibility `GtkNotebook` uses the following roles: - %GTK_ACCESSIBLE_ROLE_GROUP for the notebook widget - %GTK_ACCESSIBLE_ROLE_TAB_LIST for the list of tabs - %GTK_ACCESSIBLE_ROLE_TAB role for each tab - %GTK_ACCESSIBLE_ROLE_TAB_PANEL for each page Creates a new `GtkNotebook` widget with no pages. the newly created `GtkNotebook` Appends a page to @notebook. the index (starting from 0) of the appended page in the notebook, or -1 if function fails a `GtkNotebook` the `GtkWidget` to use as the contents of the page the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” Appends a page to @notebook, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the appended page in the notebook, or -1 if function fails a `GtkNotebook` the `GtkWidget` to use as the contents of the page the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a `GtkLabel` or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label is not a `GtkLabel`, @menu_label must be specified if the page-switch menu is to be used. Removes the child from the notebook. This function is very similar to [method@Gtk.Notebook.remove_page], but additionally informs the notebook that the removal is happening as part of a tab DND operation, which should not be cancelled. a `GtkNotebook` a child Gets one of the action widgets. See [method@Gtk.Notebook.set_action_widget]. The action widget with the given @pack_type or %NULL when this action widget has not been set a `GtkNotebook` pack type of the action widget to receive Returns the page number of the current page. the index (starting from 0) of the current page in the notebook. If the notebook has no pages, then -1 will be returned. a `GtkNotebook` Gets the current group name for @notebook. the group name, or %NULL if none is set a `GtkNotebook` Retrieves the menu label widget of the page containing @child. the menu label, or %NULL if the notebook page does not have a menu label other than the default (the tab label). a `GtkNotebook` a widget contained in a page of @notebook Retrieves the text of the menu label for the page containing @child. the text of the tab label, or %NULL if the widget does not have a menu label other than the default menu label, or the menu label widget is not a `GtkLabel`. The string is owned by the widget and must not be freed. a `GtkNotebook` the child widget of a page of the notebook. Gets the number of pages in a notebook. the number of pages in the notebook a `GtkNotebook` Returns the child widget contained in page number @page_num. the child widget, or %NULL if @page_num is out of bounds a `GtkNotebook` the index of a page in the notebook, or -1 to get the last page Returns the `GtkNotebookPage` for @child. the `GtkNotebookPage` for @child a `GtkNotebook` a child of @notebook Returns a `GListModel` that contains the pages of the notebook. This can be used to keep an up-to-date view. The model also implements [iface@Gtk.SelectionModel] and can be used to track and modify the visible page. a `GListModel` for the notebook's children a `GtkNotebook` Returns whether the tab label area has arrows for scrolling. %TRUE if arrows for scrolling are present a `GtkNotebook` Returns whether a bevel will be drawn around the notebook pages. %TRUE if the bevel is drawn a `GtkNotebook` Returns whether the tabs of the notebook are shown. %TRUE if the tabs are shown a `GtkNotebook` Returns whether the tab contents can be detached from @notebook. %TRUE if the tab is detachable. a `GtkNotebook` a child `GtkWidget` Returns the tab label widget for the page @child. %NULL is returned if @child is not in @notebook or if no tab label has specifically been set for @child. the tab label a `GtkNotebook` the page Retrieves the text of the tab label for the page containing @child. the text of the tab label, or %NULL if the tab label widget is not a `GtkLabel`. The string is owned by the widget and must not be freed. a `GtkNotebook` a widget contained in a page of @notebook Gets the edge at which the tabs are drawn. the edge at which the tabs are drawn a `GtkNotebook` Gets whether the tab can be reordered via drag and drop or not. %TRUE if the tab is reorderable. a `GtkNotebook` a child `GtkWidget` Insert a page into @notebook at the given position. the index (starting from 0) of the inserted page in the notebook, or -1 if function fails a `GtkNotebook` the `GtkWidget` to use as the contents of the page the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages Insert a page into @notebook at the given position, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the inserted page in the notebook a `GtkNotebook` the `GtkWidget` to use as the contents of the page the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a `GtkLabel` or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label is not a `GtkLabel`, @menu_label must be specified if the page-switch menu is to be used. the index (starting at 0) at which to insert the page, or -1 to append the page after all other pages. Switches to the next page. Nothing happens if the current page is the last page. a `GtkNotebook` Finds the index of the page which contains the given child widget. the index of the page containing @child, or -1 if @child is not in the notebook a `GtkNotebook` a `GtkWidget` Disables the popup menu. a `GtkNotebook` Enables the popup menu. If the user clicks with the right mouse button on the tab labels, a menu with all the pages will be popped up. a `GtkNotebook` Prepends a page to @notebook. the index (starting from 0) of the prepended page in the notebook, or -1 if function fails a `GtkNotebook` the `GtkWidget` to use as the contents of the page the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” Prepends a page to @notebook, specifying the widget to use as the label in the popup menu. the index (starting from 0) of the prepended page in the notebook, or -1 if function fails a `GtkNotebook` the `GtkWidget` to use as the contents of the page the `GtkWidget` to be used as the label for the page, or %NULL to use the default label, “page N” the widget to use as a label for the page-switch menu, if that is enabled. If %NULL, and @tab_label is a `GtkLabel` or %NULL, then the menu label will be a newly created label with the same text as @tab_label; if @tab_label is not a `GtkLabel`, @menu_label must be specified if the page-switch menu is to be used. Switches to the previous page. Nothing happens if the current page is the first page. a `GtkNotebook` Removes a page from the notebook given its index in the notebook. a `GtkNotebook` the index of a notebook page, starting from 0. If -1, the last page will be removed. Reorders the page containing @child, so that it appears in position @position. If @position is greater than or equal to the number of children in the list or negative, @child will be moved to the end of the list. a `GtkNotebook` the child to move the new position, or -1 to move to the end Sets @widget as one of the action widgets. Depending on the pack type the widget will be placed before or after the tabs. You can use a `GtkBox` if you need to pack more than one widget on the same side. a `GtkNotebook` a `GtkWidget` pack type of the action widget Switches to the page number @page_num. Note that due to historical reasons, GtkNotebook refuses to switch to a page unless the child widget is visible. Therefore, it is recommended to show child widgets before adding them to a notebook. a `GtkNotebook` 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 notebook, nothing will be done. Sets a group name for @notebook. Notebooks with the same name will be able to exchange tabs via drag and drop. A notebook with a %NULL group name will not be able to exchange tabs with any other notebook. a `GtkNotebook` the name of the notebook group, or %NULL to unset it Changes the menu label for the page containing @child. a `GtkNotebook` the child widget the menu label, or %NULL for default Creates a new label and sets it as the menu label of @child. a `GtkNotebook` the child widget the label text Sets whether the tab label area will have arrows for scrolling if there are too many tabs to fit in the area. a `GtkNotebook` %TRUE if scroll arrows should be added Sets whether a bevel will be drawn around the notebook pages. This only has a visual effect when the tabs are not shown. a `GtkNotebook` %TRUE if a bevel should be drawn around the notebook Sets whether to show the tabs for the notebook or not. a `GtkNotebook` %TRUE if the tabs should be shown Sets whether the tab can be detached from @notebook to another notebook or widget. Note that two notebooks must share a common group identifier (see [method@Gtk.Notebook.set_group_name]) to allow automatic tabs interchange between them. If you want a widget to interact with a notebook through DnD (i.e.: accept dragged tabs from it) it must be set as a drop destination by adding to it a [class@Gtk.DropTarget] controller that accepts the GType `GTK_TYPE_NOTEBOOK_PAGE`. The `:value` of said drop target will be preloaded with a [class@Gtk.NotebookPage] object that corresponds to the dropped tab, so you can process the value via `::accept` or `::drop` signals. Note that you should use [method@Gtk.Notebook.detach_tab] instead of [method@Gtk.Notebook.remove_page] if you want to remove the tab from the source notebook as part of accepting a drop. Otherwise, the source notebook will think that the dragged tab was removed from underneath the ongoing drag operation, and will initiate a drag cancel animation. ```c static void on_drag_data_received (GtkWidget *widget, GdkDrop *drop, GtkSelectionData *data, guint time, gpointer user_data) { GtkDrag *drag; GtkWidget *notebook; GtkWidget **child; drag = gtk_drop_get_drag (drop); notebook = g_object_get_data (drag, "gtk-notebook-drag-origin"); child = (void*) gtk_selection_data_get_data (data); // process_widget (*child); gtk_notebook_detach_tab (GTK_NOTEBOOK (notebook), *child); } ``` If you want a notebook to accept drags from other widgets, you will have to set your own DnD code to do it. a `GtkNotebook` a child `GtkWidget` whether the tab is detachable or not Changes the tab label for @child. If %NULL is specified for @tab_label, then the page will have the label “page N”. a `GtkNotebook` the page the tab label widget to use, or %NULL for default tab label Creates a new label and sets it as the tab label for the page containing @child. a `GtkNotebook` the page the label text Sets the edge at which the tabs are drawn. a `GtkNotebook`. the edge to draw the tabs at Sets whether the notebook tab can be reordered via drag and drop or not. a `GtkNotebook` a child `GtkWidget` whether the tab is reorderable or not If %TRUE, pressing the right mouse button on the notebook shows a page switching menu. Group name for tab drag and drop. The index of the current page. A selection model with the pages. If %TRUE, scroll arrows are added if there are too many pages to fit. Whether the border should be shown. Whether tabs should be shown. Which side of the notebook holds the tabs. Emitted when the current page should be changed. The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>PgUp</kbd>, <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>PgDn</kbd>, <kbd>Ctrl</kbd>+<kbd>PgUp</kbd> and <kbd>Ctrl</kbd>+<kbd>PgDn</kbd>. whether the page was changed the page index The ::create-window signal is emitted when a detachable tab is dropped on the root window. A handler for this signal can create a window containing a notebook where the tab will be attached. It is also responsible for moving/resizing the window and adding the necessary properties to the notebook (e.g. the `GtkNotebook`:group-name ). a `GtkNotebook` that @page should be added to the tab of @notebook that is being detached Emitted when a tab should be focused. whether the tab has been focused the notebook tab Emitted when focus was moved out. The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>Tab</kbd>, <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Tab</kbd>, <kbd>Ctrl</kbd>+<kbd>←</kbd>, <kbd>Ctrl</kbd>+<kbd>→</kbd>, <kbd>Ctrl</kbd>+<kbd>↑</kbd> and <kbd>Ctrl</kbd>+<kbd>↓</kbd>. the direction to move the focus the ::page-added signal is emitted in the notebook right after a page is added to the notebook. the child `GtkWidget` affected the new page number for @child the ::page-removed signal is emitted in the notebook right after a page is removed from the notebook. the child `GtkWidget` affected the @child page number the ::page-reordered signal is emitted in the notebook right after a page has been reordered. the child `GtkWidget` affected the new page number for @child Emitted when the tab should be reordered. The default bindings for this signal are <kbd>Alt</kbd>+<kbd>Home</kbd>, <kbd>Alt</kbd>+<kbd>End</kbd>, <kbd>Alt</kbd>+<kbd>PgUp</kbd>, <kbd>Alt</kbd>+<kbd>PgDn</kbd>, <kbd>Alt</kbd>+<kbd>←</kbd>, <kbd>Alt</kbd>+<kbd>→</kbd>, <kbd>Alt</kbd>+<kbd>↑</kbd> and <kbd>Alt</kbd>+<kbd>↓</kbd>. whether the tab was moved. the direction to move the tab whether to move to the last position Emitted when a page should be selected. The default binding for this signal is <kbd>␣</kbd>. whether the page was selected whether to move focus Emitted when the user or a function changes the current page. the new current page the index of the page `GtkNotebookPage` is an auxiliary object used by `GtkNotebook`. Returns the notebook child to which @page belongs. the child to which @page belongs a `GtkNotebookPage` The child for this page. Whether the tab is detachable. The label widget displayed in the child's menu entry. The text of the menu widget. The index of the child in the parent. Whether the tab is reorderable by user action. The tab widget for this page. Whether to expand the child's tab. Whether the child's tab should fill the allocated area. The text of the tab widget. The parameter used in the action signals of `GtkNotebook`. the first tab in the notebook the last tab in the notebook A `GtkShortcutAction` that does nothing. Gets the nothing action. This is an action that does nothing and where activating it always fails. The nothing action Used to determine the layout of pages on a sheet when printing multiple pages per sheet.         `GtkNumericSorter` is a `GtkSorter` that compares numbers. To obtain the numbers to compare, this sorter evaluates a [class@Gtk.Expression]. Creates a new numeric sorter using the given @expression. Smaller numbers will be sorted first. You can call [method@Gtk.NumericSorter.set_sort_order] to change this. a new `GtkNumericSorter` The expression to evaluate Gets the expression that is evaluated to obtain numbers from items. a `GtkExpression` a `GtkNumericSorter` Gets whether this sorter will sort smaller numbers first. the order of the numbers a `GtkNumericSorter` Sets the expression that is evaluated to obtain numbers from items. Unless an expression is set on @self, the sorter will always compare items as invalid. The expression must have a return type that can be compared numerically, such as %G_TYPE_INT or %G_TYPE_DOUBLE. a `GtkNumericSorter` a `GtkExpression` Sets whether to sort smaller numbers before larger ones. a `GtkNumericSorter` whether to sort smaller numbers first The expression to evaluate on items to get a number to compare with. Whether the sorter will sort smaller numbers first. A `GObject` value in a `GtkExpression`. Creates an expression evaluating to the given `object` with a weak reference. Once the `object` is disposed, it will fail to evaluate. This expression is meant to break reference cycles. If you want to keep a reference to `object`, use [ctor@Gtk.ConstantExpression.new]. a new `GtkExpression` object to watch Gets the object that the expression evaluates to. the object, or `NULL` an object `GtkExpression` Describes the way two values can be compared. These values can be used with a [callback@GLib.CompareFunc]. However, a `GCompareFunc` is allowed to return any integer values. For converting such a value to a `GtkOrdering` value, use [func@Gtk.Ordering.from_cmpfunc]. the first value is smaller than the second the two values are equal the first value is larger than the second Converts the result of a `GCompareFunc` like strcmp() to a `GtkOrdering` value. the corresponding `GtkOrdering` Result of a comparison function The `GtkOrientable` interface is implemented by all widgets that can be oriented horizontally or vertically. `GtkOrientable` is more flexible in that it allows the orientation to be changed at runtime, allowing the widgets to “flip”. ## CSS nodes `GtkWidget` types implementing the `GtkOrientable` interface will automatically acquire the `horizontal` or `vertical` CSS class depending on the value of the [property@Gtk.Orientable:orientation] property. Retrieves the orientation of the @orientable. the orientation of the @orientable a `GtkOrientable` Sets the orientation of the @orientable. a `GtkOrientable` the orientable’s new orientation The orientation of the orientable. Represents the orientation of widgets and other objects. Typical examples are [class@Box] or [class@GesturePan]. The element is in horizontal orientation. The element is in vertical orientation. Defines how content overflowing a given area should be handled. This is used in [method@Gtk.Widget.set_overflow]. The [property@Gtk.Widget:overflow] property is modeled after the CSS overflow property, but implements it only partially. No change is applied. Content is drawn at the specified position. Content is clipped to the bounds of the area. Content outside the area is not drawn and cannot be interacted with. `GtkOverlay` is a container which contains a single main child, on top of which it can place “overlay” widgets.  The position of each overlay widget is determined by its [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties. E.g. a widget with both alignments set to %GTK_ALIGN_START will be placed at the top left corner of the `GtkOverlay` container, whereas an overlay with halign set to %GTK_ALIGN_CENTER and valign set to %GTK_ALIGN_END will be placed a the bottom edge of the `GtkOverlay`, horizontally centered. The position can be adjusted by setting the margin properties of the child to non-zero values. More complicated placement of overlays is possible by connecting to the [signal@Gtk.Overlay::get-child-position] signal. An overlay’s minimum and natural sizes are those of its main child. The sizes of overlay children are not considered when measuring these preferred sizes. # GtkOverlay as GtkBuildable The `GtkOverlay` implementation of the `GtkBuildable` interface supports placing a child as an overlay by specifying “overlay” as the “type” attribute of a `<child>` element. # CSS nodes `GtkOverlay` has a single CSS node with the name “overlay”. Overlay children whose alignments cause them to be positioned at an edge get the style classes “.left”, “.right”, “.top”, and/or “.bottom” according to their position. Creates a new `GtkOverlay`. a new `GtkOverlay` object. Adds @widget to @overlay. The widget will be stacked on top of the main widget added with [method@Gtk.Overlay.set_child]. The position at which @widget is placed is determined from its [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties. a `GtkOverlay` a `GtkWidget` to be added to the container Gets the child widget of @overlay. the child widget of @overlay a `GtkOverlay` Gets whether @widget should be clipped within the parent. whether the widget is clipped within the parent. a `GtkOverlay` an overlay child of `GtkOverlay` Gets whether @widget's size is included in the measurement of @overlay. whether the widget is measured a `GtkOverlay` an overlay child of `GtkOverlay` Removes an overlay that was added with gtk_overlay_add_overlay(). a `GtkOverlay` a `GtkWidget` to be removed Sets the child widget of @overlay. a `GtkOverlay` the child widget Sets whether @widget should be clipped within the parent. a `GtkOverlay` an overlay child of `GtkOverlay` whether the child should be clipped Sets whether @widget is included in the measured size of @overlay. The overlay will request the size of the largest child that has this property set to %TRUE. Children who are not included may be drawn outside of @overlay's allocation if they are too large. a `GtkOverlay` an overlay child of `GtkOverlay` whether the child should be measured The main child widget. Emitted to determine the position and size of any overlay child widgets. A handler for this signal should fill @allocation with the desired position and size for @widget, relative to the 'main' child of @overlay. The default handler for this signal uses the @widget's halign and valign properties to determine the position and gives the widget its natural size (except that an alignment of %GTK_ALIGN_FILL will cause the overlay to be full-width/height). If the main child is a `GtkScrolledWindow`, the overlays are placed relative to its contents. %TRUE if the @allocation has been filled the child widget to position return location for the allocation `GtkOverlayLayout` is the layout manager used by [class@Gtk.Overlay]. It places widgets as overlays on top of the main child. This is not a reusable layout manager, since it expects its widget to be a `GtkOverlay`. It is only listed here so that its layout properties get documented. Creates a new `GtkOverlayLayout` instance. the newly created instance `GtkLayoutChild` subclass for children in a `GtkOverlayLayout`. Retrieves whether the child is clipped. whether the child is clipped a `GtkOverlayLayoutChild` Retrieves whether the child is measured. whether the child is measured a `GtkOverlayLayoutChild` Sets whether to clip this child. a `GtkOverlayLayoutChild` whether to clip this child Sets whether to measure this child. a `GtkOverlayLayoutChild` whether to measure this child Whether the child should be clipped to fit the parent's size. Whether the child size should contribute to the `GtkOverlayLayout`'s measurement. Name for the A3 paper size. Name for the A4 paper size. Name for the A5 paper size. Name for the B5 paper size. Name for the Executive paper size. Name for the Legal paper size. Name for the Letter paper size. The key used by the “Print to file” printer to store whether to collate the printed pages. The key used by the “Print to file” printer to store the default source. The key used by the “Print to file” printer to store the dither used. The key used by the “Print to file” printer to store whether to print the output in duplex. The key used by the “Print to file” printer to store the finishings. The key used by the “Print to file” printer to store the media type. The set of media types is defined in PWG 5101.1-2002 PWG. The key used by the “Print to file” printer to store the number of pages per sheet. The key used by the “Print to file” printer to store the number of pages per sheet in number-up mode. The key used by the “Print to file” printer to store the number of copies. The key used by the “Print to file” printer to store the orientation. The key used by the “Print to file” printer to store the file name of the output without the path to the directory and the file extension. The key used by the “Print to file” printer to store the output bin. The key used by the “Print to file” printer to store the directory to which the output should be written. The key used by the “Print to file” printer to store the format of the output. The supported values are “PS” and “PDF”. The key used by the “Print to file” printer to store the URI to which the output should be written. GTK itself supports only “file://” URIs. The key used by the “Print to file” printer to store the array of page ranges to print. The key used by the “Print to file” printer to store the set of pages to print. The key used by the “Print to file” printer to store the page format. The key used by the “Print to file” printer to store the page height. The key used by the “Print to file” printer to store the paper width. The key used by the “Print to file” printer to store the printer name. The key used by the “Print to file” printer to store the resolution in lines per inch. The key used by the “Print to file” printer to store which pages to print. The key used by the “Print to file” printer to store the printing quality. The key used by the “Print to file” printer to store the resolution in DPI. The key used by the “Print to file” printer to store the horizontal resolution in DPI. The key used by the “Print to file” printer to store the vertical resolution in DPI. The key used by the “Print to file” printer to store whether to reverse the order of the printed pages. The key used by the “Print to file” printer to store the scale. The key used by the “Print to file” printer to store whether to print with colors. The key used by the “Print to file” printer to store 32-bit Windows extra driver. The key used by the “Print to file” printer to store the 32-bit Windows driver version. Use this priority for functionality related to size allocation. It is used internally by GTK+ to compute the sizes of widgets. This priority is higher than %GDK_PRIORITY_REDRAW to avoid resizing a widget which was just redrawn. Represents the packing location of a children in its parent. See [class@WindowControls] for example. The child is packed into the start of the widget The child is packed into the end of the widget Struct defining a pad action entry. the type of pad feature that will trigger this action entry. the 0-indexed button/ring/strip number that will trigger this action entry. the mode that will trigger this action entry, or -1 for all modes. Human readable description of this action entry, this string should be deemed user-visible. action name that will be activated in the `GActionGroup`. The type of a pad action. Action is triggered by a pad button Action is triggered by a pad ring Action is triggered by a pad strip `GtkPadController` is an event controller for the pads found in drawing tablets. Pads are the collection of buttons and tactile sensors often found around the stylus-sensitive area. These buttons and sensors have no implicit meaning, and by default they perform no action. `GtkPadController` is provided to map those to [iface@Gio.Action] objects, thus letting the application give them a more semantic meaning. Buttons and sensors are not constrained to triggering a single action, some %GDK_SOURCE_TABLET_PAD devices feature multiple "modes". All these input elements have one current mode, which may determine the final action being triggered. Pad devices often divide buttons and sensors into groups. All elements in a group share the same current mode, but different groups may have different modes. See [method@Gdk.DevicePad.get_n_groups] and [method@Gdk.DevicePad.get_group_n_modes]. Each of the actions that a given button/strip/ring performs for a given mode is defined by a [struct@Gtk.PadActionEntry]. It contains an action name that will be looked up in the given [iface@Gio.ActionGroup] and activated whenever the specified input element and mode are triggered. A simple example of `GtkPadController` usage: Assigning button 1 in all modes and pad devices to an "invert-selection" action: ```c GtkPadActionEntry *pad_actions[] = { { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection", "pad-actions.invert-selection" }, … }; … action_group = g_simple_action_group_new (); action = g_simple_action_new ("pad-actions.invert-selection", NULL); g_signal_connect (action, "activate", on_invert_selection_activated, NULL); g_action_map_add_action (G_ACTION_MAP (action_group), action); … pad_controller = gtk_pad_controller_new (action_group, NULL); ``` The actions belonging to rings/strips will be activated with a parameter of type %G_VARIANT_TYPE_DOUBLE bearing the value of the given axis, it is required that those are made stateful and accepting this `GVariantType`. Creates a new `GtkPadController` that will associate events from @pad to actions. A %NULL pad may be provided so the controller manages all pad devices generically, it is discouraged to mix `GtkPadController` objects with %NULL and non-%NULL @pad argument on the same toplevel window, as execution order is not guaranteed. The `GtkPadController` is created with no mapped actions. In order to map pad events to actions, use [method@Gtk.PadController.set_action_entries] or [method@Gtk.PadController.set_action]. Be aware that pad events will only be delivered to `GtkWindow`s, so adding a pad controller to any other type of widget will not have an effect. A newly created `GtkPadController` `GActionGroup` to trigger actions from A %GDK_SOURCE_TABLET_PAD device, or %NULL to handle all pads Adds an individual action to @controller. This action will only be activated if the given button/ring/strip number in @index is interacted while the current mode is @mode. -1 may be used for simple cases, so the action is triggered on all modes. The given @label should be considered user-visible, so internationalization rules apply. Some windowing systems may be able to use those for user feedback. a `GtkPadController` the type of pad feature that will trigger this action the 0-indexed button/ring/strip number that will trigger this action the mode that will trigger this action, or -1 for all modes. Human readable description of this action, this string should be deemed user-visible. action name that will be activated in the `GActionGroup` A convenience function to add a group of action entries on @controller. See [struct@Gtk.PadActionEntry] and [method@Gtk.PadController.set_action]. a `GtkPadController` the action entries to set on @controller the number of elements in @entries The action group of the controller. The pad of the controller. See also gtk_print_settings_set_orientation(). Portrait mode. Landscape mode. Reverse portrait mode. Reverse landscape mode. A range of pages to print. See also [method@Gtk.PrintSettings.set_page_ranges]. start of page range. end of page range. See also gtk_print_job_set_page_set(). All pages. Even pages. Odd pages. A `GtkPageSetup` object stores the page size, orientation and margins. The idea is that you can get one of these from the page setup dialog and then pass it to the `GtkPrintOperation` when printing. The benefit of splitting this out of the `GtkPrintSettings` is that these affect the actual layout of the page, and thus need to be set long before user prints. ## Margins The margins specified in this object are the “print margins”, i.e. the parts of the page that the printer cannot print on. These are different from the layout margins that a word processor uses; they are typically used to determine the minimal size for the layout margins. To obtain a `GtkPageSetup` use [ctor@Gtk.PageSetup.new] to get the defaults, or use [func@Gtk.print_run_page_setup_dialog] to show the page setup dialog and receive the resulting page setup. ## A page setup dialog ```c static GtkPrintSettings *settings = NULL; static GtkPageSetup *page_setup = NULL; static void do_page_setup (void) { GtkPageSetup *new_page_setup; if (settings == NULL) settings = gtk_print_settings_new (); new_page_setup = gtk_print_run_page_setup_dialog (GTK_WINDOW (main_window), page_setup, settings); if (page_setup) g_object_unref (page_setup); page_setup = new_page_setup; } ``` Creates a new `GtkPageSetup`. a new `GtkPageSetup`. Reads the page setup from the file @file_name. Returns a new `GtkPageSetup` object with the restored page setup, or %NULL if an error occurred. See [method@Gtk.PageSetup.to_file]. the restored `GtkPageSetup` the filename to read the page setup from Desrialize a page setup from an a{sv} variant. The variant must be in the format produced by [method@Gtk.PageSetup.to_gvariant]. a new `GtkPageSetup` object an a{sv} `GVariant` Reads the page setup from the group @group_name in the key file @key_file. Returns a new `GtkPageSetup` object with the restored page setup, or %NULL if an error occurred. the restored `GtkPageSetup` the `GKeyFile` to retrieve the page_setup from the name of the group in the key_file to read to use the default name “Page Setup” Copies a `GtkPageSetup`. a copy of @other the `GtkPageSetup` to copy Gets the bottom margin in units of @unit. the bottom margin a `GtkPageSetup` the unit for the return value Gets the left margin in units of @unit. the left margin a `GtkPageSetup` the unit for the return value Gets the page orientation of the `GtkPageSetup`. the page orientation a `GtkPageSetup` Returns the page height in units of @unit. Note that this function takes orientation and margins into consideration. See [method@Gtk.PageSetup.get_paper_height]. the page height. a `GtkPageSetup` the unit for the return value Returns the page width in units of @unit. Note that this function takes orientation and margins into consideration. See [method@Gtk.PageSetup.get_paper_width]. the page width. a `GtkPageSetup` the unit for the return value Returns the paper height in units of @unit. Note that this function takes orientation, but not margins into consideration. See [method@Gtk.PageSetup.get_page_height]. the paper height. a `GtkPageSetup` the unit for the return value Gets the paper size of the `GtkPageSetup`. the paper size a `GtkPageSetup` Returns the paper width in units of @unit. Note that this function takes orientation, but not margins into consideration. See [method@Gtk.PageSetup.get_page_width]. the paper width. a `GtkPageSetup` the unit for the return value Gets the right margin in units of @unit. the right margin a `GtkPageSetup` the unit for the return value Gets the top margin in units of @unit. the top margin a `GtkPageSetup` the unit for the return value Reads the page setup from the file @file_name. See [method@Gtk.PageSetup.to_file]. %TRUE on success a `GtkPageSetup` the filename to read the page setup from Reads the page setup from the group @group_name in the key file @key_file. %TRUE on success a `GtkPageSetup` the `GKeyFile` to retrieve the page_setup from the name of the group in the key_file to read to use the default name “Page Setup” Sets the bottom margin of the `GtkPageSetup`. a `GtkPageSetup` the new bottom margin in units of @unit the units for @margin Sets the left margin of the `GtkPageSetup`. a `GtkPageSetup` the new left margin in units of @unit the units for @margin Sets the page orientation of the `GtkPageSetup`. a `GtkPageSetup` a `GtkPageOrientation` value Sets the paper size of the `GtkPageSetup` without changing the margins. See [method@Gtk.PageSetup.set_paper_size_and_default_margins]. a `GtkPageSetup` a `GtkPaperSize` Sets the paper size of the `GtkPageSetup` and modifies the margins according to the new paper size. a `GtkPageSetup` a `GtkPaperSize` Sets the right margin of the `GtkPageSetup`. a `GtkPageSetup` the new right margin in units of @unit the units for @margin Sets the top margin of the `GtkPageSetup`. a `GtkPageSetup` the new top margin in units of @unit the units for @margin This function saves the information from @setup to @file_name. %TRUE on success a `GtkPageSetup` the file to save to Serialize page setup to an a{sv} variant. a new, floating, `GVariant` a `GtkPageSetup` This function adds the page setup from @setup to @key_file. a `GtkPageSetup` the `GKeyFile` to save the page setup to the group to add the settings to in @key_file, or %NULL to use the default name “Page Setup” The type of function that is passed to gtk_print_run_page_setup_dialog_async(). This function will be called when the page setup dialog is dismissed, and also serves as destroy notify for @data. the `GtkPageSetup` that has been passed to gtk_print_run_page_setup_dialog_async() user data that has been passed to gtk_print_run_page_setup_dialog_async() `GtkPageSetupUnixDialog` implements a page setup dialog for platforms which don’t provide a native page setup dialog, like Unix.  It can be used very much like any other GTK dialog, at the cost of the portability offered by the high-level printing API in [class@Gtk.PrintOperation]. ## CSS nodes `GtkPageSetupUnixDialog` has a single CSS node with the name `window` and style class `.pagesetup`. Creates a new page setup dialog. the new `GtkPageSetupUnixDialog` the title of the dialog transient parent of the dialog Gets the currently selected page setup from the dialog. the current page setup a `GtkPageSetupUnixDialog` Gets the current print settings from the dialog. the current print settings a `GtkPageSetupUnixDialog` Sets the `GtkPageSetup` from which the page setup dialog takes its values. a `GtkPageSetupUnixDialog` a `GtkPageSetup` Sets the `GtkPrintSettings` from which the page setup dialog takes its values. a `GtkPageSetupUnixDialog` a `GtkPrintSettings` Describes the panning direction of a [class@GesturePan]. panned towards the left panned towards the right panned upwards panned downwards A widget with two panes, arranged either horizontally or vertically.  The division between the two panes is adjustable by the user by dragging a handle. Child widgets are added to the panes of the widget with [method@Gtk.Paned.set_start_child] and [method@Gtk.Paned.set_end_child]. The division between the two children is set by default from the size requests of the children, but it can be adjusted by the user. A paned widget draws a separator between the two child widgets and a small handle that the user can drag to adjust the division. It does not draw any relief around the children or around the separator. (The space in which the separator is called the gutter.) Often, it is useful to put each child inside a [class@Gtk.Frame] so that the gutter appears as a ridge. No separator is drawn if one of the children is missing. Each child has two options that can be set, "resize" and "shrink". If "resize" is true then, when the `GtkPaned` is resized, that child will expand or shrink along with the paned widget. If "shrink" is true, then that child can be made smaller than its requisition by the user. Setting "shrink" to false allows the application to set a minimum size. If "resize" is false for both children, then this is treated as if "resize" is true for both children. The application can set the position of the slider as if it were set by the user, by calling [method@Gtk.Paned.set_position]. # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.Paned::accept-position] - [signal@Gtk.Paned::cancel-position] - [signal@Gtk.Paned::cycle-child-focus] - [signal@Gtk.Paned::cycle-handle-focus] - [signal@Gtk.Paned::move-handle] - [signal@Gtk.Paned::toggle-handle-focus] # CSS nodes ``` paned ├── <child> ├── separator[.wide] ╰── <child> ``` `GtkPaned` has a main CSS node with name paned, and a subnode for the separator with name separator. The subnode gets a .wide style class when the paned is supposed to be wide. In horizontal orientation, the nodes are arranged based on the text direction, so in left-to-right mode, :first-child will select the leftmost child, while it will select the rightmost child in RTL layouts. ## Creating a paned widget with minimum sizes. ```c GtkWidget *hpaned = gtk_paned_new (GTK_ORIENTATION_HORIZONTAL); GtkWidget *frame1 = gtk_frame_new (NULL); GtkWidget *frame2 = gtk_frame_new (NULL); gtk_widget_set_size_request (hpaned, 200, -1); gtk_paned_set_start_child (GTK_PANED (hpaned), frame1); gtk_paned_set_resize_start_child (GTK_PANED (hpaned), TRUE); gtk_paned_set_shrink_start_child (GTK_PANED (hpaned), FALSE); gtk_widget_set_size_request (frame1, 50, -1); gtk_paned_set_end_child (GTK_PANED (hpaned), frame2); gtk_paned_set_resize_end_child (GTK_PANED (hpaned), FALSE); gtk_paned_set_shrink_end_child (GTK_PANED (hpaned), FALSE); gtk_widget_set_size_request (frame2, 50, -1); ``` Creates a new `GtkPaned` widget. the newly created paned widget the paned’s orientation. Retrieves the end child of the given `GtkPaned`. the end child widget a `GtkPaned` Obtains the position of the divider between the two panes. the position of the divider, in pixels a `GtkPaned` widget Returns whether the [property@Gtk.Paned:end-child] can be resized. true if the end child is resizable a `GtkPaned` Returns whether the [property@Gtk.Paned:start-child] can be resized. true if the start child is resizable a `GtkPaned` Returns whether the [property@Gtk.Paned:end-child] can shrink. true if the end child is shrinkable a `GtkPaned` Returns whether the [property@Gtk.Paned:start-child] can shrink. true if the start child is shrinkable a `GtkPaned` Retrieves the start child of the given `GtkPaned`. the start child widget a `GtkPaned` Gets whether the separator should be wide. %TRUE if the paned should have a wide handle a `GtkPaned` Sets the end child of @paned to @child. If @child is `NULL`, the existing child will be removed. a `GtkPaned` the widget to add Sets the position of the divider between the two panes. a `GtkPaned` widget pixel position of divider, a negative value means that the position is unset Sets whether the [property@Gtk.Paned:end-child] can be resized. a `GtkPaned` true to let the end child be resized Sets whether the [property@Gtk.Paned:start-child] can be resized. a `GtkPaned` true to let the start child be resized Sets whether the [property@Gtk.Paned:end-child] can shrink. a `GtkPaned` true to let the end child be shrunk Sets whether the [property@Gtk.Paned:start-child] can shrink. a `GtkPaned` true to let the start child be shrunk Sets the start child of @paned to @child. If @child is `NULL`, the existing child will be removed. a `GtkPaned` the widget to add Sets whether the separator should be wide. a `GtkPaned` the new value for the [property@Gtk.Paned:wide-handle] property The second child. The largest possible value for the [property@Gtk.Paned:position] property. This property is derived from the size and shrinkability of the widget's children. The smallest possible value for the [property@Gtk.Paned:position] property. This property is derived from the size and shrinkability of the widget's children. Position of the separator in pixels, from the left/top. Whether the [property@Gtk.Paned:position] property has been set. Determines whether the second child expands and shrinks along with the paned widget. Determines whether the first child expands and shrinks along with the paned widget. Determines whether the second child can be made smaller than its requisition. Determines whether the first child can be made smaller than its requisition. The first child. Whether the `GtkPaned` should provide a stronger visual separation. For example, this could be set when a paned contains two [class@Gtk.Notebook]s, whose tab rows would otherwise merge visually. Emitted to accept the current position of the handle when moving it using key bindings. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Return</kbd> or <kbd>Space</kbd>. whether the position was accepted Emitted to cancel moving the position of the handle using key bindings. The position of the handle will be reset to the value prior to moving it. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Escape</kbd>. whether the position was canceled Emitted to cycle the focus between the children of the paned. This is a [keybinding signal](class.SignalAction.html). The default binding is <kbd>F6</kbd>. whether the behavior was cycled whether cycling backward or forward Emitted to cycle whether the paned should grab focus to allow the user to change position of the handle by using key bindings. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>F8</kbd>. whether the behavior was cycled whether cycling backward or forward Emitted to move the handle with key bindings. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>←</kbd>, <kbd>←</kbd>, <kbd>Ctrl</kbd>+<kbd>→</kbd>, <kbd>→</kbd>, <kbd>Ctrl</kbd>+<kbd>↑</kbd>, <kbd>↑</kbd>, <kbd>Ctrl</kbd>+<kbd>↓</kbd>, <kbd>↓</kbd>, <kbd>PgUp</kbd>, <kbd>PgDn</kbd>, <kbd>Home</kbd>, <kbd>End</kbd>. whether the handle was moved a `GtkScrollType` Emitted to accept the current position of the handle and then move focus to the next widget in the focus chain. This is a [keybinding signal](class.SignalAction.html). The default binding is <kbd>Tab</kbd>. whether handle focus was toggled `GtkPaperSize` handles paper sizes. It uses the standard called [PWG 5101.1-2002 PWG: Standard for Media Standardized Names](http://www.pwg.org/standards.html) to name the paper sizes (and to get the data for the page sizes). In addition to standard paper sizes, `GtkPaperSize` allows to construct custom paper sizes with arbitrary dimensions. The `GtkPaperSize` object stores not only the dimensions (width and height) of a paper size and its name, it also provides default print margins. Creates a new `GtkPaperSize` object by parsing a [PWG 5101.1-2002](ftp://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn10-20020226-5101.1.pdf) paper name. If @name is %NULL, the default paper size is returned, see [func@Gtk.PaperSize.get_default]. a new `GtkPaperSize`, use [method@Gtk.PaperSize.free] to free it a paper size name Creates a new `GtkPaperSize` object with the given parameters. a new `GtkPaperSize` object, use [method@Gtk.PaperSize.free] to free it the paper name the human-readable name the paper width, in units of @unit the paper height, in units of @unit the unit for @width and @height. not %GTK_UNIT_NONE. Deserialize a paper size from a `GVariant`. The `GVariant must be in the format produced by [method@Gtk.PaperSize.to_gvariant]. a new `GtkPaperSize` object an a{sv} `GVariant` Creates a new `GtkPaperSize` object by using IPP information. If @ipp_name is not a recognized paper name, @width and @height are used to construct a custom `GtkPaperSize` object. a new `GtkPaperSize`, use [method@Gtk.PaperSize.free] to free it an IPP paper name the paper width, in points the paper height in points Reads a paper size from the group @group_name in the key file @key_file. a new `GtkPaperSize` object with the restored paper size the `GKeyFile` to retrieve the papersize from the name of the group in the key file to read, or %NULL to read the first group Creates a new `GtkPaperSize` object by using PPD information. If @ppd_name is not a recognized PPD paper name, @ppd_display_name, @width and @height are used to construct a custom `GtkPaperSize` object. a new `GtkPaperSize`, use [method@Gtk.PaperSize.free] to free it a PPD paper name the corresponding human-readable name the paper width, in points the paper height in points Copies an existing `GtkPaperSize`. a copy of @other a `GtkPaperSize` Free the given `GtkPaperSize` object. a `GtkPaperSize` Gets the default bottom margin for the `GtkPaperSize`. the default bottom margin a `GtkPaperSize` object the unit for the return value, not %GTK_UNIT_NONE Gets the default left margin for the `GtkPaperSize`. the default left margin a `GtkPaperSize` object the unit for the return value, not %GTK_UNIT_NONE Gets the default right margin for the `GtkPaperSize`. the default right margin a `GtkPaperSize` object the unit for the return value, not %GTK_UNIT_NONE Gets the default top margin for the `GtkPaperSize`. the default top margin a `GtkPaperSize` object the unit for the return value, not %GTK_UNIT_NONE Gets the human-readable name of the `GtkPaperSize`. the human-readable name of @size a `GtkPaperSize` object Gets the paper height of the `GtkPaperSize`, in units of @unit. the paper height a `GtkPaperSize` object the unit for the return value, not %GTK_UNIT_NONE Gets the name of the `GtkPaperSize`. the name of @size a `GtkPaperSize` object Gets the PPD name of the `GtkPaperSize`, which may be %NULL. the PPD name of @size a `GtkPaperSize` object Gets the paper width of the `GtkPaperSize`, in units of @unit. the paper width a `GtkPaperSize` object the unit for the return value, not %GTK_UNIT_NONE Returns %TRUE if @size is not a standard paper size. whether @size is a custom paper size. a `GtkPaperSize` object Compares two `GtkPaperSize` objects. %TRUE, if @size1 and @size2 represent the same paper size a `GtkPaperSize` object another `GtkPaperSize` object Returns %TRUE if @size is an IPP standard paper size. whether @size is not an IPP custom paper size. a `GtkPaperSize` object Changes the dimensions of a @size to @width x @height. a custom `GtkPaperSize` object the new width in units of @unit the new height in units of @unit the unit for @width and @height Serialize a paper size to an `a{sv}` variant. a new, floating, `GVariant` a `GtkPaperSize` This function adds the paper size from @size to @key_file. a `GtkPaperSize` the `GKeyFile` to save the paper size to the group to add the settings to in @key_file Returns the name of the default paper size, which depends on the current locale. the name of the default paper size. The string is owned by GTK and should not be modified. Creates a list of known paper sizes. a newly allocated list of newly allocated `GtkPaperSize` objects whether to include custom paper sizes as defined in the page setup dialog A `GParamSpec` for properties holding a `GtkExpression`. `GtkPasswordEntry` is an entry that has been tailored for entering secrets.  It does not show its contents in clear text, does not allow to copy it to the clipboard, and it shows a warning when Caps Lock is engaged. If the underlying platform allows it, `GtkPasswordEntry` will also place the text in a non-pageable memory area, to avoid it being written out to disk by the operating system. Optionally, it can offer a way to reveal the contents in clear text. `GtkPasswordEntry` provides only minimal API and should be used with the [iface@Gtk.Editable] API. # CSS Nodes ``` entry.password ╰── text ├── image.caps-lock-indicator ┊ ``` `GtkPasswordEntry` has a single CSS node with name entry that carries a .passwordstyle class. The text Css node below it has a child with name image and style class .caps-lock-indicator for the Caps Lock icon, and possibly other children. # Accessibility `GtkPasswordEntry` uses the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role. Creates a `GtkPasswordEntry`. a new `GtkPasswordEntry` Gets the menu model set with gtk_password_entry_set_extra_menu(). the menu model a `GtkPasswordEntry` Returns whether the entry is showing an icon to reveal the contents. %TRUE if an icon is shown a `GtkPasswordEntry` Sets a menu model to add when constructing the context menu for @entry. a `GtkPasswordEntry` a `GMenuModel` Sets whether the entry should have a clickable icon to reveal the contents. Setting this to %FALSE also hides the text again. a `GtkPasswordEntry` whether to show the peek icon Whether to activate the default widget when Enter is pressed. A menu model whose contents will be appended to the context menu. The text that will be displayed in the `GtkPasswordEntry` when it is empty and unfocused. Whether to show an icon for revealing the content. Emitted when the entry is activated. The keybindings for this signal are all forms of the Enter key. A `GtkEntryBuffer` that locks the underlying memory to prevent it from being swapped to disk. `GtkPasswordEntry` uses a `GtkPasswordEntryBuffer`. Creates a new `GtkEntryBuffer` using secure memory allocations. the newly created instance Flags that influence the behavior of [method@Widget.pick]. The default behavior, include widgets that are receiving events Include widgets that are insensitive Include widgets that are marked as non-targetable. See [property@Widget:can-target] The `GtkPicture` widget displays a `GdkPaintable`.  Many convenience functions are provided to make pictures simple to use. For example, if you want to load an image from a file, and then display it, there’s a convenience function to do this: ```c GtkWidget *widget = gtk_picture_new_for_filename ("myfile.png"); ``` If the file isn’t loaded successfully, the picture will contain a “broken image” icon similar to that used in many web browsers. If you want to handle errors in loading the file yourself, for example by displaying an error message, then load the image with [ctor@Gdk.Texture.new_from_file], then create the `GtkPicture` with [ctor@Gtk.Picture.new_for_paintable]. Sometimes an application will want to avoid depending on external data files, such as image files. See the documentation of `GResource` for details. In this case, [ctor@Gtk.Picture.new_for_resource] and [method@Gtk.Picture.set_resource] should be used. `GtkPicture` displays an image at its natural size. See [class@Gtk.Image] if you want to display a fixed-size image, such as an icon. ## Sizing the paintable You can influence how the paintable is displayed inside the `GtkPicture` by changing [property@Gtk.Picture:content-fit]. See [enum@Gtk.ContentFit] for details. [property@Gtk.Picture:can-shrink] can be unset to make sure that paintables are never made smaller than their ideal size - but be careful if you do not know the size of the paintable in use (like when displaying user-loaded images). This can easily cause the picture to grow larger than the screen. And [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] can be used to make sure the paintable doesn't fill all available space but is instead displayed at its original size. ## CSS nodes `GtkPicture` has a single CSS node with the name `picture`. ## Accessibility `GtkPicture` uses the `GTK_ACCESSIBLE_ROLE_IMG` role. Creates a new empty `GtkPicture` widget. a newly created `GtkPicture` widget. Creates a new `GtkPicture` displaying the given @file. If the file isn’t found or can’t be loaded, the resulting `GtkPicture` is empty. If you need to detect failures to load the file, use [ctor@Gdk.Texture.new_from_file] to load the file yourself, then create the `GtkPicture` from the texture. a new `GtkPicture` a `GFile` Creates a new `GtkPicture` displaying the file @filename. This is a utility function that calls [ctor@Gtk.Picture.new_for_file]. See that function for details. a new `GtkPicture` a filename Creates a new `GtkPicture` displaying @paintable. The `GtkPicture` will track changes to the @paintable and update its size and contents in response to it. a new `GtkPicture` a `GdkPaintable` Creates a new `GtkPicture` displaying @pixbuf. This is a utility function that calls [ctor@Gtk.Picture.new_for_paintable], See that function for details. The pixbuf must not be modified after passing it to this function. Use [ctor@Gtk.Picture.new_for_paintable] and [ctor@Gdk.Texture.new_for_pixbuf] instead a new `GtkPicture` a `GdkPixbuf` Creates a new `GtkPicture` displaying the resource at @resource_path. This is a utility function that calls [ctor@Gtk.Picture.new_for_file]. See that function for details. a new `GtkPicture` resource path to play back Gets the alternative textual description of the picture. The returned string will be %NULL if the picture cannot be described textually. the alternative textual description of @self. a `GtkPicture` Returns whether the `GtkPicture` respects its contents size. %TRUE if the picture can be made smaller than its contents a `GtkPicture` Returns the fit mode for the content of the `GtkPicture`. See [enum@Gtk.ContentFit] for details. the content fit mode a `GtkPicture` Gets the `GFile` currently displayed if @self is displaying a file. If @self is not displaying a file, for example when [method@Gtk.Picture.set_paintable] was used, then %NULL is returned. The `GFile` displayed by @self. a `GtkPicture` Returns whether the `GtkPicture` preserves its contents aspect ratio. Use [method@Gtk.Picture.get_content_fit] instead. This will now return `FALSE` only if [property@Gtk.Picture:content-fit] is `GTK_CONTENT_FIT_FILL`. Returns `TRUE` otherwise. %TRUE if the self tries to keep the contents' aspect ratio a `GtkPicture` Gets the `GdkPaintable` being displayed by the `GtkPicture`. the displayed paintable a `GtkPicture` Sets an alternative textual description for the picture contents. It is equivalent to the "alt" attribute for images on websites. This text will be made available to accessibility tools. If the picture cannot be described textually, set this property to %NULL. a `GtkPicture` a textual description of the contents If set to %TRUE, the @self can be made smaller than its contents. The contents will then be scaled down when rendering. If you want to still force a minimum size manually, consider using [method@Gtk.Widget.set_size_request]. Also of note is that a similar function for growing does not exist because the grow behavior can be controlled via [method@Gtk.Widget.set_halign] and [method@Gtk.Widget.set_valign]. a `GtkPicture` if @self can be made smaller than its contents Sets how the content should be resized to fit the `GtkPicture`. See [enum@Gtk.ContentFit] for details. a `GtkPicture` the content fit mode Makes @self load and display @file. See [ctor@Gtk.Picture.new_for_file] for details. a `GtkPicture` a `GFile` Makes @self load and display the given @filename. This is a utility function that calls [method@Gtk.Picture.set_file]. a `GtkPicture` the filename to play If set to %TRUE, the @self will render its contents according to their aspect ratio. That means that empty space may show up at the top/bottom or left/right of @self. If set to %FALSE or if the contents provide no aspect ratio, the contents will be stretched over the picture's whole area. Use [method@Gtk.Picture.set_content_fit] instead. If still used, this method will always set the [property@Gtk.Picture:content-fit] property to `GTK_CONTENT_FIT_CONTAIN` if @keep_aspect_ratio is true, otherwise it will set it to `GTK_CONTENT_FIT_FILL`. a `GtkPicture` whether to keep aspect ratio Makes @self display the given @paintable. If @paintable is %NULL, nothing will be displayed. See [ctor@Gtk.Picture.new_for_paintable] for details. a `GtkPicture` a `GdkPaintable` Sets a `GtkPicture` to show a `GdkPixbuf`. See [ctor@Gtk.Picture.new_for_pixbuf] for details. This is a utility function that calls [method@Gtk.Picture.set_paintable]. Use [method@Gtk.Picture.set_paintable] instead a `GtkPicture` a `GdkPixbuf` Makes @self load and display the resource at the given @resource_path. This is a utility function that calls [method@Gtk.Picture.set_file]. a `GtkPicture` the resource to set The alternative textual description for the picture. If the `GtkPicture` can be made smaller than the natural size of its contents. How the content should be resized to fit inside the `GtkPicture`. The `GFile` that is displayed or %NULL if none. Whether the GtkPicture will render its contents trying to preserve the aspect ratio. Use [property@Gtk.Picture:content-fit] instead. The `GdkPaintable` to be displayed by this `GtkPicture`. Determines how the size should be computed to achieve the one of the visibility mode for the scrollbars. The scrollbar is always visible. The view size is independent of the content. The scrollbar will appear and disappear as necessary. For example, when all of a `GtkTreeView` can not be seen. The scrollbar should never appear. In this mode the content determines the size. Don't show a scrollbar, but don't force the size to follow the content. This can be used e.g. to make multiple scrolled windows share a scrollbar. `GtkPopover` is a bubble-like context popup.  It is primarily meant to provide context-dependent information or options. Popovers are attached to a parent widget. By default, they point to the whole widget area, although this behavior can be changed with [method@Gtk.Popover.set_pointing_to]. The position of a popover relative to the widget it is attached to can also be changed with [method@Gtk.Popover.set_position] By default, `GtkPopover` performs a grab, in order to ensure input events get redirected to it while it is shown, and also so the popover is dismissed in the expected situations (clicks outside the popover, or the Escape key being pressed). If no such modal behavior is desired on a popover, [method@Gtk.Popover.set_autohide] may be called on it to tweak its behavior. ## GtkPopover as menu replacement `GtkPopover` is often used to replace menus. The best was to do this is to use the [class@Gtk.PopoverMenu] subclass which supports being populated from a `GMenuModel` with [ctor@Gtk.PopoverMenu.new_from_model]. ```xml <section> <attribute name="display-hint">horizontal-buttons</attribute> <item> <attribute name="label">Cut</attribute> <attribute name="action">app.cut</attribute> <attribute name="verb-icon">edit-cut-symbolic</attribute> </item> <item> <attribute name="label">Copy</attribute> <attribute name="action">app.copy</attribute> <attribute name="verb-icon">edit-copy-symbolic</attribute> </item> <item> <attribute name="label">Paste</attribute> <attribute name="action">app.paste</attribute> <attribute name="verb-icon">edit-paste-symbolic</attribute> </item> </section> ``` # Shortcuts and Gestures `GtkPopover` supports the following keyboard shortcuts: - <kbd>Escape</kbd> closes the popover. - <kbd>Alt</kbd> makes the mnemonics visible. The following signals have default keybindings: - [signal@Gtk.Popover::activate-default] # CSS nodes ``` popover.background[.menu] ├── arrow ╰── contents ╰── <child> ``` `GtkPopover` has a main node with name `popover`, an arrow with name `arrow`, and another node for the content named `contents`. The `popover` node always gets the `.background` style class. It also gets the `.menu` style class if the popover is menu-like, e.g. is a [class@Gtk.PopoverMenu]. Particular uses of `GtkPopover`, such as touch selection popups or magnifiers in `GtkEntry` or `GtkTextView` get style classes like `.touch-selection` or `.magnifier` to differentiate from plain popovers. When styling a popover directly, the `popover` node should usually not have any background. The visible part of the popover can have a shadow. To specify it in CSS, set the box-shadow of the `contents` node. Note that, in order to accomplish appropriate arrow visuals, `GtkPopover` uses custom drawing for the `arrow` node. This makes it possible for the arrow to change its shape dynamically, but it also limits the possibilities of styling it using CSS. In particular, the `arrow` gets drawn over the `content` node's border and shadow, so they look like one shape, which means that the border width of the `content` node and the `arrow` node should be the same. The arrow also does not support any border shape other than solid, no border-radius, only one border width (border-bottom-width is used) and no box-shadow. Creates a new `GtkPopover`. the new `GtkPopover` Returns whether the popover is modal. See [method@Gtk.Popover.set_autohide] for the implications of this. %TRUE if @popover is modal a `GtkPopover` Returns whether the popover will close after a modal child is closed. %TRUE if @popover will close after a modal child. a `GtkPopover` Gets the child widget of @popover. the child widget of @popover a `GtkPopover` Gets whether this popover is showing an arrow pointing at the widget that it is relative to. whether the popover has an arrow a `GtkPopover` Gets whether mnemonics are visible. %TRUE if mnemonics are supposed to be visible in this popover a `GtkPopover` Gets the offset previous set with [method@Gtk.Popover.set_offset()]. a `GtkPopover` a location for the x_offset a location for the y_offset Gets the rectangle that the popover points to. If a rectangle to point to has been set, this function will return %TRUE and fill in @rect with such rectangle, otherwise it will return %FALSE and fill in @rect with the parent widget coordinates. %TRUE if a rectangle to point to was set. a `GtkPopover` location to store the rectangle Returns the preferred position of @popover. The preferred position. a `GtkPopover` Pops @popover down. This may have the side-effect of closing a parent popover as well. See [property@Gtk.Popover:cascade-popdown]. a `GtkPopover` Pops @popover up. a `GtkPopover` Allocate a size for the `GtkPopover`. This function needs to be called in size-allocate by widgets who have a `GtkPopover` as child. When using a layout manager, this is happening automatically. To make a popover appear on screen, use [method@Gtk.Popover.popup]. a `GtkPopover` Sets whether @popover is modal. A modal popover will grab the keyboard focus on it when being displayed. Focus will wrap around within the popover. Clicking outside the popover area or pressing Esc will dismiss the popover. Called this function on an already showing popup with a new autohide value different from the current one, will cause the popup to be hidden. a `GtkPopover` %TRUE to dismiss the popover on outside clicks If @cascade_popdown is %TRUE, the popover will be closed when a child modal popover is closed. If %FALSE, @popover will stay visible. A `GtkPopover` %TRUE if the popover should follow a child closing Sets the child widget of @popover. a `GtkPopover` the child widget Sets the default widget of a `GtkPopover`. The default widget is the widget that’s activated when the user presses Enter in a dialog (for example). This function sets or unsets the default widget for a `GtkPopover`. a `GtkPopover` a child widget of @popover to set as the default, or %NULL to unset the default widget for the popover Sets whether this popover should draw an arrow pointing at the widget it is relative to. a `GtkPopover` %TRUE to draw an arrow Sets whether mnemonics should be visible. a `GtkPopover` the new value Sets the offset to use when calculating the position of the popover. These values are used when preparing the [struct@Gdk.PopupLayout] for positioning the popover. a `GtkPopover` the x offset to adjust the position by the y offset to adjust the position by Sets the rectangle that @popover points to. This is in the coordinate space of the @popover parent. a `GtkPopover` rectangle to point to Sets the preferred position for @popover to appear. If the @popover is currently visible, it will be immediately updated. This preference will be respected where possible, although on lack of space (eg. if close to the window edges), the `GtkPopover` may choose to appear on the opposite side. a `GtkPopover` preferred popover position Whether to dismiss the popover on outside clicks. Whether the popover pops down after a child popover. This is used to implement the expected behavior of submenus. The child widget. The default widget inside the popover. Whether to draw an arrow. Whether mnemonics are currently visible in this popover. Rectangle in the parent widget that the popover points to. How to place the popover, relative to its parent. Emitted whend the user activates the default widget. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Enter</kbd>. Emitted when the popover is closed. `GtkPopoverMenu` is a subclass of `GtkPopover` that implements menu behavior.  `GtkPopoverMenu` treats its children like menus and allows switching between them. It can open submenus as traditional, nested submenus, or in a more touch-friendly sliding fashion. The property [property@Gtk.PopoverMenu:flags] controls this appearance. `GtkPopoverMenu` is meant to be used primarily with menu models, using [ctor@Gtk.PopoverMenu.new_from_model]. If you need to put other widgets such as a `GtkSpinButton` or a `GtkSwitch` into a popover, you can use [method@Gtk.PopoverMenu.add_child]. For more dialog-like behavior, use a plain `GtkPopover`. ## Menu models The XML format understood by `GtkBuilder` for `GMenuModel` consists of a toplevel `<menu>` element, which contains one or more `<item>` elements. Each `<item>` element contains `<attribute>` and `<link>` elements with a mandatory name attribute. `<link>` elements have the same content model as `<menu>`. Instead of `<link name="submenu">` or `<link name="section">`, you can use `<submenu>` or `<section>` elements. ```xml <menu id='app-menu'> <section> <item> <attribute name='label' translatable='yes'>_New Window</attribute> <attribute name='action'>app.new</attribute> </item> <item> <attribute name='label' translatable='yes'>_About Sunny</attribute> <attribute name='action'>app.about</attribute> </item> <item> <attribute name='label' translatable='yes'>_Quit</attribute> <attribute name='action'>app.quit</attribute> </item> </section> </menu> ``` Attribute values can be translated using gettext, like other `GtkBuilder` content. `<attribute>` elements can be marked for translation with a `translatable="yes"` attribute. It is also possible to specify message context and translator comments, using the context and comments attributes. To make use of this, the `GtkBuilder` must have been given the gettext domain to use. The following attributes are used when constructing menu items: - "label": a user-visible string to display - "use-markup": whether the text in the menu item includes [Pango markup](https://docs.gtk.org/Pango/pango_markup.html) - "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 track whether a submenu is open - "hidden-when": a string used to determine when the item will be hidden. Possible values include "action-disabled", "action-missing", "macos-menubar". This is mainly useful for exported menus, see [method@Gtk.Application.set_menubar]. - "custom": a string used to match against the ID of a custom child added with [method@Gtk.PopoverMenu.add_child], [method@Gtk.PopoverMenuBar.add_child], or in the ui file with `<child type="ID">`. 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", "circular-buttons" and "inline-buttons". They all indicate that section should be displayed as a horizontal row of buttons. - "text-direction": a string used to determine the `GtkTextDirection` to use when "display-hint" is set to "horizontal-buttons". Possible values include "rtl", "ltr", and "none". The following attributes are used when constructing submenus: - "label": a user-visible string to display - "icon": icon name to display Menu items will also show accelerators, which are usually associated with actions via [method@Gtk.Application.set_accels_for_action], [method@WidgetClass.add_binding_action] or [method@Gtk.ShortcutController.add_shortcut]. # Shortcuts and Gestures `GtkPopoverMenu` supports the following keyboard shortcuts: - <kbd>Space</kbd> activates the default widget. # CSS Nodes `GtkPopoverMenu` is just a subclass of `GtkPopover` that adds custom content to it, therefore it has the same CSS nodes. It is one of the cases that add a `.menu` style class to the main `popover` node. Menu items have nodes with name `button` and class `.model`. If a section display-hint is set, the section gets a node `box` with class `horizontal` plus a class with the same text as the display hint. Note that said box may not be the direct ancestor of the item `button`s. Thus, for example, to style items in an `inline-buttons` section, select `.inline-buttons button.model`. Other things that may be of interest to style in menus include `label` nodes. # Accessibility `GtkPopoverMenu` uses the %GTK_ACCESSIBLE_ROLE_MENU role, and its items use the %GTK_ACCESSIBLE_ROLE_MENU_ITEM, %GTK_ACCESSIBLE_ROLE_MENU_ITEM_CHECKBOX or %GTK_ACCESSIBLE_ROLE_MENU_ITEM_RADIO roles, depending on the action they are connected to. Creates a `GtkPopoverMenu` and populates it according to @model. The created buttons are connected to actions found in the `GtkApplicationWindow` to which the popover belongs - typically by means of being attached to a widget that is contained within the `GtkApplicationWindow`s widget hierarchy. Actions can also be added using [method@Gtk.Widget.insert_action_group] on the menus attach widget or on any of its parent widgets. This function creates menus with sliding submenus. See [ctor@Gtk.PopoverMenu.new_from_model_full] for a way to control this. the new `GtkPopoverMenu` a `GMenuModel` Creates a `GtkPopoverMenu` and populates it according to @model. The created buttons are connected to actions found in the action groups that are accessible from the parent widget. This includes the `GtkApplicationWindow` to which the popover belongs. Actions can also be added using [method@Gtk.Widget.insert_action_group] on the parent widget or on any of its parent widgets. the new `GtkPopoverMenu` a `GMenuModel` flags that affect how the menu is created Adds a custom widget to a generated menu. For this to work, the menu model of @popover must have an item with a `custom` attribute that matches @id. %TRUE if @id was found and the widget added a `GtkPopoverMenu` the `GtkWidget` to add the ID to insert @child at Returns the flags that @popover uses to create/display a menu from its model. the `GtkPopoverMenuFlags` a `GtkPopoverMenu` Returns the menu model used to populate the popover. the menu model of @popover a `GtkPopoverMenu` Removes a widget that has previously been added with [method@Gtk.PopoverMenu.add_child()] %TRUE if the widget was removed a `GtkPopoverMenu` the `GtkWidget` to remove Sets the flags that @popover uses to create/display a menu from its model. If a model is set and the flags change, contents are rebuilt, so if setting properties individually, set flags before model to avoid a redundant rebuild. a `GtkPopoverMenu` a set of `GtkPopoverMenuFlags` Sets a new menu model on @popover. The existing contents of @popover are removed, and the @popover is populated with new contents according to @model. a `GtkPopoverMenu` a `GMenuModel` The flags that @popover uses to create/display a menu from its model. If a model is set and the flags change, contents are rebuilt, so if setting properties individually, set flags before model to avoid a redundant rebuild. The model from which the menu is made. The name of the visible submenu. `GtkPopoverMenuBar` presents a horizontal bar of items that pop up popover menus when clicked.  The only way to create instances of `GtkPopoverMenuBar` is from a `GMenuModel`. # CSS nodes ``` menubar ├── item[.active] ┊ ╰── popover ╰── item ╰── popover ``` `GtkPopoverMenuBar` has a single CSS node with name menubar, below which each item has its CSS node, and below that the corresponding popover. The item whose popover is currently open gets the .active style class. # Accessibility `GtkPopoverMenuBar` uses the %GTK_ACCESSIBLE_ROLE_MENU_BAR role, the menu items use the %GTK_ACCESSIBLE_ROLE_MENU_ITEM role and the menus use the %GTK_ACCESSIBLE_ROLE_MENU role. Creates a `GtkPopoverMenuBar` from a `GMenuModel`. a new `GtkPopoverMenuBar` a `GMenuModel` Adds a custom widget to a generated menubar. For this to work, the menu model of @bar must have an item with a `custom` attribute that matches @id. %TRUE if @id was found and the widget added a `GtkPopoverMenuBar` the `GtkWidget` to add the ID to insert @child at Returns the model from which the contents of @bar are taken. a `GMenuModel` a `GtkPopoverMenuBar` Removes a widget that has previously been added with gtk_popover_menu_bar_add_child(). %TRUE if the widget was removed a `GtkPopoverMenuBar` the `GtkWidget` to remove Sets a menu model from which @bar should take its contents. a `GtkPopoverMenuBar` a `GMenuModel` The `GMenuModel` from which the menu bar is created. The model should only contain submenus as toplevel elements. Flags that affect how [class@Gtk.PopoverMenu] widgets built from a [class@Gio.MenuModel] are created and displayed. Submenus are presented as sliding submenus that replace the main menu. Submenus are presented as traditional, nested popovers. Describes which edge of a widget a certain feature is positioned at. For examples, see the tabs of a [class@Notebook], or the label of a [class@Scale]. The feature is at the left edge. The feature is at the right edge. The feature is at the top edge. The feature is at the bottom edge. A print backend. Specifies which features the print dialog should offer. If neither %GTK_PRINT_CAPABILITY_GENERATE_PDF nor %GTK_PRINT_CAPABILITY_GENERATE_PS is specified, GTK assumes that all formats are supported. Print dialog will offer printing even/odd pages. Print dialog will allow to print multiple copies. Print dialog will allow to collate multiple copies. Print dialog will allow to print pages in reverse order. Print dialog will allow to scale the output. The program will send the document to the printer in PDF format The program will send the document to the printer in Postscript format Print dialog will offer a preview Print dialog will offer printing multiple pages per sheet Print dialog will allow to rearrange pages when printing multiple pages per sheet A `GtkPrintContext` encapsulates context information that is required when drawing pages for printing. This includes the cairo context and important parameters like page size and resolution. It also lets you easily create [class@Pango.Layout] and [class@Pango.Context] objects that match the font metrics of the cairo surface. `GtkPrintContext` objects get passed to the [signal@Gtk.PrintOperation::begin-print], [signal@Gtk.PrintOperation::end-print], [signal@Gtk.PrintOperation::request-page-setup] and [signal@Gtk.PrintOperation::draw-page] signals on the [class@Gtk.PrintOperation] object. ## Using GtkPrintContext in a ::draw-page callback ```c static void draw_page (GtkPrintOperation *operation, GtkPrintContext *context, int page_nr) { cairo_t *cr; PangoLayout *layout; PangoFontDescription *desc; cr = gtk_print_context_get_cairo_context (context); // Draw a red rectangle, as wide as the paper (inside the margins) cairo_set_source_rgb (cr, 1.0, 0, 0); cairo_rectangle (cr, 0, 0, gtk_print_context_get_width (context), 50); cairo_fill (cr); // Draw some lines cairo_move_to (cr, 20, 10); cairo_line_to (cr, 40, 20); cairo_arc (cr, 60, 60, 20, 0, M_PI); cairo_line_to (cr, 80, 20); cairo_set_source_rgb (cr, 0, 0, 0); cairo_set_line_width (cr, 5); cairo_set_line_cap (cr, CAIRO_LINE_CAP_ROUND); cairo_set_line_join (cr, CAIRO_LINE_JOIN_ROUND); cairo_stroke (cr); // Draw some text layout = gtk_print_context_create_pango_layout (context); pango_layout_set_text (layout, "Hello World! Printing is easy", -1); desc = pango_font_description_from_string ("sans 28"); pango_layout_set_font_description (layout, desc); pango_font_description_free (desc); cairo_move_to (cr, 30, 20); pango_cairo_layout_path (cr, layout); // Font Outline cairo_set_source_rgb (cr, 0.93, 1.0, 0.47); cairo_set_line_width (cr, 0.5); cairo_stroke_preserve (cr); // Font Fill cairo_set_source_rgb (cr, 0, 0.0, 1.0); cairo_fill (cr); g_object_unref (layout); } ``` Creates a new `PangoContext` that can be used with the `GtkPrintContext`. a new Pango context for @context a `GtkPrintContext` Creates a new `PangoLayout` that is suitable for use with the `GtkPrintContext`. a new Pango layout for @context a `GtkPrintContext` Obtains the cairo context that is associated with the `GtkPrintContext`. the cairo context of @context a `GtkPrintContext` Obtains the horizontal resolution of the `GtkPrintContext`, in dots per inch. the horizontal resolution of @context a `GtkPrintContext` Obtains the vertical resolution of the `GtkPrintContext`, in dots per inch. the vertical resolution of @context a `GtkPrintContext` Obtains the hardware printer margins of the `GtkPrintContext`, in units. %TRUE if the hard margins were retrieved a `GtkPrintContext` top hardware printer margin bottom hardware printer margin left hardware printer margin right hardware printer margin Obtains the height of the `GtkPrintContext`, in pixels. the height of @context a `GtkPrintContext` Obtains the `GtkPageSetup` that determines the page dimensions of the `GtkPrintContext`. the page setup of @context a `GtkPrintContext` Returns a `PangoFontMap` that is suitable for use with the `GtkPrintContext`. the font map of @context a `GtkPrintContext` Obtains the width of the `GtkPrintContext`, in pixels. the width of @context a `GtkPrintContext` Sets a new cairo context on a print context. This function is intended to be used when implementing an internal print preview, it is not needed for printing, since GTK itself creates a suitable cairo context in that case. a `GtkPrintContext` the cairo context the horizontal resolution to use with @cr the vertical resolution to use with @cr A `GtkPrintDialog` object collects the arguments that are needed to present a print dialog to the user, such as a title for the dialog and whether it should be modal. The dialog is shown with the [method@Gtk.PrintDialog.setup] function. The actual printing can be done with [method@Gtk.PrintDialog.print] or [method@Gtk.PrintDialog.print_file]. These APIs follows the GIO async pattern, and the results can be obtained by calling the corresponding finish methods. Creates a new `GtkPrintDialog` object. the new `GtkPrintDialog` Returns the label that will be shown on the accept button of the print dialog. the accept label a `GtkPrintDialog` Returns whether the print dialog blocks interaction with the parent window while it is presented. whether the print dialog is modal a `GtkPrintDialog` Returns the page setup. the page setup a `GtkPrintDialog` Returns the print settings for the print dialog. the settings a `GtkPrintDialog` Returns the title that will be shown on the print dialog. the title a `GtkPrintDialog` This function prints content from a stream. If you pass `NULL` as @setup, then this method will present a print dialog. Otherwise, it will attempt to print directly, without user interaction. The @callback will be called when the printing is done. a `GtkPrintDialog` the parent `GtkWindow` the `GtkPrintSetup` to use a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback This function prints a file. If you pass `NULL` as @setup, then this method will present a print dialog. Otherwise, it will attempt to print directly, without user interaction. a `GtkPrintDialog` the parent `GtkWindow` the `GtkPrintSetup` to use the `GFile` to print a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.PrintDialog.print_file] call and returns the results. Whether the call was successful a `GtkPrintDialog` a `GAsyncResult` Finishes the [method@Gtk.PrintDialog.print] call and returns the results. If the call was successful, the content to be printed should be written to the returned output stream. Otherwise, `NULL` is returned. The overall results of the print operation will be returned in the [method@Gio.OutputStream.close] call, so if you are interested in the results, you need to explicitly close the output stream (it will be closed automatically if you just unref it). Be aware that the close call may not be instant as it operation will for the printer to finish printing. a [class@Gio.OutputStream] a `GtkPrintDialog` a `GAsyncResult` Sets the label that will be shown on the accept button of the print dialog shown for [method@Gtk.PrintDialog.setup]. a `GtkPrintDialog` the new accept label Sets whether the print dialog blocks interaction with the parent window while it is presented. a `GtkPrintDialog` the new value Set the page setup for the print dialog. a `GtkPrintDialog` the new page setup Sets the print settings for the print dialog. a `GtkPrintDialog` the new print settings Sets the title that will be shown on the print dialog. a `GtkPrintDialog` the new title This function presents a print dialog to let the user select a printer, and set up print settings and page setup. The @callback will be called when the dialog is dismissed. The obtained [struct@Gtk.PrintSetup] can then be passed to [method@Gtk.PrintDialog.print] or [method@Gtk.PrintDialog.print_file]. One possible use for this method is to have the user select a printer, then show a page setup UI in the application (e.g. to arrange images on a page), then call [method@Gtk.PrintDialog.print] on @self to do the printing without further user interaction. a `GtkPrintDialog` the parent `GtkWindow` a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.PrintDialog.setup] call. If the call was successful, it returns a [struct@Gtk.PrintSetup] which contains the print settings and page setup information that will be used to print. The `GtkPrintSetup` object that resulted from the call, or `NULL` if the call was not successful a `GtkPrintDialog` a `GAsyncResult` A label that may be shown on the accept button of a print dialog that is presented by [method@Gtk.PrintDialog.setup]. Whether the print dialog is modal. The page setup to use. The print settings to use. A title that may be shown on the print dialog that is presented by [method@Gtk.PrintDialog.setup]. See also gtk_print_settings_set_duplex(). No duplex. Horizontal duplex. Vertical duplex. Error codes that identify various errors that can occur while using the GTK printing support. An unspecified error occurred. An internal error occurred. A memory allocation failed. An error occurred while loading a page setup or paper size from a key file. Registers an error quark for `GtkPrintOperation` if necessary. The error quark used for `GtkPrintOperation` errors. A `GtkPrintJob` object represents a job that is sent to a printer. You only need to deal directly with print jobs if you use the non-portable [class@Gtk.PrintUnixDialog] API. Use [method@Gtk.PrintJob.get_surface] to obtain the cairo surface onto which the pages must be drawn. Use [method@Gtk.PrintJob.send] to send the finished job to the printer. If you don’t use cairo `GtkPrintJob` also supports printing of manually generated PostScript, via [method@Gtk.PrintJob.set_source_file]. Creates a new `GtkPrintJob`. a new `GtkPrintJob` the job title a `GtkPrinter` a `GtkPrintSettings` a `GtkPageSetup` Gets whether this job is printed collated. whether the job is printed collated a `GtkPrintJob` Gets the n-up setting for this job. the n-up setting a `GtkPrintJob` Gets the n-up layout setting for this job. the n-up layout a `GtkPrintJob` Gets the number of copies of this job. the number of copies a `GtkPrintJob` Gets the page ranges for this job. a pointer to an array of `GtkPageRange` structs a `GtkPrintJob` return location for the number of ranges Gets the `GtkPageSet` setting for this job. the `GtkPageSet` setting a `GtkPrintJob` Gets the `GtkPrintPages` setting for this job. the `GtkPrintPages` setting a `GtkPrintJob` Gets the `GtkPrinter` of the print job. the printer of @job a `GtkPrintJob` Gets whether this job is printed reversed. whether the job is printed reversed. a `GtkPrintJob` Gets whether the job is printed rotated. whether the job is printed rotated a `GtkPrintJob` Gets the scale for this job. the scale a `GtkPrintJob` Gets the `GtkPrintSettings` of the print job. the settings of @job a `GtkPrintJob` Gets the status of the print job. the status of @job a `GtkPrintJob` Gets a cairo surface onto which the pages of the print job should be rendered. the cairo surface of @job a `GtkPrintJob` Gets the job title. the title of @job a `GtkPrintJob` Returns whether jobs will be tracked after printing. For details, see [method@Gtk.PrintJob.set_track_print_status]. %TRUE if print job status will be reported after printing a `GtkPrintJob` Sends the print job off to the printer. a `GtkPrintJob` function to call when the job completes or an error occurs user data that gets passed to @callback destroy notify for @user_data Sets whether this job is printed collated. a `GtkPrintJob` whether the job is printed collated Sets the n-up setting for this job. a `GtkPrintJob` the n-up value Sets the n-up layout setting for this job. a `GtkPrintJob` the n-up layout setting Sets the number of copies for this job. a `GtkPrintJob` the number of copies Sets the page ranges for this job. a `GtkPrintJob` pointer to an array of `GtkPageRange` structs the length of the @ranges array Sets the `GtkPageSet` setting for this job. a `GtkPrintJob` a `GtkPageSet` setting Sets the `GtkPrintPages` setting for this job. a `GtkPrintJob` the `GtkPrintPages` setting Sets whether this job is printed reversed. a `GtkPrintJob` whether the job is printed reversed Sets whether this job is printed rotated. a `GtkPrintJob` whether to print rotated Sets the scale for this job. 1.0 means unscaled. a `GtkPrintJob` the scale Make the `GtkPrintJob` send an existing document to the printing system. The file can be in any format understood by the platforms printing system (typically PostScript, but on many platforms PDF may work too). See [method@Gtk.Printer.accepts_pdf] and [method@Gtk.Printer.accepts_ps]. This is similar to [method@Gtk.PrintJob.set_source_file], but takes expects an open file descriptor for the file, instead of a filename. %FALSE if an error occurred a `GtkPrintJob` a file descriptor Make the `GtkPrintJob` send an existing document to the printing system. The file can be in any format understood by the platforms printing system (typically PostScript, but on many platforms PDF may work too). See [method@Gtk.Printer.accepts_pdf] and [method@Gtk.Printer.accepts_ps]. %FALSE if an error occurred a `GtkPrintJob` the file to be printed If track_status is %TRUE, the print job will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like “out of paper” issues, and when the print job actually reaches the printer. This function is often implemented using some form of polling, so it should not be enabled unless needed. a `GtkPrintJob` %TRUE to track status after printing Page setup. The printer to send the job to. Printer settings. The title of the print job. %TRUE if the print job will continue to emit status-changed signals after the print data has been setn to the printer. Emitted when the status of a job changes. The signal handler can use [method@Gtk.PrintJob.get_status] to obtain the new status. The type of callback that is passed to gtk_print_job_send(). It is called when the print job has been completely sent. the `GtkPrintJob` user data that has been passed to gtk_print_job_send() a `GError` that contains error information if the sending of the print job failed, otherwise %NULL `GtkPrintOperation` is the high-level, portable printing API. It looks a bit different than other GTK dialogs such as the `GtkFileChooser`, since some platforms don’t expose enough infrastructure to implement a good print dialog. On such platforms, `GtkPrintOperation` uses the native print dialog. On platforms which do not provide a native print dialog, GTK uses its own, see [class@Gtk.PrintUnixDialog]. The typical way to use the high-level printing API is to create a `GtkPrintOperation` object with [ctor@Gtk.PrintOperation.new] when the user selects to print. Then you set some properties on it, e.g. the page size, any [class@Gtk.PrintSettings] from previous print operations, the number of pages, the current page, etc. Then you start the print operation by calling [method@Gtk.PrintOperation.run]. It will then show a dialog, let the user select a printer and options. When the user finished the dialog, various signals will be emitted on the `GtkPrintOperation`, the main one being [signal@Gtk.PrintOperation::draw-page], which you are supposed to handle and render the page on the provided [class@Gtk.PrintContext] using Cairo. # The high-level printing API ```c static GtkPrintSettings *settings = NULL; static void do_print (void) { GtkPrintOperation *print; GtkPrintOperationResult res; print = gtk_print_operation_new (); if (settings != NULL) gtk_print_operation_set_print_settings (print, settings); g_signal_connect (print, "begin_print", G_CALLBACK (begin_print), NULL); g_signal_connect (print, "draw_page", G_CALLBACK (draw_page), NULL); res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, GTK_WINDOW (main_window), NULL); if (res == GTK_PRINT_OPERATION_RESULT_APPLY) { if (settings != NULL) g_object_unref (settings); settings = g_object_ref (gtk_print_operation_get_print_settings (print)); } g_object_unref (print); } ``` By default `GtkPrintOperation` uses an external application to do print preview. To implement a custom print preview, an application must connect to the preview signal. The functions [method@Gtk.PrintOperationPreview.render_page], [method@Gtk.PrintOperationPreview.end_preview] and [method@Gtk.PrintOperationPreview.is_selected] are useful when implementing a print preview. Creates a new `GtkPrintOperation`. a new `GtkPrintOperation` Signal emitted after the user has finished changing print settings in the dialog, before the actual rendering starts. Signal emitted when displaying the print dialog. Signal emitted right before “begin-print” if you added a custom widget in the “create-custom-widget” handler. Signal emitted when the print operation run has finished doing everything required for printing. Signal emitted for every page that is printed. Signal emitted after all pages have been rendered. Signal emitted after the “begin-print” signal, but before the actual rendering starts. Signal emitted when a preview is requested from the native dialog. Emitted once for every page that is printed, to give the application a chance to modify the page setup. Emitted at between the various phases of the print operation. Emitted after change of selected printer. Cancels a running print operation. This function may be called from a [signal@Gtk.PrintOperation::begin-print], [signal@Gtk.PrintOperation::paginate] or [signal@Gtk.PrintOperation::draw-page] signal handler to stop the currently running print operation. a `GtkPrintOperation` Signal that drawing of particular page is complete. It is called after completion of page drawing (e.g. drawing in another thread). If [method@Gtk.PrintOperation.set_defer_drawing] was called before, then this function has to be called by application. Otherwise it is called by GTK itself. a `GtkPrintOperation` Returns the default page setup. the default page setup a `GtkPrintOperation` Gets whether page setup selection combos are embedded whether page setup selection combos are embedded a `GtkPrintOperation` Call this when the result of a print operation is %GTK_PRINT_OPERATION_RESULT_ERROR. It can be called either after [method@Gtk.PrintOperation.run] returns, or in the [signal@Gtk.PrintOperation::done] signal handler. The returned `GError` will contain more details on what went wrong. a `GtkPrintOperation` Gets whether there is a selection. whether there is a selection a `GtkPrintOperation` Returns the number of pages that will be printed. Note that this value is set during print preparation phase (%GTK_PRINT_STATUS_PREPARING), so this function should never be called before the data generation phase (%GTK_PRINT_STATUS_GENERATING_DATA). You can connect to the [signal@Gtk.PrintOperation::status-changed] signal and call gtk_print_operation_get_n_pages_to_print() when print status is %GTK_PRINT_STATUS_GENERATING_DATA. This is typically used to track the progress of print operation. the number of pages that will be printed a `GtkPrintOperation` Returns the current print settings. Note that the return value is %NULL until either [method@Gtk.PrintOperation.set_print_settings] or [method@Gtk.PrintOperation.run] have been called. the current print settings of @op. a `GtkPrintOperation` Returns the status of the print operation. Also see [method@Gtk.PrintOperation.get_status_string]. the status of the print operation a `GtkPrintOperation` Returns a string representation of the status of the print operation. The string is translated and suitable for displaying the print status e.g. in a `GtkStatusbar`. Use [method@Gtk.PrintOperation.get_status] to obtain a status value that is suitable for programmatic use. a string representation of the status of the print operation a `GtkPrintOperation` Gets whether the application supports print of selection whether the application supports print of selection a `GtkPrintOperation` A convenience function to find out if the print operation is finished. a print operation is finished if its status is either %GTK_PRINT_STATUS_FINISHED or %GTK_PRINT_STATUS_FINISHED_ABORTED. Note: when you enable print status tracking the print operation can be in a non-finished state even after done has been called, as the operation status then tracks the print job status on the printer. %TRUE, if the print operation is finished. a `GtkPrintOperation` Runs the print operation. Normally that this function does not return until the rendering of all pages is complete. You can connect to the [signal@Gtk.PrintOperation::status-changed] signal on @op to obtain some information about the progress of the print operation. Furthermore, it may use a recursive mainloop to show the print dialog. If you set the [Gtk.PrintOperation:allow-async] property, the operation will run asynchronously if this is supported on the platform. The [signal@Gtk.PrintOperation::done] signal will be emitted with the result of the operation when the it is done (i.e. when the dialog is canceled, or when the print succeeds or fails). ```c if (settings != NULL) gtk_print_operation_set_print_settings (print, settings); if (page_setup != NULL) gtk_print_operation_set_default_page_setup (print, page_setup); g_signal_connect (print, "begin-print", G_CALLBACK (begin_print), &data); g_signal_connect (print, "draw-page", G_CALLBACK (draw_page), &data); res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, parent, &error); if (res == GTK_PRINT_OPERATION_RESULT_ERROR) { error_dialog = gtk_message_dialog_new (GTK_WINDOW (parent), GTK_DIALOG_DESTROY_WITH_PARENT, GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, "Error printing file:\n%s", error->message); g_signal_connect (error_dialog, "response", G_CALLBACK (gtk_window_destroy), NULL); gtk_window_present (GTK_WINDOW (error_dialog)); g_error_free (error); } else if (res == GTK_PRINT_OPERATION_RESULT_APPLY) { if (settings != NULL) g_object_unref (settings); settings = g_object_ref (gtk_print_operation_get_print_settings (print)); } ``` Note that gtk_print_operation_run() can only be called once on a given `GtkPrintOperation`. the result of the print operation. A return value of %GTK_PRINT_OPERATION_RESULT_APPLY indicates that the printing was completed successfully. In this case, it is a good idea to obtain the used print settings with [method@Gtk.PrintOperation.get_print_settings] and store them for reuse with the next print operation. A value of %GTK_PRINT_OPERATION_RESULT_IN_PROGRESS means the operation is running asynchronously, and will emit the [signal@Gtk.PrintOperation::done] signal when done. a `GtkPrintOperation` the action to start Transient parent of the dialog Sets whether gtk_print_operation_run() may return before the print operation is completed. Note that some platforms may not allow asynchronous operation. a `GtkPrintOperation` %TRUE to allow asynchronous operation Sets the current page. If this is called before [method@Gtk.PrintOperation.run], the user will be able to select to print only the current page. Note that this only makes sense for pre-paginated documents. a `GtkPrintOperation` the current page, 0-based Sets the label for the tab holding custom widgets. a `GtkPrintOperation` the label to use, or %NULL to use the default label Makes @default_page_setup the default page setup for @op. This page setup will be used by [method@Gtk.PrintOperation.run], but it can be overridden on a per-page basis by connecting to the [signal@Gtk.PrintOperation::request-page-setup] signal. a `GtkPrintOperation` a `GtkPageSetup` Sets up the `GtkPrintOperation` to wait for calling of [method@Gtk.PrintOperation.draw_page_finish from application. This can be used for drawing page in another thread. This function must be called in the callback of the [signal@Gtk.PrintOperation::draw-page] signal. a `GtkPrintOperation` Embed page size combo box and orientation combo box into page setup page. Selected page setup is stored as default page setup in `GtkPrintOperation`. a `GtkPrintOperation` %TRUE to embed page setup selection in the `GtkPrintUnixDialog` Sets up the `GtkPrintOperation` to generate a file instead of showing the print dialog. The intended use of this function is for implementing “Export to PDF” actions. Currently, PDF is the only supported format. “Print to PDF” support is independent of this and is done by letting the user pick the “Print to PDF” item from the list of printers in the print dialog. a `GtkPrintOperation` the filename for the exported file Sets whether there is a selection to print. Application has to set number of pages to which the selection will draw by [method@Gtk.PrintOperation.set_n_pages] in a handler for the [signal@Gtk.PrintOperation::begin-print] signal. a `GtkPrintOperation` %TRUE indicates that a selection exists Sets the name of the print job. The name is used to identify the job (e.g. in monitoring applications like eggcups). If you don’t set a job name, GTK picks a default one by numbering successive print jobs. a `GtkPrintOperation` a string that identifies the print job Sets the number of pages in the document. This must be set to a positive number before the rendering starts. It may be set in a [signal@Gtk.PrintOperation::begin-print] signal handler. Note that the page numbers passed to the [signal@Gtk.PrintOperation::request-page-setup] and [signal@Gtk.PrintOperation::draw-page] signals are 0-based, i.e. if the user chooses to print all pages, the last ::draw-page signal will be for page @n_pages - 1. a `GtkPrintOperation` the number of pages Sets the print settings for @op. This is typically used to re-establish print settings from a previous print operation, see [method@Gtk.PrintOperation.run]. a `GtkPrintOperation` `GtkPrintSettings` If @show_progress is %TRUE, the print operation will show a progress dialog during the print operation. a `GtkPrintOperation` %TRUE to show a progress dialog Sets whether selection is supported by `GtkPrintOperation`. a `GtkPrintOperation` %TRUE to support selection If track_status is %TRUE, the print operation will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like “out of paper” issues, and when the print job actually reaches the printer. This function is often implemented using some form of polling, so it should not be enabled unless needed. a `GtkPrintOperation` %TRUE to track status after printing Sets up the transformation for the cairo context obtained from `GtkPrintContext` in such a way that distances are measured in units of @unit. a `GtkPrintOperation` the unit to use If @full_page is %TRUE, the transformation for the cairo context obtained from `GtkPrintContext` puts the origin at the top left corner of the page. This may not be the top left corner of the sheet, depending on page orientation and the number of pages per sheet). Otherwise, the origin is at the top left corner of the imageable area (i.e. inside the margins). a `GtkPrintOperation` %TRUE to set up the `GtkPrintContext` for the full page Determines whether the print operation may run asynchronously or not. Some systems don't support asynchronous printing, but those that do will return %GTK_PRINT_OPERATION_RESULT_IN_PROGRESS as the status, and emit the [signal@Gtk.PrintOperation::done] signal when the operation is actually done. The Windows port does not support asynchronous operation at all (this is unlikely to change). On other platforms, all actions except for %GTK_PRINT_OPERATION_ACTION_EXPORT support asynchronous operation. The current page in the document. If this is set before [method@Gtk.PrintOperation.run], the user will be able to select to print only the current page. Note that this only makes sense for pre-paginated documents. Used as the label of the tab containing custom widgets. Note that this property may be ignored on some platforms. If this is %NULL, GTK uses a default label. The `GtkPageSetup` used by default. This page setup will be used by [method@Gtk.PrintOperation.run], but it can be overridden on a per-page basis by connecting to the [signal@Gtk.PrintOperation::request-page-setup] signal. If %TRUE, page size combo box and orientation combo box are embedded into page setup page. The name of a file to generate instead of showing the print dialog. Currently, PDF is the only supported format. The intended use of this property is for implementing “Export to PDF” actions. “Print to PDF” support is independent of this and is done by letting the user pick the “Print to PDF” item from the list of printers in the print dialog. Determines whether there is a selection in your application. This can allow your application to print the selection. This is typically used to make a "Selection" button sensitive. A string used to identify the job (e.g. in monitoring applications like eggcups). If you don't set a job name, GTK picks a default one by numbering successive print jobs. The number of pages in the document. This must be set to a positive number before the rendering starts. It may be set in a [signal@Gtk.PrintOperation::begin-print] signal handler. Note that the page numbers passed to the [signal@Gtk.PrintOperation::request-page-setup] and [signal@Gtk.PrintOperation::draw-page] signals are 0-based, i.e. if the user chooses to print all pages, the last ::draw-page signal will be for page @n_pages - 1. The number of pages that will be printed. Note that this value is set during print preparation phase (%GTK_PRINT_STATUS_PREPARING), so this value should never be get before the data generation phase (%GTK_PRINT_STATUS_GENERATING_DATA). You can connect to the [signal@Gtk.PrintOperation::status-changed] signal and call [method@Gtk.PrintOperation.get_n_pages_to_print] when print status is %GTK_PRINT_STATUS_GENERATING_DATA. This is typically used to track the progress of print operation. The `GtkPrintSettings` used for initializing the dialog. Setting this property is typically used to re-establish print settings from a previous print operation, see [method@Gtk.PrintOperation.run]. Determines whether to show a progress dialog during the print operation. The status of the print operation. A string representation of the status of the print operation. The string is translated and suitable for displaying the print status e.g. in a `GtkStatusbar`. See the [property@Gtk.PrintOperation:status] property for a status value that is suitable for programmatic use. If %TRUE, the print operation will support print of selection. This allows the print dialog to show a "Selection" button. If %TRUE, the print operation will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like “out of paper” issues, and when the print job actually reaches the printer. However, this is often implemented using polling, and should not be enabled unless needed. The transformation for the cairo context obtained from `GtkPrintContext` is set up in such a way that distances are measured in units of @unit. If %TRUE, the transformation for the cairo context obtained from `GtkPrintContext` puts the origin at the top left corner of the page. This may not be the top left corner of the sheet, depending on page orientation and the number of pages per sheet. Otherwise, the origin is at the top left corner of the imageable area (i.e. inside the margins). Emitted after the user has finished changing print settings in the dialog, before the actual rendering starts. A typical use for ::begin-print is to use the parameters from the [class@Gtk.PrintContext] and paginate the document accordingly, and then set the number of pages with [method@Gtk.PrintOperation.set_n_pages]. the `GtkPrintContext` for the current operation Emitted when displaying the print dialog. If you return a widget in a handler for this signal it will be added to a custom tab in the print dialog. You typically return a container widget with multiple widgets in it. The print dialog owns the returned widget, and its lifetime is not controlled by the application. However, the widget is guaranteed to stay around until the [signal@Gtk.PrintOperation::custom-widget-apply] signal is emitted on the operation. Then you can read out any information you need from the widgets. A custom widget that gets embedded in the print dialog Emitted right before ::begin-print if you added a custom widget in the ::create-custom-widget handler. When you get this signal you should read the information from the custom widgets, as the widgets are not guaranteed to be around at a later time. the custom widget added in ::create-custom-widget Emitted when the print operation run has finished doing everything required for printing. @result gives you information about what happened during the run. If @result is %GTK_PRINT_OPERATION_RESULT_ERROR then you can call [method@Gtk.PrintOperation.get_error] for more information. If you enabled print status tracking then [method@Gtk.PrintOperation.is_finished] may still return %FALSE after the ::done signal was emitted. the result of the print operation Emitted for every page that is printed. The signal handler must render the @page_nr's page onto the cairo context obtained from @context using [method@Gtk.PrintContext.get_cairo_context]. ```c static void draw_page (GtkPrintOperation *operation, GtkPrintContext *context, int page_nr, gpointer user_data) { cairo_t *cr; PangoLayout *layout; double width, text_height; int layout_height; PangoFontDescription *desc; cr = gtk_print_context_get_cairo_context (context); width = gtk_print_context_get_width (context); cairo_rectangle (cr, 0, 0, width, HEADER_HEIGHT); cairo_set_source_rgb (cr, 0.8, 0.8, 0.8); cairo_fill (cr); layout = gtk_print_context_create_pango_layout (context); desc = pango_font_description_from_string ("sans 14"); pango_layout_set_font_description (layout, desc); pango_font_description_free (desc); pango_layout_set_text (layout, "some text", -1); pango_layout_set_width (layout, width * PANGO_SCALE); pango_layout_set_alignment (layout, PANGO_ALIGN_CENTER); pango_layout_get_size (layout, NULL, &layout_height); text_height = (double)layout_height / PANGO_SCALE; cairo_move_to (cr, width / 2, (HEADER_HEIGHT - text_height) / 2); pango_cairo_show_layout (cr, layout); g_object_unref (layout); } ``` Use [method@Gtk.PrintOperation.set_use_full_page] and [method@Gtk.PrintOperation.set_unit] before starting the print operation to set up the transformation of the cairo context according to your needs. the `GtkPrintContext` for the current operation the number of the currently printed page (0-based) Emitted after all pages have been rendered. A handler for this signal can clean up any resources that have been allocated in the [signal@Gtk.PrintOperation::begin-print] handler. the `GtkPrintContext` for the current operation Emitted after the ::begin-print signal, but before the actual rendering starts. It keeps getting emitted until a connected signal handler returns %TRUE. The ::paginate signal is intended to be used for paginating a document in small chunks, to avoid blocking the user interface for a long time. The signal handler should update the number of pages using [method@Gtk.PrintOperation.set_n_pages], and return %TRUE if the document has been completely paginated. If you don't need to do pagination in chunks, you can simply do it all in the ::begin-print handler, and set the number of pages from there. %TRUE if pagination is complete the `GtkPrintContext` for the current operation Gets emitted when a preview is requested from the native dialog. The default handler for this signal uses an external viewer application to preview. To implement a custom print preview, an application must return %TRUE from its handler for this signal. In order to use the provided @context for the preview implementation, it must be given a suitable cairo context with [method@Gtk.PrintContext.set_cairo_context]. The custom preview implementation can use [method@Gtk.PrintOperationPreview.is_selected] and [method@Gtk.PrintOperationPreview.render_page] to find pages which are selected for print and render them. The preview must be finished by calling [method@Gtk.PrintOperationPreview.end_preview] (typically in response to the user clicking a close button). %TRUE if the listener wants to take over control of the preview the `GtkPrintOperationPreview` for the current operation the `GtkPrintContext` that will be used the `GtkWindow` to use as window parent Emitted once for every page that is printed. This gives the application a chance to modify the page setup. Any changes done to @setup will be in force only for printing this page. the `GtkPrintContext` for the current operation the number of the currently printed page (0-based) the `GtkPageSetup` Emitted at between the various phases of the print operation. See [enum@Gtk.PrintStatus] for the phases that are being discriminated. Use [method@Gtk.PrintOperation.get_status] to find out the current status. Emitted after change of selected printer. The actual page setup and print settings are passed to the custom widget, which can actualize itself according to this change. the custom widget added in ::create-custom-widget actual page setup actual print settings Determines what action the print operation should perform. A parameter of this typs is passed to [method@Gtk.PrintOperation.run]. Show the print dialog. Start to print without showing the print dialog, based on the current print settings. Show the print preview. Export to a file. This requires the export-filename property to be set. The parent class. Signal emitted when the print operation run has finished doing everything required for printing. Signal emitted after the user has finished changing print settings in the dialog, before the actual rendering starts. Signal emitted after the “begin-print” signal, but before the actual rendering starts. Emitted once for every page that is printed, to give the application a chance to modify the page setup. Signal emitted for every page that is printed. Signal emitted after all pages have been rendered. Emitted at between the various phases of the print operation. Signal emitted when displaying the print dialog. Signal emitted right before “begin-print” if you added a custom widget in the “create-custom-widget” handler. Signal emitted when a preview is requested from the native dialog. Emitted after change of selected printer. `GtkPrintOperationPreview` is the interface that is used to implement print preview. A `GtkPrintOperationPreview` object is passed to the [signal@Gtk.PrintOperation::preview] signal by [class@Gtk.PrintOperation]. Ends a preview. This function must be called to finish a custom print preview. a `GtkPrintOperationPreview` Returns whether the given page is included in the set of pages that have been selected for printing. %TRUE if the page has been selected for printing a `GtkPrintOperationPreview` a page number Renders a page to the preview. This is using the print context that was passed to the [signal@Gtk.PrintOperation::preview] handler together with @preview. A custom print preview should use this function to render the currently selected page. Note that this function requires a suitable cairo context to be associated with the print context. a `GtkPrintOperationPreview` the page to render Ends a preview. This function must be called to finish a custom print preview. a `GtkPrintOperationPreview` Returns whether the given page is included in the set of pages that have been selected for printing. %TRUE if the page has been selected for printing a `GtkPrintOperationPreview` a page number Renders a page to the preview. This is using the print context that was passed to the [signal@Gtk.PrintOperation::preview] handler together with @preview. A custom print preview should use this function to render the currently selected page. Note that this function requires a suitable cairo context to be associated with the print context. a `GtkPrintOperationPreview` the page to render Emitted once for each page that gets rendered to the preview. A handler for this signal should update the @context according to @page_setup and set up a suitable cairo context, using [method@Gtk.PrintContext.set_cairo_context]. the current `GtkPrintContext` the `GtkPageSetup` for the current page The ::ready signal gets emitted once per preview operation, before the first page is rendered. A handler for this signal can be used for setup tasks. the current `GtkPrintContext` a `GtkPrintOperationPreview` the page to render %TRUE if the page has been selected for printing a `GtkPrintOperationPreview` a page number a `GtkPrintOperationPreview` The result of a print operation. A value of this type is returned by [method@Gtk.PrintOperation.run]. An error has occurred. The print settings should be stored. The print operation has been canceled, the print settings should not be stored. The print operation is not complete yet. This value will only be returned when running asynchronously. See also gtk_print_job_set_pages() All pages. Current page. Range of pages. Selected pages. See also gtk_print_settings_set_quality(). Low quality. Normal quality. High quality. Draft quality. A `GtkPrintSettings` object represents the settings of a print dialog in a system-independent way. The main use for this object is that once you’ve printed you can get a settings object that represents the settings the user chose, and the next time you print you can pass that object in so that the user doesn’t have to re-set all his settings. Its also possible to enumerate the settings so that you can easily save the settings for the next time your app runs, or even store them in a document. The predefined keys try to use shared values as much as possible so that moving such a document between systems still works. Creates a new `GtkPrintSettings` object. a new `GtkPrintSettings` object Reads the print settings from @file_name. Returns a new `GtkPrintSettings` object with the restored settings, or %NULL if an error occurred. If the file could not be loaded then error is set to either a `GFileError` or `GKeyFileError`. See [method@Gtk.PrintSettings.to_file]. the restored `GtkPrintSettings` the filename to read the settings from Deserialize print settings from an a{sv} variant. The variant must be in the format produced by [method@Gtk.PrintSettings.to_gvariant]. a new `GtkPrintSettings` object an a{sv} `GVariant` Reads the print settings from the group @group_name in @key_file. Returns a new `GtkPrintSettings` object with the restored settings, or %NULL if an error occurred. If the file could not be loaded then error is set to either `GFileError` or `GKeyFileError`. the restored `GtkPrintSettings` the `GKeyFile` to retrieve the settings from the name of the group to use, or %NULL to use the default “Print Settings” Copies a `GtkPrintSettings` object. a newly allocated copy of @other a `GtkPrintSettings` Calls @func for each key-value pair of @settings. a `GtkPrintSettings` the function to call user data for @func Looks up the string value associated with @key. the string value for @key a `GtkPrintSettings` a key Returns the boolean represented by the value that is associated with @key. The string “true” represents %TRUE, any other string %FALSE. %TRUE, if @key maps to a true value. a `GtkPrintSettings` a key Gets the value of %GTK_PRINT_SETTINGS_COLLATE. whether to collate the printed pages a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE. the default source a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_DITHER. the dithering that is used a `GtkPrintSettings` Returns the double value associated with @key, or 0. the double value of @key a `GtkPrintSettings` a key Returns the floating point number represented by the value that is associated with @key, or @default_val if the value does not represent a floating point number. Floating point numbers are parsed with g_ascii_strtod(). the floating point number associated with @key a `GtkPrintSettings` a key the default value Gets the value of %GTK_PRINT_SETTINGS_DUPLEX. whether to print the output in duplex. a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_FINISHINGS. the finishings a `GtkPrintSettings` Returns the integer value of @key, or 0. the integer value of @key a `GtkPrintSettings` a key Returns the value of @key, interpreted as an integer, or the default value. the integer value of @key a `GtkPrintSettings` a key the default value Returns the value associated with @key, interpreted as a length. The returned value is converted to @units. the length value of @key, converted to @unit a `GtkPrintSettings` a key the unit of the return value Gets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE. The set of media types is defined in PWG 5101.1-2002 PWG. the media type a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_N_COPIES. the number of copies to print a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP. the number of pages per sheet a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT. layout of page in number-up mode a `GtkPrintSettings` Get the value of %GTK_PRINT_SETTINGS_ORIENTATION, converted to a `GtkPageOrientation`. the orientation a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN. the output bin a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES. an array of `GtkPageRange`s. Use g_free() to free the array when it is no longer needed. a `GtkPrintSettings` return location for the length of the returned array Gets the value of %GTK_PRINT_SETTINGS_PAGE_SET. the set of pages to print a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT, converted to @unit. the paper height, in units of @unit a `GtkPrintSettings` the unit for the return value Gets the value of %GTK_PRINT_SETTINGS_PAPER_FORMAT, converted to a `GtkPaperSize`. the paper size a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH, converted to @unit. the paper width, in units of @unit a `GtkPrintSettings` the unit for the return value Gets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES. which pages to print a `GtkPrintSettings` Convenience function to obtain the value of %GTK_PRINT_SETTINGS_PRINTER. the printer name a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI. the resolution in lpi (lines per inch) a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_QUALITY. the print quality a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION. the resolution in dpi a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_X. the horizontal resolution in dpi a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_RESOLUTION_Y. the vertical resolution in dpi a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_REVERSE. whether to reverse the order of the printed pages a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_SCALE. the scale in percent a `GtkPrintSettings` Gets the value of %GTK_PRINT_SETTINGS_USE_COLOR. whether to use color a `GtkPrintSettings` Returns %TRUE, if a value is associated with @key. %TRUE, if @key has a value a `GtkPrintSettings` a key Reads the print settings from @file_name. If the file could not be loaded then error is set to either a `GFileError` or `GKeyFileError`. See [method@Gtk.PrintSettings.to_file]. %TRUE on success a `GtkPrintSettings` the filename to read the settings from Reads the print settings from the group @group_name in @key_file. If the file could not be loaded then error is set to either a `GFileError` or `GKeyFileError`. %TRUE on success a `GtkPrintSettings` the `GKeyFile` to retrieve the settings from the name of the group to use, or %NULL to use the default “Print Settings” Associates @value with @key. a `GtkPrintSettings` a key a string value Sets @key to a boolean value. a `GtkPrintSettings` a key a boolean Sets the value of %GTK_PRINT_SETTINGS_COLLATE. a `GtkPrintSettings` whether to collate the output Sets the value of %GTK_PRINT_SETTINGS_DEFAULT_SOURCE. a `GtkPrintSettings` the default source Sets the value of %GTK_PRINT_SETTINGS_DITHER. a `GtkPrintSettings` the dithering that is used Sets @key to a double value. a `GtkPrintSettings` a key a double value Sets the value of %GTK_PRINT_SETTINGS_DUPLEX. a `GtkPrintSettings` a `GtkPrintDuplex` value Sets the value of %GTK_PRINT_SETTINGS_FINISHINGS. a `GtkPrintSettings` the finishings Sets @key to an integer value. a `GtkPrintSettings` a key an integer Associates a length in units of @unit with @key. a `GtkPrintSettings` a key a length the unit of @length Sets the value of %GTK_PRINT_SETTINGS_MEDIA_TYPE. The set of media types is defined in PWG 5101.1-2002 PWG. a `GtkPrintSettings` the media type Sets the value of %GTK_PRINT_SETTINGS_N_COPIES. a `GtkPrintSettings` the number of copies Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP. a `GtkPrintSettings` the number of pages per sheet Sets the value of %GTK_PRINT_SETTINGS_NUMBER_UP_LAYOUT. a `GtkPrintSettings` a `GtkNumberUpLayout` value Sets the value of %GTK_PRINT_SETTINGS_ORIENTATION. a `GtkPrintSettings` a page orientation Sets the value of %GTK_PRINT_SETTINGS_OUTPUT_BIN. a `GtkPrintSettings` the output bin Sets the value of %GTK_PRINT_SETTINGS_PAGE_RANGES. a `GtkPrintSettings` an array of `GtkPageRange`s the length of @page_ranges Sets the value of %GTK_PRINT_SETTINGS_PAGE_SET. a `GtkPrintSettings` a `GtkPageSet` value Sets the value of %GTK_PRINT_SETTINGS_PAPER_HEIGHT. a `GtkPrintSettings` the paper height the units of @height Sets the value of %GTK_PRINT_SETTINGS_PAPER_FORMAT, %GTK_PRINT_SETTINGS_PAPER_WIDTH and %GTK_PRINT_SETTINGS_PAPER_HEIGHT. a `GtkPrintSettings` a paper size Sets the value of %GTK_PRINT_SETTINGS_PAPER_WIDTH. a `GtkPrintSettings` the paper width the units of @width Sets the value of %GTK_PRINT_SETTINGS_PRINT_PAGES. a `GtkPrintSettings` a `GtkPrintPages` value Convenience function to set %GTK_PRINT_SETTINGS_PRINTER to @printer. a `GtkPrintSettings` the printer name Sets the value of %GTK_PRINT_SETTINGS_PRINTER_LPI. a `GtkPrintSettings` the resolution in lpi (lines per inch) Sets the value of %GTK_PRINT_SETTINGS_QUALITY. a `GtkPrintSettings` a `GtkPrintQuality` value Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION, %GTK_PRINT_SETTINGS_RESOLUTION_X and %GTK_PRINT_SETTINGS_RESOLUTION_Y. a `GtkPrintSettings` the resolution in dpi Sets the values of %GTK_PRINT_SETTINGS_RESOLUTION, %GTK_PRINT_SETTINGS_RESOLUTION_X and %GTK_PRINT_SETTINGS_RESOLUTION_Y. a `GtkPrintSettings` the horizontal resolution in dpi the vertical resolution in dpi Sets the value of %GTK_PRINT_SETTINGS_REVERSE. a `GtkPrintSettings` whether to reverse the output Sets the value of %GTK_PRINT_SETTINGS_SCALE. a `GtkPrintSettings` the scale in percent Sets the value of %GTK_PRINT_SETTINGS_USE_COLOR. a `GtkPrintSettings` whether to use color This function saves the print settings from @settings to @file_name. If the file could not be written then error is set to either a `GFileError` or `GKeyFileError`. %TRUE on success a `GtkPrintSettings` the file to save to Serialize print settings to an a{sv} variant. a new, floating, `GVariant` a `GtkPrintSettings` This function adds the print settings from @settings to @key_file. a `GtkPrintSettings` the `GKeyFile` to save the print settings to the group to add the settings to in @key_file, or %NULL to use the default “Print Settings” Removes any value associated with @key. This has the same effect as setting the value to %NULL. a `GtkPrintSettings` a key Function called by [method@Gtk.PrintSettings.foreach] on every key/value pair inside a [class@Gtk.PrintSettings]. the setting key the setting value The user data provided with the function A `GtkPrintSetup` is an auxiliary object for printing that allows decoupling the setup from the printing. A print setup is obtained by calling [method@Gtk.PrintDialog.setup], and can later be passed to print functions such as [method@Gtk.PrintDialog.print]. Print setups can be reused for multiple print calls. Applications may wish to store the page_setup and print_settings from the print setup and copy them to the PrintDialog if they want to keep using them. Returns the page setup of @setup. It may be different from the `GtkPrintDialog`'s page setup if the user changed it during the setup process. the page setup, or `NULL` a `GtkPrintSetup` Returns the print settings of @setup. They may be different from the `GtkPrintDialog`'s settings if the user changed them during the setup process. the print settings, or `NULL` a `GtkPrintSetup` Increase the reference count of @setup. the print setup a `GtkPrintSetup` Decrease the reference count of @setup. If the reference count reaches zero, the object is freed. a `GtkPrintSetup` The status gives a rough indication of the completion of a running print operation. The printing has not started yet; this status is set initially, and while the print dialog is shown. This status is set while the begin-print signal is emitted and during pagination. This status is set while the pages are being rendered. The print job is being sent off to the printer. The print job has been sent to the printer, but is not printed for some reason, e.g. the printer may be stopped. Some problem has occurred during printing, e.g. a paper jam. The printer is processing the print job. The printing has been completed successfully. The printing has been aborted. `GtkPrintUnixDialog` implements a print dialog for platforms which don’t provide a native print dialog, like Unix.  It can be used very much like any other GTK dialog, at the cost of the portability offered by the high-level printing API with [class@Gtk.PrintOperation]. In order to print something with `GtkPrintUnixDialog`, you need to use [method@Gtk.PrintUnixDialog.get_selected_printer] to obtain a [class@Gtk.Printer] object and use it to construct a [class@Gtk.PrintJob] using [ctor@Gtk.PrintJob.new]. `GtkPrintUnixDialog` uses the following response values: - %GTK_RESPONSE_OK: for the “Print” button - %GTK_RESPONSE_APPLY: for the “Preview” button - %GTK_RESPONSE_CANCEL: for the “Cancel” button # GtkPrintUnixDialog as GtkBuildable The `GtkPrintUnixDialog` implementation of the `GtkBuildable` interface exposes its @notebook internal children with the name “notebook”. An example of a `GtkPrintUnixDialog` UI definition fragment: ```xml <object class="GtkPrintUnixDialog" id="dialog1"> <child internal-child="notebook"> <object class="GtkNotebook" id="notebook"> <child> <object type="GtkNotebookPage"> <property name="tab_expand">False</property> <property name="tab_fill">False</property> <property name="tab"> <object class="GtkLabel" id="tablabel"> <property name="label">Tab label</property> </object> </property> <property name="child"> <object class="GtkLabel" id="tabcontent"> <property name="label">Content on notebook tab</property> </object> </property> </object> </child> </object> </child> </object> ``` # CSS nodes `GtkPrintUnixDialog` has a single CSS node with name window. The style classes dialog and print are added. Creates a new `GtkPrintUnixDialog`. a new `GtkPrintUnixDialog` Title of the dialog Transient parent of the dialog Adds a custom tab to the print dialog. a `GtkPrintUnixDialog` the widget to put in the custom tab the widget to use as tab label Gets the current page of the `GtkPrintUnixDialog`. the current page of @dialog a `GtkPrintUnixDialog` Gets whether to embed the page setup. whether to embed the page setup a `GtkPrintUnixDialog` Gets whether there is a selection. whether there is a selection a `GtkPrintUnixDialog` Gets the capabilities that have been set on this `GtkPrintUnixDialog`. the printing capabilities a `GtkPrintUnixDialog` Gets the page setup that is used by the `GtkPrintUnixDialog`. the page setup of @dialog. a `GtkPrintUnixDialog` Gets whether a page setup was set by the user. whether a page setup was set by user. a `GtkPrintUnixDialog` Gets the currently selected printer. the currently selected printer a `GtkPrintUnixDialog` Gets a new `GtkPrintSettings` object that represents the current values in the print dialog. Note that this creates a new object, and you need to unref it if don’t want to keep it. a new `GtkPrintSettings` object with the values from @dialog a `GtkPrintUnixDialog` Gets whether the print dialog allows user to print a selection. whether the application supports print of selection a `GtkPrintUnixDialog` Sets the current page number. If @current_page is not -1, this enables the current page choice for the range of pages to print. a `GtkPrintUnixDialog` the current page number. Embed page size combo box and orientation combo box into page setup page. a `GtkPrintUnixDialog` embed page setup selection Sets whether a selection exists. a `GtkPrintUnixDialog` %TRUE indicates that a selection exists This lets you specify the printing capabilities your application supports. For instance, if you can handle scaling the output then you pass %GTK_PRINT_CAPABILITY_SCALE. If you don’t pass that, then the dialog will only let you select the scale if the printing system automatically handles scaling. a `GtkPrintUnixDialog` the printing capabilities of your application Sets the page setup of the `GtkPrintUnixDialog`. a `GtkPrintUnixDialog` a `GtkPageSetup` Sets the `GtkPrintSettings` for the `GtkPrintUnixDialog`. Typically, this is used to restore saved print settings from a previous print operation before the print dialog is shown. a `GtkPrintUnixDialog` a `GtkPrintSettings` Sets whether the print dialog allows user to print a selection. a `GtkPrintUnixDialog` %TRUE to allow print selection The current page in the document. %TRUE if the page setup controls are embedded. Whether the application has a selection. Capabilities the application can handle. The `GtkPageSetup` object to use. The `GtkPrintSettings` object used for this dialog. The `GtkPrinter` which is selected. Whether the dialog supports selection. A `GtkPrinter` object represents a printer. You only need to deal directly with printers if you use the non-portable [class@Gtk.PrintUnixDialog] API. A `GtkPrinter` allows to get status information about the printer, such as its description, its location, the number of queued jobs, etc. Most importantly, a `GtkPrinter` object can be used to create a [class@Gtk.PrintJob] object, which lets you print to the printer. Creates a new `GtkPrinter`. a new `GtkPrinter` the name of the printer a `GtkPrintBackend` whether the printer is virtual Returns whether the printer accepts input in PDF format. %TRUE if @printer accepts PDF a `GtkPrinter` Returns whether the printer accepts input in PostScript format. %TRUE if @printer accepts PostScript a `GtkPrinter` Compares two printers. 0 if the printer match, a negative value if @a < @b, or a positive value if @a > @b a `GtkPrinter` another `GtkPrinter` Returns the backend of the printer. the backend of @printer a `GtkPrinter` Returns the printer’s capabilities. This is useful when you’re using `GtkPrintUnixDialog`’s manual-capabilities setting and need to know which settings the printer can handle and which you must handle yourself. This will return 0 unless the printer’s details are available, see [method@Gtk.Printer.has_details] and [method@Gtk.Printer.request_details]. the printer’s capabilities a `GtkPrinter` Returns default page size of @printer. a newly allocated `GtkPageSetup` with default page size of the printer. a `GtkPrinter` Gets the description of the printer. the description of @printer a `GtkPrinter` Retrieve the hard margins of @printer. These are the margins that define the area at the borders of the paper that the printer cannot print to. Note: This will not succeed unless the printer’s details are available, see [method@Gtk.Printer.has_details] and [method@Gtk.Printer.request_details]. %TRUE iff the hard margins were retrieved a `GtkPrinter` a location to store the top margin in a location to store the bottom margin in a location to store the left margin in a location to store the right margin in Retrieve the hard margins of @printer for @paper_size. These are the margins that define the area at the borders of the paper that the printer cannot print to. Note: This will not succeed unless the printer’s details are available, see [method@Gtk.Printer.has_details] and [method@Gtk.Printer.request_details]. %TRUE iff the hard margins were retrieved a `GtkPrinter` a `GtkPaperSize` a location to store the top margin in a location to store the bottom margin in a location to store the left margin in a location to store the right margin in Gets the name of the icon to use for the printer. the icon name for @printer a `GtkPrinter` Gets the number of jobs currently queued on the printer. the number of jobs on @printer a `GtkPrinter` Returns a description of the location of the printer. the location of @printer a `GtkPrinter` Returns the name of the printer. the name of @printer a `GtkPrinter` Returns the state message describing the current state of the printer. the state message of @printer a `GtkPrinter` Returns whether the printer details are available. %TRUE if @printer details are available a `GtkPrinter` Returns whether the printer is accepting jobs %TRUE if @printer is accepting jobs a `GtkPrinter` Returns whether the printer is currently active (i.e. accepts new jobs). %TRUE if @printer is active a `GtkPrinter` Returns whether the printer is the default printer. %TRUE if @printer is the default a `GtkPrinter` Returns whether the printer is currently paused. A paused printer still accepts jobs, but it is not printing them. %TRUE if @printer is paused a `GtkPrinter` Returns whether the printer is virtual (i.e. does not represent actual printer hardware, but something like a CUPS class). %TRUE if @printer is virtual a `GtkPrinter` Lists all the paper sizes @printer supports. This will return and empty list unless the printer’s details are available, see [method@Gtk.Printer.has_details] and [method@Gtk.Printer.request_details]. a newly allocated list of newly allocated `GtkPageSetup`s. a `GtkPrinter` Requests the printer details. When the details are available, the [signal@Gtk.Printer::details-acquired] signal will be emitted on @printer. a `GtkPrinter` %TRUE if the printer is accepting jobs. %TRUE if this printer can accept PDF. %TRUE if this printer can accept PostScript. The backend for the printer. Icon name to use for the printer. %FALSE if this represents a real hardware device. Number of jobs queued in the printer. Information about the location of the printer. The name of the printer. %TRUE if this printer is paused. A paused printer still accepts jobs, but it does not print them. String giving the current status of the printer. Emitted in response to a request for detailed information about a printer from the print backend. The @success parameter indicates if the information was actually obtained. %TRUE if the details were successfully acquired The type of function passed to gtk_enumerate_printers(). Note that you need to ref @printer, if you want to keep a reference to it after the function has returned. %TRUE to stop the enumeration, %FALSE to continue a `GtkPrinter` user data passed to gtk_enumerate_printers() `GtkProgressBar` is typically used to display the progress of a long running operation. It provides a visual clue that processing is underway. `GtkProgressBar` can be used in two different modes: percentage mode and activity mode.  When an application can determine how much work needs to take place (e.g. read a fixed number of bytes from a file) and can monitor its progress, it can use the `GtkProgressBar` in percentage mode and the user sees a growing bar indicating the percentage of the work that has been completed. In this mode, the application is required to call [method@Gtk.ProgressBar.set_fraction] periodically to update the progress bar. When an application has no accurate way of knowing the amount of work to do, it can use the `GtkProgressBar` in activity mode, which shows activity by a block moving back and forth within the progress area. In this mode, the application is required to call [method@Gtk.ProgressBar.pulse] periodically to update the progress bar. There is quite a bit of flexibility provided to control the appearance of the `GtkProgressBar`. Functions are provided to control the orientation of the bar, optional text can be displayed along with the bar, and the step size used in activity mode can be set. # CSS nodes ``` progressbar[.osd] ├── [text] ╰── trough[.empty][.full] ╰── progress[.pulse] ``` `GtkProgressBar` has a main CSS node with name progressbar and subnodes with names text and trough, of which the latter has a subnode named progress. The text subnode is only present if text is shown. The progress subnode has the style class .pulse when in activity mode. It gets the style classes .left, .right, .top or .bottom added when the progress 'touches' the corresponding end of the GtkProgressBar. The .osd class on the progressbar node is for use in overlays like the one Epiphany has for page loading progress. # Accessibility `GtkProgressBar` uses the %GTK_ACCESSIBLE_ROLE_PROGRESS_BAR role. Creates a new `GtkProgressBar`. a `GtkProgressBar`. Returns the ellipsizing position of the progress bar. See [method@Gtk.ProgressBar.set_ellipsize]. `PangoEllipsizeMode` a `GtkProgressBar` Returns the current fraction of the task that’s been completed. a fraction from 0.0 to 1.0 a `GtkProgressBar` Returns whether the progress bar is inverted. %TRUE if the progress bar is inverted a `GtkProgressBar` Retrieves the pulse step. See [method@Gtk.ProgressBar.set_pulse_step]. a fraction from 0.0 to 1.0 a `GtkProgressBar` Returns whether the `GtkProgressBar` shows text. See [method@Gtk.ProgressBar.set_show_text]. %TRUE if text is shown in the progress bar a `GtkProgressBar` Retrieves the text that is displayed with the progress bar. The return value is a reference to the text, not a copy of it, so will become invalid if you change the text in the progress bar. the text a `GtkProgressBar` Indicates that some progress has been made, but you don’t know how much. Causes the progress bar to enter “activity mode,” where a block bounces back and forth. Each call to [method@Gtk.ProgressBar.pulse] causes the block to move by a little bit (the amount of movement per pulse is determined by [method@Gtk.ProgressBar.set_pulse_step]). a `GtkProgressBar` Sets the mode used to ellipsize the text. The text is ellipsized if there is not enough space to render the entire string. a `GtkProgressBar` a `PangoEllipsizeMode` Causes the progress bar to “fill in” the given fraction of the bar. The fraction should be between 0.0 and 1.0, inclusive. a `GtkProgressBar` fraction of the task that’s been completed Sets whether the progress bar is inverted. Progress bars normally grow from top to bottom or left to right. Inverted progress bars grow in the opposite direction. a `GtkProgressBar` %TRUE to invert the progress bar Sets the fraction of total progress bar length to move the bouncing block. The bouncing block is moved when [method@Gtk.ProgressBar.pulse] is called. a `GtkProgressBar` fraction between 0.0 and 1.0 Sets whether the progress bar will show text next to the bar. The shown text is either the value of the [property@Gtk.ProgressBar:text] property or, if that is %NULL, the [property@Gtk.ProgressBar:fraction] value, as a percentage. To make a progress bar that is styled and sized suitably for containing text (even if the actual text is blank), set [property@Gtk.ProgressBar:show-text] to %TRUE and [property@Gtk.ProgressBar:text] to the empty string (not %NULL). a `GtkProgressBar` whether to show text Causes the given @text to appear next to the progress bar. If @text is %NULL and [property@Gtk.ProgressBar:show-text] is %TRUE, the current value of [property@Gtk.ProgressBar:fraction] will be displayed as a percentage. If @text is non-%NULL and [property@Gtk.ProgressBar:show-text] is %TRUE, the text will be displayed. In this case, it will not display the progress percentage. If @text is the empty string, the progress bar will still be styled and sized suitably for containing text, as long as [property@Gtk.ProgressBar:show-text] is %TRUE. a `GtkProgressBar` a UTF-8 string The preferred place to ellipsize the string. The text will be ellipsized if the progress bar does not have enough room to display the entire string, specified as a `PangoEllipsizeMode`. Note that setting this property to a value other than %PANGO_ELLIPSIZE_NONE has the side-effect that the progress bar requests only enough space to display the ellipsis ("..."). Another means to set a progress bar's width is [method@Gtk.Widget.set_size_request]. The fraction of total work that has been completed. Invert the direction in which the progress bar grows. The fraction of total progress to move the bounding block when pulsed. Sets whether the progress bar will show a text in addition to the bar itself. The shown text is either the value of the [property@Gtk.ProgressBar:text] property or, if that is %NULL, the [property@Gtk.ProgressBar:fraction] value, as a percentage. To make a progress bar that is styled and sized suitably for showing text (even if the actual text is blank), set [property@Gtk.ProgressBar:show-text] to %TRUE and [property@Gtk.ProgressBar:text] to the empty string (not %NULL). Text to be displayed in the progress bar. Describes limits of a [class@EventController] for handling events targeting other widgets. Events are handled regardless of what their target is. Events are only handled if their target is in the same [iface@Native] as the event controllers widget. Note that some event types have two targets (origin and destination). Describes the stage at which events are fed into a [class@EventController]. Events are not delivered. Events are delivered in the capture phase. The capture phase happens before the bubble phase, runs from the toplevel down to the event widget. This option should only be used on containers that might possibly handle events before their children do. Events are delivered in the bubble phase. The bubble phase happens after the capture phase, and before the default handlers are run. This phase runs from the event widget, up to the toplevel. Events are delivered in the default widget event handlers, note that widget implementations must chain up on button, motion, touch and grab broken handlers for controllers in this phase to be run. A `GObject` property value in a `GtkExpression`. Creates an expression that looks up a property. The object to use is found by evaluating the `expression`, or using the `this` argument when `expression` is `NULL`. If the resulting object conforms to `this_type`, its property named `property_name` will be queried. Otherwise, this expression's evaluation will fail. The given `this_type` must have a property with `property_name`. a new `GtkExpression` The type to expect for the this type Expression to evaluate to get the object to query or `NULL` to query the `this` object name of the property Creates an expression that looks up a property. The object to use is found by evaluating the `expression`, or using the `this` argument when `expression` is `NULL`. If the resulting object conforms to `this_type`, its property specified by `pspec` will be queried. Otherwise, this expression's evaluation will fail. a new `GtkExpression` Expression to evaluate to get the object to query or `NULL` to query the `this` object the `GParamSpec` for the property to query Gets the expression specifying the object of a property expression. the object expression a property `GtkExpression` Gets the `GParamSpec` specifying the property of a property expression. the `GParamSpec` for the property a property `GtkExpression` `GtkRange` is the common base class for widgets which visualize an adjustment. Widgets that are derived from `GtkRange` include [class@Gtk.Scale] and [class@Gtk.Scrollbar]. Apart from signals for monitoring the parameters of the adjustment, `GtkRange` provides properties and methods for setting a “fill level” on range widgets. See [method@Gtk.Range.set_fill_level]. # Shortcuts and Gestures The `GtkRange` slider is draggable. Holding the <kbd>Shift</kbd> key while dragging, or initiating the drag with a long-press will enable the fine-tuning mode. Get the adjustment which is the “model” object for `GtkRange`. a `GtkAdjustment` a `GtkRange` Gets the current position of the fill level indicator. The current fill level A `GtkRange` Gets whether the `GtkRange` respects text direction. See [method@Gtk.Range.set_flippable]. %TRUE if the range is flippable a `GtkRange` Gets whether the range is inverted. See [method@Gtk.Range.set_inverted]. %TRUE if the range is inverted a `GtkRange` This function returns the area that contains the range’s trough, in coordinates relative to @range's origin. This function is useful mainly for `GtkRange` subclasses. a `GtkRange` return location for the range rectangle Gets whether the range is restricted to the fill level. %TRUE if @range is restricted to the fill level. A `GtkRange` Gets the number of digits to round the value to when it changes. See [signal@Gtk.Range::change-value]. the number of digits to round to a `GtkRange` Gets whether the range displays the fill level graphically. %TRUE if @range shows the fill level. A `GtkRange` This function returns sliders range along the long dimension, in widget->window coordinates. This function is useful mainly for `GtkRange` subclasses. a `GtkRange` return location for the slider's start return location for the slider's end This function is useful mainly for `GtkRange` subclasses. See [method@Gtk.Range.set_slider_size_fixed]. whether the range’s slider has a fixed size. a `GtkRange` Gets the current value of the range. current value of the range. a `GtkRange` Sets the adjustment to be used as the “model” object for the `GtkRange` The adjustment indicates the current range value, the minimum and maximum range values, the step/page increments used for keybindings and scrolling, and the page size. The page size is normally 0 for `GtkScale` and nonzero for `GtkScrollbar`, and indicates the size of the visible area of the widget being scrolled. The page size affects the size of the scrollbar slider. a `GtkRange` a `GtkAdjustment` Set the new position of the fill level indicator. The “fill level” is probably best described by its most prominent use case, which is an indicator for the amount of pre-buffering in a streaming media player. In that use case, the value of the range would indicate the current play position, and the fill level would be the position up to which the file/stream has been downloaded. This amount of prebuffering can be displayed on the range’s trough and is themeable separately from the trough. To enable fill level display, use [method@Gtk.Range.set_show_fill_level]. The range defaults to not showing the fill level. Additionally, it’s possible to restrict the range’s slider position to values which are smaller than the fill level. This is controlled by [method@Gtk.Range.set_restrict_to_fill_level] and is by default enabled. a `GtkRange` the new position of the fill level indicator Sets whether the `GtkRange` respects text direction. If a range is flippable, it will switch its direction if it is horizontal and its direction is %GTK_TEXT_DIR_RTL. See [method@Gtk.Widget.get_direction]. a `GtkRange` %TRUE to make the range flippable Sets the step and page sizes for the range. The step size is used when the user clicks the `GtkScrollbar` arrows or moves a `GtkScale` via arrow keys. The page size is used for example when moving via Page Up or Page Down keys. a `GtkRange` step size page size Sets whether to invert the range. Ranges normally move from lower to higher values as the slider moves from top to bottom or left to right. Inverted ranges have higher values at the top or on the right rather than on the bottom or left. a `GtkRange` %TRUE to invert the range Sets the allowable values in the `GtkRange`. The range value is clamped to be between @min and @max. (If the range has a non-zero page size, it is clamped between @min and @max - page-size.) a `GtkRange` minimum range value maximum range value Sets whether the slider is restricted to the fill level. See [method@Gtk.Range.set_fill_level] for a general description of the fill level concept. A `GtkRange` Whether the fill level restricts slider movement. Sets the number of digits to round the value to when it changes. See [signal@Gtk.Range::change-value]. a `GtkRange` the precision in digits, or -1 Sets whether a graphical fill level is show on the trough. See [method@Gtk.Range.set_fill_level] for a general description of the fill level concept. A `GtkRange` Whether a fill level indicator graphics is shown. Sets whether the range’s slider has a fixed size, or a size that depends on its adjustment’s page size. This function is useful mainly for `GtkRange` subclasses. a `GtkRange` %TRUE to make the slider size constant Sets the current value of the range. If the value is outside the minimum or maximum range values, it will be clamped to fit inside them. The range emits the [signal@Gtk.Range::value-changed] signal if the value changes. a `GtkRange` new value of the range The adjustment that is controlled by the range. The fill level (e.g. prebuffering of a network stream). If %TRUE, the direction in which the slider moves is inverted. Controls whether slider movement is restricted to an upper boundary set by the fill level. The number of digits to round the value to when it changes. See [signal@Gtk.Range::change-value]. Controls whether fill level indicator graphics are displayed on the trough. Emitted before clamping a value, to give the application a chance to adjust the bounds. the value before we clamp Emitted when a scroll action is performed on a range. It allows an application to determine the type of scroll event that occurred and the resultant new value. The application can handle the event itself and return %TRUE to prevent further processing. Or, by returning %FALSE, it can pass the event to other handlers until the default GTK handler is reached. The value parameter is unrounded. An application that overrides the ::change-value signal is responsible for clamping the value to the desired number of decimal digits; the default GTK handler clamps the value based on [property@Gtk.Range:round-digits]. %TRUE to prevent other handlers from being invoked for the signal, %FALSE to propagate the signal further the type of scroll action that was performed the new value resulting from the scroll action Virtual function that moves the slider. Used for keybindings. how to move the slider Emitted when the range value changes. Meta-data to be passed to gtk_recent_manager_add_full() when registering a recently used resource. a UTF-8 encoded string, containing the name of the recently used resource to be displayed, or %NULL; a UTF-8 encoded string, containing a short description of the resource, or %NULL; the MIME type of the resource; the name of the application that is registering this recently used resource; command line used to launch this resource; may contain the “\%f” and “\%u” escape characters which will be expanded to the resource file path and URI respectively when the command line is retrieved; a vector of strings containing groups names; whether this resource should be displayed only by the applications that have registered it or not. `GtkRecentInfo` contains the metadata associated with an item in the recently used files list. Creates a `GAppInfo` for the specified `GtkRecentInfo` In case of error, @error will be set either with a %GTK_RECENT_MANAGER_ERROR or a %G_IO_ERROR the newly created `GAppInfo` a `GtkRecentInfo` the name of the application that should be mapped to a `GAppInfo`; if %NULL is used then the default application for the MIME type is used Checks whether the resource pointed by @info still exists. At the moment this check is done only on resources pointing to local files. %TRUE if the resource exists a `GtkRecentInfo` Gets the time when the resource was added to the recently used resources list. a `GDateTime` for the time when the resource was added a `GtkRecentInfo` Gets the number of days elapsed since the last update of the resource pointed by @info. a positive integer containing the number of days elapsed since the time this resource was last modified a `GtkRecentInfo` Gets the data regarding the application that has registered the resource pointed by @info. If the command line contains any escape characters defined inside the storage specification, they will be expanded. %TRUE if an application with @app_name has registered this resource inside the recently used list, or %FALSE otherwise. The @app_exec string is owned by the `GtkRecentInfo` and should not be modified or freed a `GtkRecentInfo` the name of the application that has registered this item return location for the string containing the command line return location for the number of times this item was registered return location for the time this item was last registered for this application Retrieves the list of applications that have registered this resource. a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. a `GtkRecentInfo` return location for the length of the returned list Gets the (short) description of the resource. the description of the resource. The returned string is owned by the recent manager, and should not be freed. a `GtkRecentInfo` Gets the name of the resource. If none has been defined, the basename of the resource is obtained. the display name of the resource. The returned string is owned by the recent manager, and should not be freed. a `GtkRecentInfo` Retrieves the icon associated to the resource MIME type. a `GIcon` containing the icon a `GtkRecentInfo` Returns all groups registered for the recently used item @info. The array of returned group names will be %NULL terminated, so length might optionally be %NULL. a newly allocated %NULL terminated array of strings. Use g_strfreev() to free it. a `GtkRecentInfo` return location for the number of groups returned Gets the MIME type of the resource. the MIME type of the resource. The returned string is owned by the recent manager, and should not be freed. a `GtkRecentInfo` Gets the time when the meta-data for the resource was last modified. a `GDateTime` for the time when the resource was last modified a `GtkRecentInfo` Gets the value of the “private” flag. Resources in the recently used list that have this flag set to %TRUE should only be displayed by the applications that have registered them. %TRUE if the private flag was found, %FALSE otherwise a `GtkRecentInfo` Computes a valid UTF-8 string that can be used as the name of the item in a menu or list. For example, calling this function on an item that refers to “file:///foo/bar.txt” will yield “bar.txt”. A newly-allocated string in UTF-8 encoding free it with g_free() an `GtkRecentInfo` Gets the URI of the resource. the URI of the resource. The returned string is owned by the recent manager, and should not be freed. a `tkRecentInfo` Gets a displayable version of the resource’s URI. If the resource is local, it returns a local path; if the resource is not local, it returns the UTF-8 encoded content of [method@Gtk.RecentInfo.get_uri]. a newly allocated UTF-8 string containing the resource’s URI or %NULL. Use g_free() when done using it. a `GtkRecentInfo` Gets the time when the meta-data for the resource was last visited. a `GDateTime` for the time when the resource was last visited a `GtkRecentInfo` Checks whether an application registered this resource using @app_name. %TRUE if an application with name @app_name was found, %FALSE otherwise a `GtkRecentInfo` a string containing an application name Checks whether @group_name appears inside the groups registered for the recently used item @info. %TRUE if the group was found a `GtkRecentInfo` name of a group Checks whether the resource is local or not by looking at the scheme of its URI. %TRUE if the resource is local a `GtkRecentInfo` Gets the name of the last application that have registered the recently used resource represented by @info. an application name. Use g_free() to free it. a `GtkRecentInfo` Checks whether two `GtkRecentInfo` point to the same resource. %TRUE if both `GtkRecentInfo` point to the same resource, %FALSE otherwise a `GtkRecentInfo` a `GtkRecentInfo` Increases the reference count of @recent_info by one. the recent info object with its reference count increased by one a `GtkRecentInfo` Decreases the reference count of @info by one. If the reference count reaches zero, @info is deallocated, and the memory freed. a `GtkRecentInfo` `GtkRecentManager` manages and looks up recently used files. Each recently used file is identified by its URI, and has meta-data associated to it, like the names and command lines of the applications that have registered it, the number of time each application has registered the same file, the mime type of the file and whether the file should be displayed only by the applications that have registered it. The recently used files list is per user. `GtkRecentManager` acts like a database of all the recently used files. You can create new `GtkRecentManager` objects, but it is more efficient to use the default manager created by GTK. Adding a new recently used file is as simple as: ```c GtkRecentManager *manager; manager = gtk_recent_manager_get_default (); gtk_recent_manager_add_item (manager, file_uri); ``` The `GtkRecentManager` will try to gather all the needed information from the file itself through GIO. Looking up the meta-data associated with a recently used file given its URI requires calling [method@Gtk.RecentManager.lookup_item]: ```c GtkRecentManager *manager; GtkRecentInfo *info; GError *error = NULL; manager = gtk_recent_manager_get_default (); info = gtk_recent_manager_lookup_item (manager, file_uri, &error); if (error) { g_warning ("Could not find the file: %s", error->message); g_error_free (error); } else { // Use the info object gtk_recent_info_unref (info); } ``` In order to retrieve the list of recently used files, you can use [method@Gtk.RecentManager.get_items], which returns a list of [struct@Gtk.RecentInfo]. Note that the maximum age of the recently used files list is controllable through the [property@Gtk.Settings:gtk-recent-files-max-age] property. Creates a new recent manager object. Recent manager objects are used to handle the list of recently used resources. A `GtkRecentManager` object monitors the recently used resources list, and emits the [signal@Gtk.RecentManager::changed] signal each time something inside the list changes. `GtkRecentManager` objects are expensive: be sure to create them only when needed. You should use [func@Gtk.RecentManager.get_default] instead. A newly created `GtkRecentManager` object Gets a unique instance of `GtkRecentManager` that you can share in your application without caring about memory management. A unique `GtkRecentManager`. Do not ref or unref it. Adds a new resource, pointed by @uri, into the recently used resources list, using the metadata specified inside the `GtkRecentData` passed in @recent_data. The passed URI will be used to identify this resource inside the list. In order to register the new recently used resource, metadata about the resource must be passed as well as the URI; the metadata is stored in a `GtkRecentData`, which must contain the MIME type of the resource pointed by the URI; the name of the application that is registering the item, and a command line to be used when launching the item. Optionally, a `GtkRecentData` might contain a UTF-8 string to be used when viewing the item instead of the last component of the URI; a short description of the item; whether the item should be considered private - that is, should be displayed only by the applications that have registered it. %TRUE if the new item was successfully added to the recently used resources list, %FALSE otherwise a `GtkRecentManager` a valid URI metadata of the resource Adds a new resource, pointed by @uri, into the recently used resources list. This function automatically retrieves some of the needed metadata and setting other metadata to common default values; it then feeds the data to [method@Gtk.RecentManager.add_full]. See [method@Gtk.RecentManager.add_full] if you want to explicitly define the metadata for the resource pointed by @uri. %TRUE if the new item was successfully added to the recently used resources list a `GtkRecentManager` a valid URI Gets the list of recently used resources. a list of newly allocated `GtkRecentInfo objects`. Use [method@Gtk.RecentInfo.unref] on each item inside the list, and then free the list itself using g_list_free(). a `GtkRecentManager` Checks whether there is a recently used resource registered with @uri inside the recent manager. %TRUE if the resource was found, %FALSE otherwise a `GtkRecentManager` a URI Searches for a URI inside the recently used resources list, and returns a `GtkRecentInfo` containing information about the resource like its MIME type, or its display name. a `GtkRecentInfo` containing information about the resource pointed by @uri, or %NULL if the URI was not registered in the recently used resources list. Free with [method@Gtk.RecentInfo.unref]. a `GtkRecentManager` a URI Changes the location of a recently used resource from @uri to @new_uri. Please note that this function will not affect the resource pointed by the URIs, but only the URI used in the recently used resources list. %TRUE on success a `GtkRecentManager` the URI of a recently used resource the new URI of the recently used resource, or %NULL to remove the item pointed by @uri in the list Purges every item from the recently used resources list. the number of items that have been removed from the recently used resources list a `GtkRecentManager` Removes a resource pointed by @uri from the recently used resources list handled by a recent manager. %TRUE if the item pointed by @uri has been successfully removed by the recently used resources list, and %FALSE otherwise a `GtkRecentManager` the URI of the item you wish to remove The full path to the file to be used to store and read the recently used resources list The size of the recently used resources list. Emitted when the current recently used resources manager changes its contents. This can happen either by calling [method@Gtk.RecentManager.add_item] or by another application. `GtkRecentManagerClass` contains only private data. Error codes for `GtkRecentManager` operations the URI specified does not exists in the recently used resources list. the URI specified is not valid. the supplied string is not UTF-8 encoded. no application has registered the specified item. failure while reading the recently used resources file. failure while writing the recently used resources file. unspecified error. Registers an error quark for [class@RecentManager] errors. the error quark Represents a request of a screen object in a given orientation. These are primarily used in container implementations when allocating a natural size for children calling. See [func@distribute_natural_allocation]. A client pointer The minimum size needed for allocation in a given orientation The natural size for allocation in a given orientation A `GtkRequisition` represents the desired size of a widget. See [GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management) for more information. the widget’s desired width the widget’s desired height Allocates a new `GtkRequisition`. The struct is initialized to zero. a new empty `GtkRequisition`. The newly allocated `GtkRequisition` should be freed with [method@Gtk.Requisition.free] Copies a `GtkRequisition`. a copy of @requisition a `GtkRequisition` Frees a `GtkRequisition`. a `GtkRequisition` Predefined values for use as response ids in gtk_dialog_add_button(). All predefined values are negative; GTK leaves values of 0 or greater for application-defined response ids. Returned if an action widget has no response id, or if the dialog gets programmatically hidden or destroyed Generic response id, not used by GTK dialogs Generic response id, not used by GTK dialogs Returned if the dialog is deleted Returned by OK buttons in GTK dialogs Returned by Cancel buttons in GTK dialogs Returned by Close buttons in GTK dialogs Returned by Yes buttons in GTK dialogs Returned by No buttons in GTK dialogs Returned by Apply buttons in GTK dialogs Returned by Help buttons in GTK dialogs A `GtkRevealer` animates the transition of its child from invisible to visible. The style of transition can be controlled with [method@Gtk.Revealer.set_transition_type]. These animations respect the [property@Gtk.Settings:gtk-enable-animations] setting. # CSS nodes `GtkRevealer` has a single CSS node with name revealer. When styling `GtkRevealer` using CSS, remember that it only hides its contents, not itself. That means applied margin, padding and borders will be visible even when the [property@Gtk.Revealer:reveal-child] property is set to %FALSE. # Accessibility `GtkRevealer` uses the %GTK_ACCESSIBLE_ROLE_GROUP role. The child of `GtkRevealer`, if set, is always available in the accessibility tree, regardless of the state of the revealer widget. Creates a new `GtkRevealer`. a newly created `GtkRevealer` Gets the child widget of @revealer. the child widget of @revealer a `GtkRevealer` Returns whether the child is fully revealed. In other words, this returns whether the transition to the revealed state is completed. %TRUE if the child is fully revealed a `GtkRevealer` Returns whether the child is currently revealed. This function returns %TRUE as soon as the transition is to the revealed state is started. To learn whether the child is fully revealed (ie the transition is completed), use [method@Gtk.Revealer.get_child_revealed]. %TRUE if the child is revealed. a `GtkRevealer` Returns the amount of time (in milliseconds) that transitions will take. the transition duration a `GtkRevealer` Gets the type of animation that will be used for transitions in @revealer. the current transition type of @revealer a `GtkRevealer` Sets the child widget of @revealer. a `GtkRevealer` the child widget Tells the `GtkRevealer` to reveal or conceal its child. The transition will be animated with the current transition type of @revealer. a `GtkRevealer` %TRUE to reveal the child Sets the duration that transitions will take. a `GtkRevealer` the new duration, in milliseconds Sets the type of animation that will be used for transitions in @revealer. Available types include various kinds of fades and slides. a `GtkRevealer` the new transition type The child widget. Whether the child is revealed and the animation target reached. Whether the revealer should reveal the child. The animation duration, in milliseconds. The type of animation used to transition. These enumeration values describe the possible transitions when the child of a `GtkRevealer` widget is shown or hidden. No transition Fade in Slide in from the left Slide in from the right Slide in from the bottom Slide in from the top Floop in from the left Floop in from the right Floop in from the bottom Floop in from the top `GtkRoot` is the interface implemented by all widgets that can act as a toplevel widget. The root widget takes care of providing the connection to the windowing system and manages layout, drawing and event delivery for its widget hierarchy. The obvious example of a `GtkRoot` is `GtkWindow`. To get the display to which a `GtkRoot` belongs, use [method@Gtk.Root.get_display]. `GtkRoot` also maintains the location of keyboard focus inside its widget hierarchy, with [method@Gtk.Root.set_focus] and [method@Gtk.Root.get_focus]. Returns the display that this `GtkRoot` is on. the display of @root a `GtkRoot` Retrieves the current focused widget within the root. Note that this is the widget that would have the focus if the root is active; if the root is not focused then `gtk_widget_has_focus (widget)` will be %FALSE for the widget. the currently focused widget a `GtkRoot` If @focus is not the current focus widget, and is focusable, sets it as the focus widget for the root. If @focus is %NULL, unsets the focus widget for the root. To set the focus to a particular widget in the root, it is usually more convenient to use [method@Gtk.Widget.grab_focus] instead of this function. a `GtkRoot` widget to be the new focus widget, or %NULL to unset the focus widget A priority that can be used when adding a `GtkStyleProvider` for application-specific style information. The priority used for default style information that is used in the absence of themes. Note that this is not very useful for providing default styling for custom style classes - themes are likely to override styling provided at this priority with catch-all `* {...}` rules. The priority used for style information provided via `GtkSettings`. This priority is higher than %GTK_STYLE_PROVIDER_PRIORITY_THEME to let settings override themes. The priority used for style information provided by themes. The priority used for the style information from `$XDG_CONFIG_HOME/gtk-4.0/gtk.css`. You should not use priorities higher than this, to give the user the last word. A `GtkScale` is a slider control used to select a numeric value.  To use it, you’ll probably want to investigate the methods on its base class, [class@Gtk.Range], in addition to the methods for `GtkScale` itself. To set the value of a scale, you would normally use [method@Gtk.Range.set_value]. To detect changes to the value, you would normally use the [signal@Gtk.Range::value-changed] signal. Note that using the same upper and lower bounds for the `GtkScale` (through the `GtkRange` methods) will hide the slider itself. This is useful for applications that want to show an undeterminate value on the scale, without changing the layout of the application (such as movie or music players). # GtkScale as GtkBuildable `GtkScale` supports a custom `<marks>` element, which can contain multiple `<mark\>` elements. The “value” and “position” attributes have the same meaning as [method@Gtk.Scale.add_mark] parameters of the same name. If the element is not empty, its content is taken as the markup to show at the mark. It can be translated with the usual ”translatable” and “context” attributes. # Shortcuts and Gestures `GtkPopoverMenu` supports the following keyboard shortcuts: - Arrow keys, <kbd>+</kbd> and <kbd>-</kbd> will increment or decrement by step, or by page when combined with <kbd>Ctrl</kbd>. - <kbd>PgUp</kbd> and <kbd>PgDn</kbd> will increment or decrement by page. - <kbd>Home</kbd> and <kbd>End</kbd> will set the minimum or maximum value. # CSS nodes ``` scale[.fine-tune][.marks-before][.marks-after] ├── [value][.top][.right][.bottom][.left] ├── marks.top │ ├── mark │ ┊ ├── [label] │ ┊ ╰── indicator ┊ ┊ │ ╰── mark ├── marks.bottom │ ├── mark │ ┊ ├── indicator │ ┊ ╰── [label] ┊ ┊ │ ╰── mark ╰── trough ├── [fill] ├── [highlight] ╰── slider ``` `GtkScale` has a main CSS node with name scale and a subnode for its contents, with subnodes named trough and slider. The main node gets the style class .fine-tune added when the scale is in 'fine-tuning' mode. If the scale has an origin (see [method@Gtk.Scale.set_has_origin]), there is a subnode with name highlight below the trough node that is used for rendering the highlighted part of the trough. If the scale is showing a fill level (see [method@Gtk.Range.set_show_fill_level]), there is a subnode with name fill below the trough node that is used for rendering the filled in part of the trough. If marks are present, there is a marks subnode before or after the trough node, below which each mark gets a node with name mark. The marks nodes get either the .top or .bottom style class. The mark node has a subnode named indicator. If the mark has text, it also has a subnode named label. When the mark is either above or left of the scale, the label subnode is the first when present. Otherwise, the indicator subnode is the first. The main CSS node gets the 'marks-before' and/or 'marks-after' style classes added depending on what marks are present. If the scale is displaying the value (see [property@Gtk.Scale:draw-value]), there is subnode with name value. This node will get the .top or .bottom style classes similar to the marks node. # Accessibility `GtkScale` uses the %GTK_ACCESSIBLE_ROLE_SLIDER role. Creates a new `GtkScale`. a new `GtkScale` the scale’s orientation. the [class@Gtk.Adjustment] which sets the range of the scale, or %NULL to create a new adjustment. Creates a new scale widget with a range from @min to @max. The returns scale will have the given orientation and will let the user input a number between @min and @max (including @min and @max) with the increment @step. @step must be nonzero; it’s the distance the slider moves when using the arrow keys to adjust the scale value. Note that the way in which the precision is derived works best if @step is a power of ten. If the resulting precision is not suitable for your needs, use [method@Gtk.Scale.set_digits] to correct it. a new `GtkScale` the scale’s orientation. minimum value maximum value step increment (tick size) used with keyboard shortcuts Obtains the coordinates where the scale will draw the `PangoLayout` representing the text in the scale. Remember when using the `PangoLayout` function you need to convert to and from pixels using `PANGO_PIXELS()` or `PANGO_SCALE`. If the [property@Gtk.Scale:draw-value] property is %FALSE, the return values are undefined. a `GtkScale` location to store X offset of layout location to store Y offset of layout Adds a mark at @value. A mark is indicated visually by drawing a tick mark next to the scale, and GTK makes it easy for the user to position the scale exactly at the marks value. If @markup is not %NULL, text is shown next to the tick mark. To remove marks from a scale, use [method@Gtk.Scale.clear_marks]. a `GtkScale` the value at which the mark is placed, must be between the lower and upper limits of the scales’ adjustment where to draw the mark. For a horizontal scale, %GTK_POS_TOP and %GTK_POS_LEFT are drawn above the scale, anything else below. For a vertical scale, %GTK_POS_LEFT and %GTK_POS_TOP are drawn to the left of the scale, anything else to the right. Text to be shown at the mark, using Pango markup Removes any marks that have been added. a `GtkScale` Gets the number of decimal places that are displayed in the value. the number of decimal places that are displayed a `GtkScale` Returns whether the current value is displayed as a string next to the slider. whether the current value is displayed as a string a `GtkScale` Returns whether the scale has an origin. %TRUE if the scale has an origin. a `GtkScale` Gets the `PangoLayout` used to display the scale. The returned object is owned by the scale so does not need to be freed by the caller. the [class@Pango.Layout] for this scale, or %NULL if the [property@Gtk.Scale:draw-value] property is %FALSE. A `GtkScale` Obtains the coordinates where the scale will draw the `PangoLayout` representing the text in the scale. Remember when using the `PangoLayout` function you need to convert to and from pixels using `PANGO_PIXELS()` or `PANGO_SCALE`. If the [property@Gtk.Scale:draw-value] property is %FALSE, the return values are undefined. a `GtkScale` location to store X offset of layout location to store Y offset of layout Gets the position in which the current value is displayed. the position in which the current value is displayed a `GtkScale` Sets the number of decimal places that are displayed in the value. Also causes the value of the adjustment to be rounded to this number of digits, so the retrieved value matches the displayed one, if [property@Gtk.Scale:draw-value] is %TRUE when the value changes. If you want to enforce rounding the value when [property@Gtk.Scale:draw-value] is %FALSE, you can set [property@Gtk.Range:round-digits] instead. Note that rounding to a small number of digits can interfere with the smooth autoscrolling that is built into `GtkScale`. As an alternative, you can use [method@Gtk.Scale.set_format_value_func] to format the displayed value yourself. a `GtkScale` the number of decimal places to display, e.g. use 1 to display 1.0, 2 to display 1.00, etc Specifies whether the current value is displayed as a string next to the slider. a `GtkScale` %TRUE to draw the value @func allows you to change how the scale value is displayed. The given function will return an allocated string representing @value. That string will then be used to display the scale's value. If #NULL is passed as @func, the value will be displayed on its own, rounded according to the value of the [property@Gtk.Scale:digits] property. a `GtkScale` function that formats the value user data to pass to @func destroy function for @user_data Sets whether the scale has an origin. If [property@Gtk.Scale:has-origin] is set to %TRUE (the default), the scale will highlight the part of the trough between the origin (bottom or left side) and the current value. a `GtkScale` %TRUE if the scale has an origin Sets the position in which the current value is displayed. a `GtkScale` the position in which the current value is displayed The number of decimal places that are displayed in the value. Whether the current value is displayed as a string next to the slider. Whether the scale has an origin. The position in which the current value is displayed. `GtkScaleButton` provides a button which pops up a scale widget. This kind of widget is commonly used for volume controls in multimedia applications, and GTK provides a [class@Gtk.VolumeButton] subclass that is tailored for this use case. # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.ScaleButton::popup] # CSS nodes ``` scalebutton.scale ╰── button.toggle ╰── <icon> ``` `GtkScaleButton` has a single CSS node with name scalebutton and `.scale` style class, and contains a `button` node with a `.toggle` style class. Creates a `GtkScaleButton`. The new scale button has a range between @min and @max, with a stepping of @step. a new `GtkScaleButton` the minimum value of the scale (usually 0) the maximum value of the scale (usually 100) the stepping of value when a scroll-wheel event, or up/down arrow event occurs (usually 2) a %NULL-terminated array of icon names, or %NULL if you want to set the list later with gtk_scale_button_set_icons() Queries a `GtkScaleButton` and returns its current state. Returns %TRUE if the scale button is pressed in and %FALSE if it is raised. whether the button is pressed a `GtkScaleButton` Gets the `GtkAdjustment` associated with the `GtkScaleButton`’s scale. See [method@Gtk.Range.get_adjustment] for details. the adjustment associated with the scale a `GtkScaleButton` Returns whether the button has a frame. %TRUE if the button has a frame a `GtkScaleButton` Retrieves the minus button of the `GtkScaleButton`. the minus button of the `GtkScaleButton` a `GtkScaleButton` Retrieves the plus button of the `GtkScaleButton.` the plus button of the `GtkScaleButton` a `GtkScaleButton` Retrieves the popup of the `GtkScaleButton`. the popup of the `GtkScaleButton` a `GtkScaleButton` Gets the current value of the scale button. current value of the scale button a `GtkScaleButton` Sets the `GtkAdjustment` to be used as a model for the `GtkScaleButton`’s scale. See [method@Gtk.Range.set_adjustment] for details. a `GtkScaleButton` a `GtkAdjustment` Sets the style of the button. a `GtkScaleButton` whether the button should have a visible frame Sets the icons to be used by the scale button. a `GtkScaleButton` a %NULL-terminated array of icon names Sets the current value of the scale. If the value is outside the minimum or maximum range values, it will be clamped to fit inside them. The scale button emits the [signal@Gtk.ScaleButton::value-changed] signal if the value changes. a `GtkScaleButton` new value of the scale button If the scale button should be pressed in. The `GtkAdjustment` that is used as the model. If the scale button has a frame. The names of the icons to be used by the scale button. The first item in the array will be used in the button when the current value is the lowest value, the second item for the highest value. All the subsequent icons will be used for all the other values, spread evenly over the range of values. If there's only one icon name in the @icons array, it will be used for all the values. If only two icon names are in the @icons array, the first one will be used for the bottom 50% of the scale, and the second one for the top 50%. It is recommended to use at least 3 icons so that the `GtkScaleButton` reflects the current value of the scale better for the users. The value of the scale. Emitted to dismiss the popup. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Escape</kbd>. Emitted to popup the scale widget. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Space</kbd>, <kbd>Enter</kbd> and <kbd>Return</kbd>. Emitted when the value field has changed. the new value a `GtkScale` location to store X offset of layout location to store Y offset of layout Function that formats the value of a scale. See [method@Gtk.Scale.set_format_value_func]. A newly allocated string describing a textual representation of the given numerical value. The `GtkScale` The numeric value to format user data The `GtkScrollInfo` can be used to provide more accurate data on how a scroll operation should be performed. Scrolling functions usually allow passing a %NULL scroll info which will cause the default values to be used and just scroll the element into view. Creates a new scroll info for scrolling an element into view. A new scroll info Checks if horizontal scrolling is enabled. %TRUE if horizontal scrolling is enabled. a `GtkScrollInfo` Checks if vertical scrolling is enabled. %TRUE if vertical scrolling is enabled. a `GtkScrollInfo` Increases the reference count of a `GtkScrollInfo` by one. the passed in `GtkScrollInfo`. a `GtkScrollInfo` Turns horizontal scrolling on or off. a `GtkScrollInfo` if scrolling in the horizontal direction should happen Turns vertical scrolling on or off. a `GtkScrollInfo` if scrolling in the vertical direction should happen Decreases the reference count of a `GtkScrollInfo` by one. If the resulting reference count is zero, frees the self. a `GtkScrollInfo` Passed as argument to various keybinding signals. Scroll in steps. Scroll by pages. Scroll to ends. Scroll in horizontal steps. Scroll by horizontal pages. Scroll to the horizontal ends. Scrolling types. No scrolling. Jump to new location. Step backward. Step forward. Page backward. Page forward. Step up. Step down. Page up. Page down. Step to the left. Step to the right. Page to the left. Page to the right. Scroll to start. Scroll to end. `GtkScrollable` is an interface for widgets with native scrolling ability. To implement this interface you should override the [property@Gtk.Scrollable:hadjustment] and [property@Gtk.Scrollable:vadjustment] properties. ## Creating a scrollable widget All scrollable widgets should do the following. - When a parent widget sets the scrollable child widget’s adjustments, the widget should connect to the [signal@Gtk.Adjustment::value-changed] signal. The child widget should then populate the adjustments’ properties as soon as possible, which usually means queueing an allocation right away and populating the properties in the [vfunc@Gtk.Widget.size_allocate] implementation. - Because its preferred size is the size for a fully expanded widget, the scrollable widget must be able to cope with underallocations. This means that it must accept any value passed to its [vfunc@Gtk.Widget.size_allocate] implementation. - When the parent allocates space to the scrollable child widget, the widget must ensure the adjustments’ property values are correct and up to date, for example using [method@Gtk.Adjustment.configure]. - When any of the adjustments emits the [signal@Gtk.Adjustment::value-changed] signal, the scrollable widget should scroll its contents. Returns the size of a non-scrolling border around the outside of the scrollable. An example for this would be treeview headers. GTK can use this information to display overlaid graphics, like the overshoot indication, at the right position. %TRUE if @border has been set a `GtkScrollable` return location for the results Returns the size of a non-scrolling border around the outside of the scrollable. An example for this would be treeview headers. GTK can use this information to display overlaid graphics, like the overshoot indication, at the right position. %TRUE if @border has been set a `GtkScrollable` return location for the results Retrieves the `GtkAdjustment` used for horizontal scrolling. horizontal `GtkAdjustment`. a `GtkScrollable` Gets the horizontal `GtkScrollablePolicy`. The horizontal `GtkScrollablePolicy`. a `GtkScrollable` Retrieves the `GtkAdjustment` used for vertical scrolling. vertical `GtkAdjustment`. a `GtkScrollable` Gets the vertical `GtkScrollablePolicy`. The vertical `GtkScrollablePolicy`. a `GtkScrollable` Sets the horizontal adjustment of the `GtkScrollable`. a `GtkScrollable` a `GtkAdjustment` Sets the `GtkScrollablePolicy`. The policy determines whether horizontal scrolling should start below the minimum width or below the natural width. a `GtkScrollable` the horizontal `GtkScrollablePolicy` Sets the vertical adjustment of the `GtkScrollable`. a `GtkScrollable` a `GtkAdjustment` Sets the `GtkScrollablePolicy`. The policy determines whether vertical scrolling should start below the minimum height or below the natural height. a `GtkScrollable` the vertical `GtkScrollablePolicy` Horizontal `GtkAdjustment` of the scrollable widget. This adjustment is shared between the scrollable widget and its parent. Determines when horizontal scrolling should start. Vertical `GtkAdjustment` of the scrollable widget. This adjustment is shared between the scrollable widget and its parent. Determines when vertical scrolling should start. %TRUE if @border has been set a `GtkScrollable` return location for the results Defines the policy to be used in a scrollable widget when updating the scrolled window adjustments in a given orientation. Scrollable adjustments are based on the minimum size Scrollable adjustments are based on the natural size The `GtkScrollbar` widget is a horizontal or vertical scrollbar.  Its position and movement are controlled by the adjustment that is passed to or created by [ctor@Gtk.Scrollbar.new]. See [class@Gtk.Adjustment] for more details. The [property@Gtk.Adjustment:value] field sets the position of the thumb and must be between [property@Gtk.Adjustment:lower] and [property@Gtk.Adjustment:upper] - [property@Gtk.Adjustment:page-size]. The [property@Gtk.Adjustment:page-size] represents the size of the visible scrollable area. The fields [property@Gtk.Adjustment:step-increment] and [property@Gtk.Adjustment:page-increment] fields are added to or subtracted from the [property@Gtk.Adjustment:value] when the user asks to move by a step (using e.g. the cursor arrow keys) or by a page (using e.g. the Page Down/Up keys). # CSS nodes ``` scrollbar ╰── range[.fine-tune] ╰── trough ╰── slider ``` `GtkScrollbar` has a main CSS node with name scrollbar and a subnode for its contents. The main node gets the .horizontal or .vertical style classes applied, depending on the scrollbar's orientation. The range node gets the style class .fine-tune added when the scrollbar is in 'fine-tuning' mode. Other style classes that may be added to scrollbars inside [class@Gtk.ScrolledWindow] include the positional classes (.left, .right, .top, .bottom) and style classes related to overlay scrolling (.overlay-indicator, .dragging, .hovering). # Accessibility `GtkScrollbar` uses the %GTK_ACCESSIBLE_ROLE_SCROLLBAR role. Creates a new scrollbar with the given orientation. the new `GtkScrollbar`. the scrollbar’s orientation. the [class@Gtk.Adjustment] to use, or %NULL to create a new adjustment. Returns the scrollbar's adjustment. the scrollbar's adjustment a `GtkScrollbar` Makes the scrollbar use the given adjustment. a `GtkScrollbar` the adjustment to set The `GtkAdjustment` controlled by this scrollbar. `GtkScrolledWindow` is a container that makes its child scrollable. It does so using either internally added scrollbars or externally associated adjustments, and optionally draws a frame around the child. Widgets with native scrolling support, i.e. those whose classes implement the [iface@Gtk.Scrollable] interface, are added directly. For other types of widget, the class [class@Gtk.Viewport] acts as an adaptor, giving scrollability to other widgets. [method@Gtk.ScrolledWindow.set_child] intelligently accounts for whether or not the added child is a `GtkScrollable`. If it isn’t, then it wraps the child in a `GtkViewport`. Therefore, you can just add any child widget and not worry about the details. If [method@Gtk.ScrolledWindow.set_child] has added a `GtkViewport` for you, it will be automatically removed when you unset the child. Unless [property@Gtk.ScrolledWindow:hscrollbar-policy] and [property@Gtk.ScrolledWindow:vscrollbar-policy] are %GTK_POLICY_NEVER or %GTK_POLICY_EXTERNAL, `GtkScrolledWindow` adds internal `GtkScrollbar` widgets around its child. The scroll position of the child, and if applicable the scrollbars, is controlled by the [property@Gtk.ScrolledWindow:hadjustment] and [property@Gtk.ScrolledWindow:vadjustment] that are associated with the `GtkScrolledWindow`. See the docs on [class@Gtk.Scrollbar] for the details, but note that the “step_increment” and “page_increment” fields are only effective if the policy causes scrollbars to be present. If a `GtkScrolledWindow` doesn’t behave quite as you would like, or doesn’t have exactly the right layout, it’s very possible to set up your own scrolling with `GtkScrollbar` and for example a `GtkGrid`. # Touch support `GtkScrolledWindow` has built-in support for touch devices. When a touchscreen is used, swiping will move the scrolled window, and will expose 'kinetic' behavior. This can be turned off with the [property@Gtk.ScrolledWindow:kinetic-scrolling] property if it is undesired. `GtkScrolledWindow` also displays visual 'overshoot' indication when the content is pulled beyond the end, and this situation can be captured with the [signal@Gtk.ScrolledWindow::edge-overshot] signal. If no mouse device is present, the scrollbars will overlaid as narrow, auto-hiding indicators over the content. If traditional scrollbars are desired although no mouse is present, this behaviour can be turned off with the [property@Gtk.ScrolledWindow:overlay-scrolling] property. # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.ScrolledWindow::scroll-child] # CSS nodes `GtkScrolledWindow` has a main CSS node with name scrolledwindow. It gets a .frame style class added when [property@Gtk.ScrolledWindow:has-frame] is %TRUE. It uses subnodes with names overshoot and undershoot to draw the overflow and underflow indications. These nodes get the .left, .right, .top or .bottom style class added depending on where the indication is drawn. `GtkScrolledWindow` also sets the positional style classes (.left, .right, .top, .bottom) and style classes related to overlay scrolling (.overlay-indicator, .dragging, .hovering) on its scrollbars. If both scrollbars are visible, the area where they meet is drawn with a subnode named junction. # Accessibility Until GTK 4.10, `GtkScrolledWindow` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. Starting from GTK 4.12, `GtkScrolledWindow` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. Creates a new scrolled window. a new scrolled window Gets the child widget of @scrolled_window. If the scrolled window automatically added a [class@Gtk.Viewport], this function will return the viewport widget, and you can retrieve its child using [method@Gtk.Viewport.get_child]. the child widget of @scrolled_window a `GtkScrolledWindow` Returns the horizontal scrollbar’s adjustment. This is the adjustment used to connect the horizontal scrollbar to the child widget’s horizontal scroll functionality. the horizontal `GtkAdjustment` a `GtkScrolledWindow` Gets whether the scrolled window draws a frame. %TRUE if the @scrolled_window has a frame a `GtkScrolledWindow` Returns the horizontal scrollbar of @scrolled_window. the horizontal scrollbar of the scrolled window. a `GtkScrolledWindow` Returns the specified kinetic scrolling behavior. the scrolling behavior flags. a `GtkScrolledWindow` Returns the maximum content height set. the maximum content height, or -1 a `GtkScrolledWindow` Returns the maximum content width set. the maximum content width, or -1 a `GtkScrolledWindow` Gets the minimal content height of @scrolled_window. the minimal content height a `GtkScrolledWindow` Gets the minimum content width of @scrolled_window. the minimum content width a `GtkScrolledWindow` Returns whether overlay scrolling is enabled for this scrolled window. %TRUE if overlay scrolling is enabled a `GtkScrolledWindow` Gets the placement of the contents with respect to the scrollbars. the current placement value. a `GtkScrolledWindow` Retrieves the current policy values for the horizontal and vertical scrollbars. See [method@Gtk.ScrolledWindow.set_policy]. a `GtkScrolledWindow` location to store the policy for the horizontal scrollbar location to store the policy for the vertical scrollbar Reports whether the natural height of the child will be calculated and propagated through the scrolled window’s requested natural height. whether natural height propagation is enabled. a `GtkScrolledWindow` Reports whether the natural width of the child will be calculated and propagated through the scrolled window’s requested natural width. whether natural width propagation is enabled. a `GtkScrolledWindow` Returns the vertical scrollbar’s adjustment. This is the adjustment used to connect the vertical scrollbar to the child widget’s vertical scroll functionality. the vertical `GtkAdjustment` a `GtkScrolledWindow` Returns the vertical scrollbar of @scrolled_window. the vertical scrollbar of the scrolled window. a `GtkScrolledWindow` Sets the child widget of @scrolled_window. If @child does not implement the [iface@Gtk.Scrollable] interface, the scrolled window will add @child to a [class@Gtk.Viewport] instance and then add the viewport as its child widget. a `GtkScrolledWindow` the child widget Sets the `GtkAdjustment` for the horizontal scrollbar. a `GtkScrolledWindow` the `GtkAdjustment` to use, or %NULL to create a new one Changes the frame drawn around the contents of @scrolled_window. a `GtkScrolledWindow` whether to draw a frame around scrolled window contents Turns kinetic scrolling on or off. Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN. a `GtkScrolledWindow` %TRUE to enable kinetic scrolling Sets the maximum height that @scrolled_window should keep visible. The @scrolled_window will grow up to this height before it starts scrolling the content. It is a programming error to set the maximum content height to a value smaller than [property@Gtk.ScrolledWindow:min-content-height]. a `GtkScrolledWindow` the maximum content height Sets the maximum width that @scrolled_window should keep visible. The @scrolled_window will grow up to this width before it starts scrolling the content. It is a programming error to set the maximum content width to a value smaller than [property@Gtk.ScrolledWindow:min-content-width]. a `GtkScrolledWindow` the maximum content width Sets the minimum height that @scrolled_window should keep visible. Note that this can and (usually will) be smaller than the minimum size of the content. It is a programming error to set the minimum content height to a value greater than [property@Gtk.ScrolledWindow:max-content-height]. a `GtkScrolledWindow` the minimal content height Sets the minimum width that @scrolled_window should keep visible. Note that this can and (usually will) be smaller than the minimum size of the content. It is a programming error to set the minimum content width to a value greater than [property@Gtk.ScrolledWindow:max-content-width]. a `GtkScrolledWindow` the minimal content width Enables or disables overlay scrolling for this scrolled window. a `GtkScrolledWindow` whether to enable overlay scrolling Sets the placement of the contents with respect to the scrollbars for the scrolled window. The default is %GTK_CORNER_TOP_LEFT, meaning the child is in the top left, with the scrollbars underneath and to the right. Other values in [enum@Gtk.CornerType] are %GTK_CORNER_TOP_RIGHT, %GTK_CORNER_BOTTOM_LEFT, and %GTK_CORNER_BOTTOM_RIGHT. See also [method@Gtk.ScrolledWindow.get_placement] and [method@Gtk.ScrolledWindow.unset_placement]. a `GtkScrolledWindow` position of the child window Sets the scrollbar policy for the horizontal and vertical scrollbars. The policy determines when the scrollbar should appear; it is a value from the [enum@Gtk.PolicyType] enumeration. If %GTK_POLICY_ALWAYS, the scrollbar is always present; if %GTK_POLICY_NEVER, the scrollbar is never present; if %GTK_POLICY_AUTOMATIC, the scrollbar is present only if needed (that is, if the slider part of the bar would be smaller than the trough — the display is larger than the page size). a `GtkScrolledWindow` policy for horizontal bar policy for vertical bar Sets whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height. a `GtkScrolledWindow` whether to propagate natural height Sets whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width. a `GtkScrolledWindow` whether to propagate natural width Sets the `GtkAdjustment` for the vertical scrollbar. a `GtkScrolledWindow` the `GtkAdjustment` to use, or %NULL to create a new one Unsets the placement of the contents with respect to the scrollbars. If no window placement is set for a scrolled window, it defaults to %GTK_CORNER_TOP_LEFT. a `GtkScrolledWindow` The child widget. When setting this property, if the child widget does not implement [iface@Gtk.Scrollable], the scrolled window will add the child to a [class@Gtk.Viewport] and then set the viewport as the child. The `GtkAdjustment` for the horizontal position. Whether to draw a frame around the contents. When the horizontal scrollbar is displayed. Use [method@Gtk.ScrolledWindow.set_policy] to set this property. Whether kinetic scrolling is enabled or not. Kinetic scrolling only applies to devices with source %GDK_SOURCE_TOUCHSCREEN. The maximum content height of @scrolled_window. The maximum content width of @scrolled_window. The minimum content height of @scrolled_window. The minimum content width of @scrolled_window. Whether overlay scrolling is enabled or not. If it is, the scrollbars are only added as traditional widgets when a mouse is present. Otherwise, they are overlaid on top of the content, as narrow indicators. Note that overlay scrolling can also be globally disabled, with the [property@Gtk.Settings:gtk-overlay-scrolling] setting. Whether the natural height of the child should be calculated and propagated through the scrolled window’s requested natural height. This is useful in cases where an attempt should be made to allocate exactly enough space for the natural size of the child. Whether the natural width of the child should be calculated and propagated through the scrolled window’s requested natural width. This is useful in cases where an attempt should be made to allocate exactly enough space for the natural size of the child. The `GtkAdjustment` for the vertical position. When the vertical scrollbar is displayed. Use [method@Gtk.ScrolledWindow.set_policy] to set this property. Where the contents are located with respect to the scrollbars. Emitted whenever user initiated scrolling makes the scrolled window firmly surpass the limits defined by the adjustment in that orientation. A similar behavior without edge resistance is provided by the [signal@Gtk.ScrolledWindow::edge-reached] signal. Note: The @pos argument is LTR/RTL aware, so callers should be aware too if intending to provide behavior on horizontal edges. edge side that was hit Emitted whenever user-initiated scrolling makes the scrolled window exactly reach the lower or upper limits defined by the adjustment in that orientation. A similar behavior with edge resistance is provided by the [signal@Gtk.ScrolledWindow::edge-overshot] signal. Note: The @pos argument is LTR/RTL aware, so callers should be aware too if intending to provide behavior on horizontal edges. edge side that was reached Emitted when focus is moved away from the scrolled window by a keybinding. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>Tab</kbd> to move forward and <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Tab</kbd>` to move backward. either %GTK_DIR_TAB_FORWARD or %GTK_DIR_TAB_BACKWARD Emitted when a keybinding that scrolls is pressed. This is a [keybinding signal](class.SignalAction.html). The horizontal or vertical adjustment is updated which triggers a signal that the scrolled window’s child may listen to and scroll itself. whether the scroll happened a `GtkScrollType` describing how much to scroll whether the keybinding scrolls the child horizontally or not `GtkSearchBar` is a container made to have a search entry.  It can also contain additional widgets, such as drop-down menus, or buttons. The search bar would appear when a search is started through typing on the keyboard, or the application’s search mode is toggled on. For keyboard presses to start a search, the search bar must be told of a widget to capture key events from through [method@Gtk.SearchBar.set_key_capture_widget]. This widget will typically be the top-level window, or a parent container of the search bar. Common shortcuts such as Ctrl+F should be handled as an application action, or through the menu items. You will also need to tell the search bar about which entry you are using as your search entry using [method@Gtk.SearchBar.connect_entry]. ## Creating a search bar The following example shows you how to create a more complex search entry. [A simple example](https://gitlab.gnome.org/GNOME/gtk/tree/main/examples/search-bar.c) # Shortcuts and Gestures `GtkSearchBar` supports the following keyboard shortcuts: - <kbd>Escape</kbd> hides the search bar. # CSS nodes ``` searchbar ╰── revealer ╰── box ├── [child] ╰── [button.close] ``` `GtkSearchBar` has a main CSS node with name searchbar. It has a child node with name revealer that contains a node with name box. The box node contains both the CSS node of the child widget as well as an optional button node which gets the .close style class applied. # Accessibility `GtkSearchBar` uses the %GTK_ACCESSIBLE_ROLE_SEARCH role. Creates a `GtkSearchBar`. You will need to tell it about which widget is going to be your text entry using [method@Gtk.SearchBar.connect_entry]. a new `GtkSearchBar` Connects the `GtkEditable` widget passed as the one to be used in this search bar. The entry should be a descendant of the search bar. Calling this function manually is only required if the entry isn’t the direct child of the search bar (as in our main example). a `GtkSearchBar` a `GtkEditable` Gets the child widget of @bar. the child widget of @bar a `GtkSearchBar` Gets the widget that @bar is capturing key events from. The key capture widget. a `GtkSearchBar` Returns whether the search mode is on or off. whether search mode is toggled on a `GtkSearchBar` Returns whether the close button is shown. whether the close button is shown a `GtkSearchBar` Sets the child widget of @bar. a `GtkSearchBar` the child widget Sets @widget as the widget that @bar will capture key events from. If key events are handled by the search bar, the bar will be shown, and the entry populated with the entered text. Note that despite the name of this function, the events are only 'captured' in the bubble phase, which means that editable child widgets of @widget will receive text input before it gets captured. If that is not desired, you can capture and forward the events yourself with [method@Gtk.EventControllerKey.forward]. a `GtkSearchBar` a `GtkWidget` Switches the search mode on or off. a `GtkSearchBar` the new state of the search mode Shows or hides the close button. Applications that already have a “search” toggle button should not show a close button in their search bar, as it duplicates the role of the toggle button. a `GtkSearchBar` whether the close button will be shown or not The child widget. The key capture widget. Whether the search mode is on and the search bar shown. Whether to show the close button in the search bar. `GtkSearchEntry` is an entry widget that has been tailored for use as a search entry. The main API for interacting with a `GtkSearchEntry` as entry is the `GtkEditable` interface.  It will show an inactive symbolic “find” icon when the search entry is empty, and a symbolic “clear” icon when there is text. Clicking on the “clear” icon will empty the search entry. To make filtering appear more reactive, it is a good idea to not react to every change in the entry text immediately, but only after a short delay. To support this, `GtkSearchEntry` emits the [signal@Gtk.SearchEntry::search-changed] signal which can be used instead of the [signal@Gtk.Editable::changed] signal. The [signal@Gtk.SearchEntry::previous-match], [signal@Gtk.SearchEntry::next-match] and [signal@Gtk.SearchEntry::stop-search] signals can be used to implement moving between search results and ending the search. Often, `GtkSearchEntry` will be fed events by means of being placed inside a [class@Gtk.SearchBar]. If that is not the case, you can use [method@Gtk.SearchEntry.set_key_capture_widget] to let it capture key input from another widget. `GtkSearchEntry` provides only minimal API and should be used with the [iface@Gtk.Editable] API. ## Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.SearchEntry::activate] - [signal@Gtk.SearchEntry::next-match] - [signal@Gtk.SearchEntry::previous-match] - [signal@Gtk.SearchEntry::stop-search] ## CSS Nodes ``` entry.search ╰── text ``` `GtkSearchEntry` has a single CSS node with name entry that carries a `.search` style class, and the text node is a child of that. ## Accessibility `GtkSearchEntry` uses the %GTK_ACCESSIBLE_ROLE_SEARCH_BOX role. Creates a `GtkSearchEntry`. a new `GtkSearchEntry` Gets the input purpose for @entry. The input hints a `GtkSearchEntry` Gets the input purpose of @entry. The input hints a `GtkSearchEntry` Gets the widget that @entry is capturing key events from. The key capture widget. a `GtkSearchEntry` Gets the placeholder text associated with @entry. The placeholder text. a `GtkSearchEntry` Get the delay to be used between the last keypress and the [signal@Gtk.SearchEntry::search-changed] signal being emitted. a delay in milliseconds. a `GtkSearchEntry` Sets the input hints for @entry. a `GtkSearchEntry` the new input hints Sets the input purpose of @entry. a `GtkSearchEntry` the new input purpose Sets @widget as the widget that @entry will capture key events from. Key events are consumed by the search entry to start or continue a search. If the entry is part of a `GtkSearchBar`, it is preferable to call [method@Gtk.SearchBar.set_key_capture_widget] instead, which will reveal the entry in addition to triggering the search entry. Note that despite the name of this function, the events are only 'captured' in the bubble phase, which means that editable child widgets of @widget will receive text input before it gets captured. If that is not desired, you can capture and forward the events yourself with [method@Gtk.EventControllerKey.forward]. a `GtkSearchEntry` a `GtkWidget` Sets the placeholder text associated with @entry. a `GtkSearchEntry` the text to set as a placeholder Set the delay to be used between the last keypress and the [signal@Gtk.SearchEntry::search-changed] signal being emitted. a `GtkSearchEntry` a delay in milliseconds Whether to activate the default widget when Enter is pressed. The hints about input for the `GtkSearchEntry` used to alter the behaviour of input methods. The purpose for the `GtkSearchEntry` input used to alter the behaviour of input methods. The text that will be displayed in the `GtkSearchEntry` when it is empty and unfocused. The delay in milliseconds from last keypress to the search changed signal. Emitted when the entry is activated. The keybindings for this signal are all forms of the <kbd>Enter</kbd> key. Emitted when the user initiates a move to the next match for the current search string. This is a [keybinding signal](class.SignalAction.html). Applications should connect to it, to implement moving between matches. The default bindings for this signal is <kbd>Ctrl</kbd>+<kbd>g</kbd>. Emitted when the user initiates a move to the previous match for the current search string. This is a [keybinding signal](class.SignalAction.html). Applications should connect to it, to implement moving between matches. The default bindings for this signal is <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>g</kbd>. Emitted with a delay. The length of the delay can be changed with the [property@Gtk.SearchEntry:search-delay] property. Emitted when the user initiated a search on the entry. Emitted when the user stops a search via keyboard input. This is a [keybinding signal](class.SignalAction.html). Applications should connect to it, to implement hiding the search entry in this case. The default bindings for this signal is <kbd>Escape</kbd>. `GtkSectionModel` is an interface that adds support for sections to list models. A `GtkSectionModel` groups successive items into so-called sections. List widgets like `GtkListView` and `GtkGridView` then allow displaying section headers for these sections by installing a header factory. Many GTK list models support sections inherently, or they pass through the sections of a model they are wrapping. When the section groupings of a model change, the model will emit the [signal@Gtk.SectionModel::sections-changed] signal by calling the [method@Gtk.SectionModel.sections_changed] function. All sections in the given range then need to be queried again. The [signal@Gio.ListModel::items-changed] signal has the same effect, all sections in that range are invalidated, too. Query the section that covers the given position. The number of items in the section can be computed by `out_end - out_start`. If the position is larger than the number of items, a single range from n_items to G_MAXUINT will be returned. a `GtkSectionModel` the position of the item to query the position of the first item in the section the position of the first item not part of the section anymore. Query the section that covers the given position. The number of items in the section can be computed by `out_end - out_start`. If the position is larger than the number of items, a single range from n_items to G_MAXUINT will be returned. a `GtkSectionModel` the position of the item to query the position of the first item in the section the position of the first item not part of the section anymore. This function emits the [signal@Gtk.SectionModel::sections-changed] signal to notify about changes to sections. It must cover all positions that used to be a section start or that are now a section start. It does not have to cover all positions for which the section has changed. The [signal@Gio.ListModel::items-changed] implies the effect of the [signal@Gtk.SectionModel::sections-changed] signal for all the items it covers. It is recommended that when changes to the items cause section changes in a larger range, that the larger range is included in the emission of the [signal@Gio.ListModel::items-changed] instead of emitting two signals. a `GtkSectionModel` the first changed item the number of changed items Emitted when the start-of-section state of some of the items in @model changes. Note that this signal does not specify the new section state of the items, they need to be queried manually. It is also not necessary for a model to change the section state of any of the items in the section model, though it would be rather useless to emit such a signal. The [signal@Gio.ListModel::items-changed] implies the effect of the [signal@Gtk.SectionModel::sections-changed] signal for all the items it covers. The first item that may have changed number of items with changes The list of virtual functions for the `GtkSectionModel` interface. No function must be implemented, but unless `GtkSectionModel::get_section()` is implemented, the whole model will just be a single section. Return the section that covers the given position. If the position is outside the number of items, returns a single range from n_items to G_MAXUINT a `GtkSectionModel` the position of the item to query the position of the first item in the section the position of the first item not part of the section anymore. `GtkSelectionFilterModel` is a list model that presents the selection from a `GtkSelectionModel`. Creates a new `GtkSelectionFilterModel` that will include the selected items from the underlying selection model. a new `GtkSelectionFilterModel` the selection model to filter Gets the model currently filtered or %NULL if none. The model that gets filtered a `GtkSelectionFilterModel` Sets the model to be filtered. Note that GTK makes no effort to ensure that @model conforms to the item type of @self. It assumes that the caller knows what they are doing and have set up an appropriate filter to ensure that item types match. a `GtkSelectionFilterModel` The model to be filtered The type of items. See [method@Gio.ListModel.get_item_type]. The model being filtered. The number of items. See [method@Gio.ListModel.get_n_items]. Used to control what selections users are allowed to make. No selection is possible. Zero or one element may be selected. Exactly one element is selected. In some circumstances, such as initially or during a search operation, it’s possible for no element to be selected with %GTK_SELECTION_BROWSE. What is really enforced is that the user can’t deselect a currently selected element except by selecting another element. Any number of elements may be selected. The Ctrl key may be used to enlarge the selection, and Shift key to select between the focus and the child pointed to. Some widgets may also allow Click-drag to select a range of elements. `GtkSelectionModel` is an interface that add support for selection to list models. This support is then used by widgets using list models to add the ability to select and unselect various items. GTK provides default implementations of the most common selection modes such as [class@Gtk.SingleSelection], so you will only need to implement this interface if you want detailed control about how selections should be handled. A `GtkSelectionModel` supports a single boolean per item indicating if an item is selected or not. This can be queried via [method@Gtk.SelectionModel.is_selected]. When the selected state of one or more items changes, the model will emit the [signal@Gtk.SelectionModel::selection-changed] signal by calling the [method@Gtk.SelectionModel.selection_changed] function. The positions given in that signal may have their selection state changed, though that is not a requirement. If new items added to the model via the [signal@Gio.ListModel::items-changed] signal are selected or not is up to the implementation. Note that items added via [signal@Gio.ListModel::items-changed] may already be selected and no [signal@Gtk.SelectionModel::selection-changed] will be emitted for them. So to track which items are selected, it is necessary to listen to both signals. Additionally, the interface can expose functionality to select and unselect items. If these functions are implemented, GTK's list widgets will allow users to select and unselect items. However, `GtkSelectionModel`s are free to only implement them partially or not at all. In that case the widgets will not support the unimplemented operations. When selecting or unselecting is supported by a model, the return values of the selection functions do *not* indicate if selection or unselection happened. They are only meant to indicate complete failure, like when this mode of selecting is not supported by the model. Selections may happen asynchronously, so the only reliable way to find out when an item was selected is to listen to the signals that indicate selection. Gets the set of selected items in a range. This function is an optimization for [method@Gtk.SelectionModel.get_selection] when you are only interested in part of the model's selected state. A common use case is in response to the [signal@Gtk.SelectionModel::selection-changed] signal. A `GtkBitset` that matches the selection state for the given range with all other values being undefined. The bitset must not be modified. a `GtkSelectionModel` start of the queried range number of items in the queried range Checks if the given item is selected. %TRUE if the item is selected a `GtkSelectionModel` the position of the item to query Requests to select all items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items are now selected. a `GtkSelectionModel` Requests to select an item in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the item was selected. a `GtkSelectionModel` the position of the item to select whether previously selected items should be unselected Requests to select a range of items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the range was selected. a `GtkSelectionModel` the first item to select the number of items to select whether previously selected items should be unselected Make selection changes. This is the most advanced selection updating method that allows the most fine-grained control over selection changes. If you can, you should try the simpler versions, as implementations are more likely to implement support for those. Requests that the selection state of all positions set in @mask be updated to the respective value in the @selected bitmask. In pseudocode, it would look something like this: ```c for (i = 0; i < n_items; i++) { // don't change values not in the mask if (!gtk_bitset_contains (mask, i)) continue; if (gtk_bitset_contains (selected, i)) select_item (i); else unselect_item (i); } gtk_selection_model_selection_changed (model, first_changed_item, n_changed_items); ``` @mask and @selected must not be modified. They may refer to the same bitset, which would mean that every item in the set should be selected. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items were updated according to the inputs. a `GtkSelectionModel` bitmask specifying if items should be selected or unselected bitmask specifying which items should be updated Requests to unselect all items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items are now unselected. a `GtkSelectionModel` Requests to unselect an item in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the item was unselected. a `GtkSelectionModel` the position of the item to unselect Requests to unselect a range of items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the range was unselected. a `GtkSelectionModel` the first item to unselect the number of items to unselect Gets the set containing all currently selected items in the model. This function may be slow, so if you are only interested in single item, consider using [method@Gtk.SelectionModel.is_selected] or if you are only interested in a few, consider [method@Gtk.SelectionModel.get_selection_in_range]. a `GtkBitset` containing all the values currently selected in @model. If no items are selected, the bitset is empty. The bitset must not be modified. a `GtkSelectionModel` Gets the set of selected items in a range. This function is an optimization for [method@Gtk.SelectionModel.get_selection] when you are only interested in part of the model's selected state. A common use case is in response to the [signal@Gtk.SelectionModel::selection-changed] signal. A `GtkBitset` that matches the selection state for the given range with all other values being undefined. The bitset must not be modified. a `GtkSelectionModel` start of the queried range number of items in the queried range Checks if the given item is selected. %TRUE if the item is selected a `GtkSelectionModel` the position of the item to query Requests to select all items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items are now selected. a `GtkSelectionModel` Requests to select an item in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the item was selected. a `GtkSelectionModel` the position of the item to select whether previously selected items should be unselected Requests to select a range of items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the range was selected. a `GtkSelectionModel` the first item to select the number of items to select whether previously selected items should be unselected Helper function for implementations of `GtkSelectionModel`. Call this when the selection changes to emit the [signal@Gtk.SelectionModel::selection-changed] signal. a `GtkSelectionModel` the first changed item the number of changed items Make selection changes. This is the most advanced selection updating method that allows the most fine-grained control over selection changes. If you can, you should try the simpler versions, as implementations are more likely to implement support for those. Requests that the selection state of all positions set in @mask be updated to the respective value in the @selected bitmask. In pseudocode, it would look something like this: ```c for (i = 0; i < n_items; i++) { // don't change values not in the mask if (!gtk_bitset_contains (mask, i)) continue; if (gtk_bitset_contains (selected, i)) select_item (i); else unselect_item (i); } gtk_selection_model_selection_changed (model, first_changed_item, n_changed_items); ``` @mask and @selected must not be modified. They may refer to the same bitset, which would mean that every item in the set should be selected. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items were updated according to the inputs. a `GtkSelectionModel` bitmask specifying if items should be selected or unselected bitmask specifying which items should be updated Requests to unselect all items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items are now unselected. a `GtkSelectionModel` Requests to unselect an item in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the item was unselected. a `GtkSelectionModel` the position of the item to unselect Requests to unselect a range of items in the model. %TRUE if this action was supported and no fallback should be tried. This does not mean the range was unselected. a `GtkSelectionModel` the first item to unselect the number of items to unselect Emitted when the selection state of some of the items in @model changes. Note that this signal does not specify the new selection state of the items, they need to be queried manually. It is also not necessary for a model to change the selection state of any of the items in the selection model, though it would be rather useless to emit such a signal. The first item that may have changed number of items with changes The list of virtual functions for the `GtkSelectionModel` interface. No function must be implemented, but unless `GtkSelectionModel::is_selected()` is implemented, it will not be possible to select items in the set. The model does not need to implement any functions to support either selecting or unselecting items. Of course, if the model does not do that, it means that users cannot select or unselect items in a list widget using the model. All selection functions fall back to `GtkSelectionModel::set_selection()` so it is sufficient to implement just that function for full selection support. Return if the item at the given position is selected. %TRUE if the item is selected a `GtkSelectionModel` the position of the item to query Return a bitset with all currently selected items in the given range. By default, this function will call `GtkSelectionModel::is_selected()` on all items in the given range. A `GtkBitset` that matches the selection state for the given range with all other values being undefined. The bitset must not be modified. a `GtkSelectionModel` start of the queried range number of items in the queried range Select the item in the given position. If the operation is known to fail, return %FALSE. %TRUE if this action was supported and no fallback should be tried. This does not mean the item was selected. a `GtkSelectionModel` the position of the item to select whether previously selected items should be unselected Unselect the item in the given position. If the operation is known to fail, return %FALSE. %TRUE if this action was supported and no fallback should be tried. This does not mean the item was unselected. a `GtkSelectionModel` the position of the item to unselect Select all items in the given range. If the operation is unsupported or known to fail for all items, return %FALSE. %TRUE if this action was supported and no fallback should be tried. This does not mean the range was selected. a `GtkSelectionModel` the first item to select the number of items to select whether previously selected items should be unselected Unselect all items in the given range. If the operation is unsupported or known to fail for all items, return %FALSE. %TRUE if this action was supported and no fallback should be tried. This does not mean the range was unselected. a `GtkSelectionModel` the first item to unselect the number of items to unselect Select all items in the model. If the operation is unsupported or known to fail for all items, return %FALSE. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items are now selected. a `GtkSelectionModel` Unselect all items in the model. If the operation is unsupported or known to fail for all items, return %FALSE. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items are now unselected. a `GtkSelectionModel` Set selection state of all items in mask to selected. See gtk_selection_model_set_selection() for a detailed explanation of this function. %TRUE if this action was supported and no fallback should be tried. This does not mean that all items were updated according to the inputs. a `GtkSelectionModel` bitmask specifying if items should be selected or unselected bitmask specifying which items should be updated Determines how GTK handles the sensitivity of various controls, such as combo box buttons. The control is made insensitive if no action can be triggered The control is always sensitive The control is always insensitive `GtkSeparator` is a horizontal or vertical separator widget.  A `GtkSeparator` can be used to group the widgets within a window. It displays a line with a shadow to make it appear sunken into the interface. # CSS nodes `GtkSeparator` has a single CSS node with name separator. The node gets one of the .horizontal or .vertical style classes. # Accessibility `GtkSeparator` uses the %GTK_ACCESSIBLE_ROLE_SEPARATOR role. Creates a new `GtkSeparator` with the given orientation. a new `GtkSeparator`. the separator’s orientation. `GtkSettings` provides a mechanism to share global settings between applications. On the X window system, this sharing is realized by an [XSettings](http://www.freedesktop.org/wiki/Specifications/xsettings-spec) manager that is usually part of the desktop environment, along with utilities that let the user change these settings. On Wayland, the settings are obtained either via a settings portal, or by reading desktop settings from [class@Gio.Settings]. On macOS, the settings are obtained from `NSUserDefaults`. In the absence of these sharing mechanisms, GTK reads default values for settings from `settings.ini` files in `/etc/gtk-4.0`, `$XDG_CONFIG_DIRS/gtk-4.0` and `$XDG_CONFIG_HOME/gtk-4.0`. These files must be valid key files (see `GKeyFile`), and have a section called Settings. Themes can also provide default values for settings by installing a `settings.ini` file next to their `gtk.css` file. Applications can override system-wide settings by setting the property of the `GtkSettings` object with g_object_set(). This should be restricted to special cases though; `GtkSettings` are not meant as an application configuration facility. There is one `GtkSettings` instance per display. It can be obtained with [func@Gtk.Settings.get_for_display], but in many cases, it is more convenient to use [method@Gtk.Widget.get_settings]. Gets the `GtkSettings` object for the default display, creating it if necessary. See [func@Gtk.Settings.get_for_display]. a `GtkSettings` object. If there is no default display, then returns %NULL. Gets the `GtkSettings` object for @display, creating it if necessary. a `GtkSettings` object a `GdkDisplay` Undoes the effect of calling g_object_set() to install an application-specific value for a setting. After this call, the setting will again follow the session-wide value for this setting. a `GtkSettings` object the name of the setting to reset Whether buttons in dialogs should use the alternative button order. Controls the direction of the sort indicators in sorted list and tree views. By default an arrow pointing down means the column is sorted in ascending order. When set to %TRUE, this order will be inverted. Whether the application prefers to use a dark theme. If a GTK theme includes a dark variant, it will be used instead of the configured theme. Some applications benefit from minimizing the amount of light pollution that interferes with the content. Good candidates for dark themes are photo and video editors that make the actual content get all the attention and minimize the distraction of the chrome. Dark themes should not be used for documents, where large spaces are white/light and the dark chrome creates too much contrast (web browser, text editor...). The aspect ratio of the text caret. Whether the cursor should blink. Also see the [property@Gtk.Settings:gtk-cursor-blink-timeout] setting, which allows more flexible control over cursor blinking. Length of the cursor blink cycle, in milliseconds. Time after which the cursor stops blinking, in seconds. The timer is reset after each user interaction. Setting this to zero has the same effect as setting [property@Gtk.Settings:gtk-cursor-blink] to %FALSE. Name of the cursor theme to use. Use %NULL to use the default theme. The size to use for cursors. 0 means to use the default size. Determines which buttons should be put in the titlebar of client-side decorated windows, and whether they should be placed on the left or right. The format of the string is button names, separated by commas. A colon separates the buttons that should appear on the left from those on the right. Recognized button names are minimize, maximize, close, icon (the window icon) and menu (a menu button for the fallback app menu). For example, "menu:minimize,maximize,close" specifies a menu on the left, and minimize, maximize and close buttons on the right. Note that buttons will only be shown when they are meaningful. E.g. a menu button only appears when the desktop shell does not show the app menu, and a close button only appears on a window that can be closed. Also note that the setting can be overridden with the [property@Gtk.HeaderBar:decoration-layout] property. Whether builtin GTK dialogs such as the file chooser, the color chooser or the font chooser will use a header bar at the top to show action widgets, or an action area at the bottom. This setting does not affect custom dialogs using `GtkDialog` directly, or message dialogs. The number of pixels the cursor can move before dragging. The maximum distance allowed between two clicks for them to be considered a double click, in pixels. The maximum time to allow between two clicks for them to be considered a double click, in milliseconds. Whether menu items should have visible accelerators which can be activated. Whether to enable toolkit-wide animations. Whether to play any event sounds at all. See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec) for more information on event sounds and sound themes. GTK itself does not support event sounds, you have to use a loadable module like the one that comes with libcanberra. Whether to play event sounds as feedback to user input. See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec) for more information on event sounds and sound themes. GTK itself does not support event sounds, you have to use a loadable module like the one that comes with libcanberra. Whether a middle click on a mouse should paste the 'PRIMARY' clipboard content at the cursor location. How long to show the last input character in hidden entries. This value is in milliseconds. 0 disables showing the last char. 600 is a good value for enabling it. Whether to select the contents of an entry when it is focused. When %TRUE, keyboard navigation and other input-related errors will cause a beep. Since the error bell is implemented using gdk_surface_beep(), the windowing system may offer ways to configure the error bell in many ways, such as flashing the window or similar visual effects. The default font to use. GTK uses the family name and size from this string. How GTK font rendering is set up. When set to [enum@Gtk.FontRendering.MANUAL], GTK respects the low-level font-related settings ([property@Gtk.Settings:gtk-hint-font-metrics], [property@Gtk.Settings:gtk-xft-antialias], [property@Gtk.Settings:gtk-xft-hinting], [property@Gtk.Settings:gtk-xft-hintstyle] and [property@Gtk.Settings:gtk-xft-rgba]) as much as practical. When set to [enum@Gtk.FontRendering.AUTOMATIC], GTK will consider factors such as screen resolution and scale in deciding how to render fonts. Timestamp of the current fontconfig configuration. Whether hinting should be applied to font metrics. Note that this also turns off subpixel positioning of glyphs, since it conflicts with metrics hinting. Name of the icon theme to use. See [class@Gtk.IconTheme] for details about how GTK handles icon themes. Which IM (input method) module should be used by default. This is the input method that will be used if the user has not explicitly chosen another input method from the IM context menu. This also can be a colon-separated list of input methods, which GTK will try in turn until it finds one available on the system. See [class@Gtk.IMContext]. Whether GTK should make sure that text can be navigated with a caret, even if it is not editable. This is useful when using a screen reader. Whether to select the contents of a selectable label when it is focused. The time for a button or touch press to be considered a “long press”. See [class@Gtk.GestureLongPress]. Whether scrolled windows may use overlaid scrolling indicators. If this is set to %FALSE, scrolled windows will have permanent scrollbars. If the value of this setting is %TRUE, clicking the primary button in a `GtkRange` trough will move the slider, and hence set the range’s value, to the point that you clicked. If it is %FALSE, a primary click will cause the slider/value to move by the range’s page-size towards the point clicked. Whichever action you choose for the primary button, the other action will be available by holding Shift and primary-clicking, or clicking the middle mouse button. A comma-separated list of print backends to use in the print dialog. Available print backends depend on the GTK installation, and may include "file", "cups", "lpr" or "papi". A command to run for displaying the print preview. The command should contain a `%f` placeholder, which will get replaced by the path to the pdf file. The command may also contain a `%s` placeholder, which will get replaced by the path to a file containing the print settings in the format produced by [method@Gtk.PrintSettings.to_file]. The preview application is responsible for removing the pdf file and the print settings file when it is done. Whether GTK should keep track of items inside the recently used resources list. If set to %FALSE, the list will always be empty. The maximum age, in days, of the items inside the recently used resources list. Items older than this setting will be excised from the list. If set to 0, the list will always be empty; if set to -1, no item will be removed. Set to %TRUE if the desktop environment is displaying the app menu, %FALSE if the app should display it itself. Set to %TRUE if the desktop environment is displaying the desktop folder, %FALSE if not. Set to %TRUE if the desktop environment is displaying the menubar, %FALSE if the app should display it itself. When %TRUE, widgets like switches include shapes to indicate their on/off state. The XDG sound theme to use for event sounds. See the [Sound Theme Specifications](http://www.freedesktop.org/wiki/Specifications/sound-theme-spec) for more information on event sounds and sound themes. GTK itself does not support event sounds, you have to use a loadable module like the one that comes with libcanberra. Whether two cursors should be displayed for mixed left-to-right and right-to-left text. Name of the theme to load. See [class@Gtk.CssProvider] for details about how GTK finds the CSS stylesheet for a theme. Determines the action to take when a double-click occurs on the titlebar of client-side decorated windows. Recognized actions are minimize, toggle-maximize, menu, lower or none. Determines the action to take when a middle-click occurs on the titlebar of client-side decorated windows. Recognized actions are minimize, toggle-maximize, menu, lower or none. Determines the action to take when a right-click occurs on the titlebar of client-side decorated windows. Recognized actions are minimize, toggle-maximize, menu, lower or none. Whether to antialias fonts. The values are 0 for no, 1 for yes, or -1 for the system default. The font resolution, in 1024 * dots/inch. -1 to use the default value. Whether to enable font hinting. The values are 0 for no, 1 for yes, or -1 for the system default. What degree of font hinting to use. The possible vaues are hintnone, hintslight, hintmedium, hintfull. The type of subpixel antialiasing to use. The possible values are none, rgb, bgr, vrgb, vbgr. Note that GSK does not support subpixel antialiasing, and this setting has no effect on font rendering in GTK. A `GtkShortcut` describes a keyboard shortcut. It contains a description of how to trigger the shortcut via a [class@Gtk.ShortcutTrigger] and a way to activate the shortcut on a widget via a [class@Gtk.ShortcutAction]. The actual work is usually done via [class@Gtk.ShortcutController], which decides if and when to activate a shortcut. Using that controller directly however is rarely necessary as various higher level convenience APIs exist on `GtkWidget`s that make it easier to use shortcuts in GTK. `GtkShortcut` does provide functionality to make it easy for users to work with shortcuts, either by providing informational strings for display purposes or by allowing shortcuts to be configured. Creates a new `GtkShortcut` that is triggered by @trigger and then activates @action. a new `GtkShortcut` The trigger that will trigger the shortcut The action that will be activated upon triggering Creates a new `GtkShortcut` that is triggered by @trigger and then activates @action with arguments given by @format_string. a new `GtkShortcut` The trigger that will trigger the shortcut The action that will be activated upon triggering GVariant format string for arguments or %NULL for no arguments arguments, as given by format string. Gets the action that is activated by this shortcut. the action a `GtkShortcut` Gets the arguments that are passed when activating the shortcut. the arguments a `GtkShortcut` Gets the trigger used to trigger @self. the trigger used a `GtkShortcut` Sets the new action for @self to be @action. a `GtkShortcut` The new action. If the @action is %NULL, the nothing action will be used. Sets the arguments to pass when activating the shortcut. a `GtkShortcut` arguments to pass when activating @self Sets the new trigger for @self to be @trigger. a `GtkShortcut` The new trigger. If the @trigger is %NULL, the never trigger will be used. The action that gets activated by this shortcut. Arguments passed to activation. The trigger that triggers this shortcut. `GtkShortcutAction` encodes an action that can be triggered by a keyboard shortcut. `GtkShortcutActions` contain functions that allow easy presentation to end users as well as being printed for debugging. All `GtkShortcutActions` are immutable, you can only specify their properties during construction. If you want to change a action, you have to replace it with a new one. If you need to pass arguments to an action, these are specified by the higher-level `GtkShortcut` object. To activate a `GtkShortcutAction` manually, [method@Gtk.ShortcutAction.activate] can be called. GTK provides various actions: - [class@Gtk.MnemonicAction]: a shortcut action that calls gtk_widget_mnemonic_activate() - [class@Gtk.CallbackAction]: a shortcut action that invokes a given callback - [class@Gtk.SignalAction]: a shortcut action that emits a given signal - [class@Gtk.ActivateAction]: a shortcut action that calls gtk_widget_activate() - [class@Gtk.NamedAction]: a shortcut action that calls gtk_widget_activate_action() - [class@Gtk.NothingAction]: a shortcut action that does nothing Tries to parse the given string into an action. On success, the parsed action is returned. When parsing failed, %NULL is returned. The accepted strings are: - `nothing`, for `GtkNothingAction` - `activate`, for `GtkActivateAction` - `mnemonic-activate`, for `GtkMnemonicAction` - `action(NAME)`, for a `GtkNamedAction` for the action named `NAME` - `signal(NAME)`, for a `GtkSignalAction` for the signal `NAME` a new `GtkShortcutAction` the string to parse Activates the action on the @widget with the given @args. Note that some actions ignore the passed in @flags, @widget or @args. Activation of an action can fail for various reasons. If the action is not supported by the @widget, if the @args don't match the action or if the activation otherwise had no effect, %FALSE will be returned. %TRUE if this action was activated successfully a `GtkShortcutAction` flags to activate with Target of the activation arguments to pass Prints the given action into a string for the developer. This is meant for debugging and logging. The form of the representation may change at any time and is not guaranteed to stay identical. a `GtkShortcutAction` a `GString` to print into Prints the given action into a human-readable string. This is a small wrapper around [method@Gtk.ShortcutAction.print] to help when debugging. a new string a `GtkShortcutAction` List of flags that can be passed to action activation. More flags may be added in the future. The action is the only action that can be activated. If this flag is not set, a future activation may select a different action. `GtkShortcutController` is an event controller that manages shortcuts. Most common shortcuts are using this controller implicitly, e.g. by adding a mnemonic underline to a [class@Gtk.Label], or by installing a key binding using [method@Gtk.WidgetClass.add_binding], or by adding accelerators to global actions using [method@Gtk.Application.set_accels_for_action]. But it is possible to create your own shortcut controller, and add shortcuts to it. `GtkShortcutController` implements [iface@Gio.ListModel] for querying the shortcuts that have been added to it. # GtkShortcutController as GtkBuildable `GtkShortcutController`s can be created in [class@Gtk.Builder] ui files, to set up shortcuts in the same place as the widgets. An example of a UI definition fragment with `GtkShortcutController`: ```xml <object class='GtkButton'> <child> <object class='GtkShortcutController'> <property name='scope'>managed</property> <child> <object class='GtkShortcut'> <property name='trigger'>&lt;Control&gt;k</property> <property name='action'>activate</property> </object> </child> </object> </child> </object> ``` This example creates a [class@Gtk.ActivateAction] for triggering the `activate` signal of the [class@Gtk.Button]. See [ctor@Gtk.ShortcutAction.parse_string] for the syntax for other kinds of [class@Gtk.ShortcutAction]. See [ctor@Gtk.ShortcutTrigger.parse_string] to learn more about the syntax for triggers. Creates a new shortcut controller. a newly created shortcut controller Creates a new shortcut controller that takes its shortcuts from the given list model. A controller created by this function does not let you add or remove individual shortcuts using the shortcut controller api, but you can change the contents of the model. a newly created shortcut controller a `GListModel` containing shortcuts Adds @shortcut to the list of shortcuts handled by @self. If this controller uses an external shortcut list, this function does nothing. the controller a `GtkShortcut` Gets the mnemonics modifiers for when this controller activates its shortcuts. the controller's mnemonics modifiers a `GtkShortcutController` Gets the scope for when this controller activates its shortcuts. See [method@Gtk.ShortcutController.set_scope] for details. the controller's scope a `GtkShortcutController` Removes @shortcut from the list of shortcuts handled by @self. If @shortcut had not been added to @controller or this controller uses an external shortcut list, this function does nothing. the controller a `GtkShortcut` Sets the controller to use the given modifier for mnemonics. The mnemonics modifiers determines which modifiers need to be pressed to allow activation of shortcuts with mnemonics triggers. GTK normally uses the Alt modifier for mnemonics, except in `GtkPopoverMenu`s, where mnemonics can be triggered without any modifiers. It should be very rarely necessary to change this, and doing so is likely to interfere with other shortcuts. This value is only relevant for local shortcut controllers. Global and managed shortcut controllers will have their shortcuts activated from other places which have their own modifiers for activating mnemonics. a `GtkShortcutController` the new mnemonics_modifiers to use Sets the controller to have the given @scope. The scope allows shortcuts to be activated outside of the normal event propagation. In particular, it allows installing global keyboard shortcuts that can be activated even when a widget does not have focus. With %GTK_SHORTCUT_SCOPE_LOCAL, shortcuts will only be activated when the widget has focus. a `GtkShortcutController` the new scope to use The type of items. See [method@Gio.ListModel.get_item_type]. The modifiers that need to be pressed to allow mnemonics activation. A list model to take shortcuts from. The number of items. See [method@Gio.ListModel.get_n_items]. What scope the shortcuts will be handled in. Prototype for shortcuts based on user callbacks. %TRUE if the action was successful. The widget passed to the activation The arguments passed to the activation The user data provided when activating the action `GtkShortcutLabel` displays a single keyboard shortcut or gesture. The main use case for `GtkShortcutLabel` is inside a [class@Gtk.ShortcutsWindow]. Creates a new `GtkShortcutLabel` with @accelerator set. a newly-allocated `GtkShortcutLabel` the initial accelerator Retrieves the current accelerator of @self. the current accelerator. a `GtkShortcutLabel` Retrieves the text that is displayed when no accelerator is set. the current text displayed when no accelerator is set. a `GtkShortcutLabel` Sets the accelerator to be displayed by @self. a `GtkShortcutLabel` the new accelerator Sets the text to be displayed by @self when no accelerator is set. a `GtkShortcutLabel` the text to be displayed when no accelerator is set The accelerator that @self displays. See [property@Gtk.ShortcutsShortcut:accelerator] for the accepted syntax. The text that is displayed when no accelerator is set. The `GtkShortcutManager` interface is used to implement shortcut scopes. This is important for [iface@Gtk.Native] widgets that have their own surface, since the event controllers that are used to implement managed and global scopes are limited to the same native. Examples for widgets implementing `GtkShortcutManager` are [class@Gtk.Window] and [class@Gtk.Popover]. Every widget that implements `GtkShortcutManager` will be used as a %GTK_SHORTCUT_SCOPE_MANAGED. Add a `GtkShortcutController` to be managed. Remove a `GtkShortcutController` that had previously been added The list of functions that can be implemented for the `GtkShortcutManager` interface. Note that no function is mandatory to implement, the default implementation will work fine. Add a `GtkShortcutController` to be managed. Remove a `GtkShortcutController` that had previously been added Describes where [class@Shortcut]s added to a [class@ShortcutController] get handled. Shortcuts are handled inside the widget the controller belongs to. Shortcuts are handled by the first ancestor that is a [iface@ShortcutManager] Shortcuts are handled by the root widget. `GtkShortcutTrigger` tracks how a `GtkShortcut` should be activated. To find out if a `GtkShortcutTrigger` triggers, you can call [method@Gtk.ShortcutTrigger.trigger] on a `GdkEvent`. `GtkShortcutTriggers` contain functions that allow easy presentation to end users as well as being printed for debugging. All `GtkShortcutTriggers` are immutable, you can only specify their properties during construction. If you want to change a trigger, you have to replace it with a new one. Tries to parse the given string into a trigger. On success, the parsed trigger is returned. When parsing failed, %NULL is returned. The accepted strings are: - `never`, for `GtkNeverTrigger` - a string parsed by gtk_accelerator_parse(), for a `GtkKeyvalTrigger`, e.g. `<Control>C` - underscore, followed by a single character, for `GtkMnemonicTrigger`, e.g. `_l` - two valid trigger strings, separated by a `|` character, for a `GtkAlternativeTrigger`: `<Control>q|<Control>w` Note that you will have to escape the `<` and `>` characters when specifying triggers in XML files, such as GtkBuilder ui files. Use `&lt;` instead of `<` and `&gt;` instead of `>`. a new `GtkShortcutTrigger` the string to parse The types of @trigger1 and @trigger2 are `gconstpointer` only to allow use of this function as a `GCompareFunc`. They must each be a `GtkShortcutTrigger`. An integer less than, equal to, or greater than zero if @trigger1 is found, respectively, to be less than, to match, or be greater than @trigger2. a `GtkShortcutTrigger` a `GtkShortcutTrigger` Checks if @trigger1 and @trigger2 trigger under the same conditions. The types of @one and @two are `gconstpointer` only to allow use of this function with `GHashTable`. They must each be a `GtkShortcutTrigger`. %TRUE if @trigger1 and @trigger2 are equal a `GtkShortcutTrigger` a `GtkShortcutTrigger` Generates a hash value for a `GtkShortcutTrigger`. The output of this function is guaranteed to be the same for a given value only per-process. It may change between different processor architectures or even different versions of GTK. Do not use this function as a basis for building protocols or file formats. The types of @trigger is `gconstpointer` only to allow use of this function with `GHashTable`. They must each be a `GtkShortcutTrigger`. a hash value corresponding to @trigger a `GtkShortcutTrigger` Prints the given trigger into a string for the developer. This is meant for debugging and logging. The form of the representation may change at any time and is not guaranteed to stay identical. a `GtkShortcutTrigger` a `GString` to print into Prints the given trigger into a string. This function is returning a translated string for presentation to end users for example in menu items or in help texts. The @display in use may influence the resulting string in various forms, such as resolving hardware keycodes or by causing display-specific modifier names. The form of the representation may change at any time and is not guaranteed to stay identical. %TRUE if something was printed or %FALSE if the trigger did not have a textual representation suitable for end users. a `GtkShortcutTrigger` `GdkDisplay` to print for a `GString` to print into Gets textual representation for the given trigger. This function is returning a translated string for presentation to end users for example in menu items or in help texts. The @display in use may influence the resulting string in various forms, such as resolving hardware keycodes or by causing display-specific modifier names. The form of the representation may change at any time and is not guaranteed to stay identical. a new string a `GtkShortcutTrigger` `GdkDisplay` to print for Prints the given trigger into a human-readable string. This is a small wrapper around [method@Gtk.ShortcutTrigger.print] to help when debugging. a new string a `GtkShortcutTrigger` Checks if the given @event triggers @self. Whether the event triggered the shortcut a `GtkShortcutTrigger` the event to check %TRUE if mnemonics should trigger. Usually the value of this property is determined by checking that the passed in @event is a Key event and has the right modifiers set. GtkShortcutType specifies the kind of shortcut that is being described. More values may be added to this enumeration over time. The shortcut is a keyboard accelerator. The GtkShortcutsShortcut:accelerator property will be used. The shortcut is a pinch gesture. GTK provides an icon and subtitle. The shortcut is a stretch gesture. GTK provides an icon and subtitle. The shortcut is a clockwise rotation gesture. GTK provides an icon and subtitle. The shortcut is a counterclockwise rotation gesture. GTK provides an icon and subtitle. The shortcut is a two-finger swipe gesture. GTK provides an icon and subtitle. The shortcut is a two-finger swipe gesture. GTK provides an icon and subtitle. The shortcut is a gesture. The GtkShortcutsShortcut:icon property will be used. The shortcut is a swipe gesture. GTK provides an icon and subtitle. The shortcut is a swipe gesture. GTK provides an icon and subtitle. A `GtkShortcutsGroup` represents a group of related keyboard shortcuts or gestures. The group has a title. It may optionally be associated with a view of the application, which can be used to show only relevant shortcuts depending on the application context. This widget is only meant to be used with [class@Gtk.ShortcutsWindow]. The recommended way to construct a `GtkShortcutsGroup` is with [class@Gtk.Builder], by using the `<child>` tag to populate a `GtkShortcutsGroup` with one or more [class@Gtk.ShortcutsShortcut] instances. If you need to add a shortcut programmatically, use [method@Gtk.ShortcutsGroup.add_shortcut]. Adds a shortcut to the shortcuts group. This is the programmatic equivalent to using [class@Gtk.Builder] and a `<child>` tag to add the child. Adding children with other API is not appropriate as `GtkShortcutsGroup` manages its children internally. a `GtkShortcutsGroup` the `GtkShortcutsShortcut` to add The size group for the accelerator portion of shortcuts in this group. This is used internally by GTK, and must not be modified by applications. A rough measure for the number of lines in this group. This is used internally by GTK, and is not useful for applications. The title for this group of shortcuts. The size group for the textual portion of shortcuts in this group. This is used internally by GTK, and must not be modified by applications. An optional view that the shortcuts in this group are relevant for. The group will be hidden if the [property@Gtk.ShortcutsWindow:view-name] property does not match the view of this group. Set this to %NULL to make the group always visible. A `GtkShortcutsSection` collects all the keyboard shortcuts and gestures for a major application mode. If your application needs multiple sections, you should give each section a unique [property@Gtk.ShortcutsSection:section-name] and a [property@Gtk.ShortcutsSection:title] that can be shown in the section selector of the [class@Gtk.ShortcutsWindow]. The [property@Gtk.ShortcutsSection:max-height] property can be used to influence how the groups in the section are distributed over pages and columns. This widget is only meant to be used with [class@Gtk.ShortcutsWindow]. The recommended way to construct a `GtkShortcutsSection` is with [class@Gtk.Builder], by using the `<child>` tag to populate a `GtkShortcutsSection` with one or more [class@Gtk.ShortcutsGroup] instances, which in turn contain one or more [class@Gtk.ShortcutsShortcut] objects. If you need to add a group programmatically, use [method@Gtk.ShortcutsSection.add_group]. # Shortcuts and Gestures Pan gestures allow to navigate between sections. The following signals have default keybindings: - [signal@Gtk.ShortcutsSection::change-current-page] Adds a group to the shortcuts section. This is the programmatic equivalent to using [class@Gtk.Builder] and a `<child>` tag to add the child. Adding children with the `GtkBox` API is not appropriate, as `GtkShortcutsSection` manages its children internally. a `GtkShortcutsSection` the `GtkShortcutsGroup` to add The maximum number of lines to allow per column. This property can be used to influence how the groups in this section are distributed across pages and columns. The default value of 15 should work in most cases. A unique name to identify this section among the sections added to the `GtkShortcutsWindow`. Setting the [property@Gtk.ShortcutsWindow:section-name] property to this string will make this section shown in the `GtkShortcutsWindow`. The string to show in the section selector of the `GtkShortcutsWindow` for this section. If there is only one section, you don't need to set a title, since the section selector will not be shown in this case. A view name to filter the groups in this section by. See [property@Gtk.ShortcutsGroup:view]. Applications are expected to use the [property@Gtk.ShortcutsWindow:view-name] property for this purpose. Emitted when we change the current page. The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>PgUp</kbd>, <kbd>PgUp</kbd>, <kbd>Ctrl</kbd>+<kbd>PgDn</kbd>, <kbd>PgDn</kbd>. whether the page was changed the offset A `GtkShortcutsShortcut` represents a single keyboard shortcut or gesture with a short text. This widget is only meant to be used with `GtkShortcutsWindow`. The size group for the accelerator portion of this shortcut. This is used internally by GTK, and must not be modified by applications. The accelerator(s) represented by this object. This property is used if [property@Gtk.ShortcutsShortcut:shortcut-type] is set to %GTK_SHORTCUT_ACCELERATOR. The syntax of this property is (an extension of) the syntax understood by [func@Gtk.accelerator_parse]. Multiple accelerators can be specified by separating them with a space, but keep in mind that the available width is limited. It is also possible to specify ranges of shortcuts, using `...` between the keys. Sequences of keys can be specified using a `+` or `&` between the keys. Examples: - A single shortcut: `<ctl><alt>delete` - Two alternative shortcuts: `<shift>a Home` - A range of shortcuts: `<alt>1...<alt>9` - Several keys pressed together: `Control_L&Control_R` - A sequence of shortcuts or keys: `<ctl>c+<ctl>x` Use "+" instead of "&" when the keys may (or have to be) pressed sequentially (e.g use "t+t" for 'press the t key twice'). Note that `<`, `>` and `&` need to be escaped as `&lt;`, `&gt`; and `&amp`; when used in .ui files. A detailed action name. If this is set for a shortcut of type %GTK_SHORTCUT_ACCELERATOR, then GTK will use the accelerators that are associated with the action via [method@Gtk.Application.set_accels_for_action], and setting [property@Gtk.ShortcutsShortcut:accelerator] is not necessary. The text direction for which this shortcut is active. If the shortcut is used regardless of the text direction, set this property to %GTK_TEXT_DIR_NONE. An icon to represent the shortcut or gesture. This property is used if [property@Gtk.ShortcutsShortcut:shortcut-type] is set to %GTK_SHORTCUT_GESTURE. For the other predefined gesture types, GTK provides an icon on its own. %TRUE if an icon has been set. The type of shortcut that is represented. The subtitle for the shortcut or gesture. This is typically used for gestures and should be a short, one-line text that describes the gesture itself. For the predefined gesture types, GTK provides a subtitle on its own. %TRUE if a subtitle has been set. The textual description for the shortcut or gesture represented by this object. This should be a short string that can fit in a single line. The size group for the textual portion of this shortcut. This is used internally by GTK, and must not be modified by applications. A `GtkShortcutsWindow` shows information about the keyboard shortcuts and gestures of an application. The shortcuts can be grouped, and you can have multiple sections in this window, corresponding to the major modes of your application. Additionally, the shortcuts can be filtered by the current view, to avoid showing information that is not relevant in the current application context. The recommended way to construct a `GtkShortcutsWindow` is with [class@Gtk.Builder], by using the `<child>` tag to populate a `GtkShortcutsWindow` with one or more [class@Gtk.ShortcutsSection] objects, which contain one or more [class@Gtk.ShortcutsGroup] instances, which, in turn, contain [class@Gtk.ShortcutsShortcut] instances. If you need to add a section programmatically, use [method@Gtk.ShortcutsWindow.add_section] instead of [method@Gtk.Window.set_child], as the shortcuts window manages its children directly. # A simple example:  This example has as single section. As you can see, the shortcut groups are arranged in columns, and spread across several pages if there are too many to find on a single page. The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/main/demos/gtk-demo/shortcuts-gedit.ui). # An example with multiple views:  This example shows a `GtkShortcutsWindow` that has been configured to show only the shortcuts relevant to the "stopwatch" view. The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/main/demos/gtk-demo/shortcuts-clocks.ui). # An example with multiple sections:  This example shows a `GtkShortcutsWindow` with two sections, "Editor Shortcuts" and "Terminal Shortcuts". The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/main/demos/gtk-demo/shortcuts-builder.ui). # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.ShortcutsWindow::close] - [signal@Gtk.ShortcutsWindow::search] # CSS nodes `GtkShortcutsWindow` has a single CSS node with the name `window` and style class `.shortcuts`. Adds a section to the shortcuts window. This is the programmatic equivalent to using [class@Gtk.Builder] and a `<child>` tag to add the child. Using [method@Gtk.Window.set_child] is not appropriate as the shortcuts window manages its children internally. a `GtkShortcutsWindow` the `GtkShortcutsSection` to add The name of the section to show. This should be the section-name of one of the `GtkShortcutsSection` objects that are in this shortcuts window. The view name by which to filter the contents. This should correspond to the [property@Gtk.ShortcutsGroup:view] property of some of the [class@Gtk.ShortcutsGroup] objects that are inside this shortcuts window. Set this to %NULL to show all groups. Emitted when the user uses a keybinding to close the window. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is the <kbd>Escape</kbd> key. Emitted when the user uses a keybinding to start a search. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Control</kbd>+<kbd>F</kbd>. A `GtkShortcut`Action that emits a signal. Signals that are used in this way are referred to as keybinding signals, and they are expected to be defined with the %G_SIGNAL_ACTION flag. Creates an action that when activated, emits the given action signal on the provided widget. It will also unpack the args into arguments passed to the signal. a new `GtkShortcutAction` name of the signal to emit Returns the name of the signal that will be emitted. the name of the signal to emit a signal action The name of the signal to emit. `GtkSignalListItemFactory` is a `GtkListItemFactory` that emits signals to manage listitems. Signals are emitted for every listitem in the same order: 1. [signal@Gtk.SignalListItemFactory::setup] is emitted to set up permanent things on the listitem. This usually means constructing the widgets used in the row and adding them to the listitem. 2. [signal@Gtk.SignalListItemFactory::bind] is emitted to bind the item passed via [property@Gtk.ListItem:item] to the widgets that have been created in step 1 or to add item-specific widgets. Signals are connected to listen to changes - both to changes in the item to update the widgets or to changes in the widgets to update the item. After this signal has been called, the listitem may be shown in a list widget. 3. [signal@Gtk.SignalListItemFactory::unbind] is emitted to undo everything done in step 2. Usually this means disconnecting signal handlers. Once this signal has been called, the listitem will no longer be used in a list widget. 4. [signal@Gtk.SignalListItemFactory::bind] and [signal@Gtk.SignalListItemFactory::unbind] may be emitted multiple times again to bind the listitem for use with new items. By reusing listitems, potentially costly setup can be avoided. However, it means code needs to make sure to properly clean up the listitem in step 3 so that no information from the previous use leaks into the next use. 5. [signal@Gtk.SignalListItemFactory::teardown] is emitted to allow undoing the effects of [signal@Gtk.SignalListItemFactory::setup]. After this signal was emitted on a listitem, the listitem will be destroyed and not be used again. Note that during the signal emissions, changing properties on the listitems passed will not trigger notify signals as the listitem's notifications are frozen. See g_object_freeze_notify() for details. For tracking changes in other properties in the listitem, the ::notify signal is recommended. The signal can be connected in the [signal@Gtk.SignalListItemFactory::setup] signal and removed again during [signal@Gtk.SignalListItemFactory::teardown]. Creates a new `GtkSignalListItemFactory`. You need to connect signal handlers before you use it. a new `GtkSignalListItemFactory` Emitted when an object has been bound, for example when a new [property@Gtk.ListItem:item] has been set on a listitem and should be bound for use. After this signal was emitted, the object might be shown in a [class@Gtk.ListView] or other widget. The [signal@Gtk.SignalListItemFactory::unbind] signal is the opposite of this signal and can be used to undo everything done in this signal. The `GObject` to bind Emitted when a new listitem has been created and needs to be setup for use. It is the first signal emitted for every listitem. The [signal@Gtk.SignalListItemFactory::teardown] signal is the opposite of this signal and can be used to undo everything done in this signal. The `GObject` to set up Emitted when an object is about to be destroyed. It is the last signal ever emitted for this @object. This signal is the opposite of the [signal@Gtk.SignalListItemFactory::setup] signal and should be used to undo everything done in that signal. The `GObject` to tear down Emitted when an object has been unbound from its item, for example when a listitem was removed from use in a list widget and its [property@Gtk.ListItem:item] is about to be unset. This signal is the opposite of the [signal@Gtk.SignalListItemFactory::bind] signal and should be used to undo everything done in that signal. The `GObject` to unbind `GtkSingleSelection` is a `GtkSelectionModel` that allows selecting a single item. Note that the selection is *persistent* -- if the selected item is removed and re-added in the same [signal@Gio.ListModel::items-changed] emission, it stays selected. In particular, this means that changing the sort order of an underlying sort model will preserve the selection. Creates a new selection to handle @model. a new `GtkSingleSelection` the `GListModel` to manage Checks if autoselect has been enabled or disabled via gtk_single_selection_set_autoselect(). %TRUE if autoselect is enabled a `GtkSingleSelection` If %TRUE, gtk_selection_model_unselect_item() is supported and allows unselecting the selected item. %TRUE to support unselecting a `GtkSingleSelection` Gets the model that @self is wrapping. The model being wrapped a `GtkSingleSelection` Gets the position of the selected item. If no item is selected, %GTK_INVALID_LIST_POSITION is returned. The position of the selected item a `GtkSingleSelection` Gets the selected item. If no item is selected, %NULL is returned. The selected item a `GtkSingleSelection` Enables or disables autoselect. If @autoselect is %TRUE, @self will enforce that an item is always selected. It will select a new item when the currently selected item is deleted and it will disallow unselecting the current item. a `GtkSingleSelection` %TRUE to always select an item If %TRUE, unselecting the current item via gtk_selection_model_unselect_item() is supported. Note that setting [property@Gtk.SingleSelection:autoselect] will cause unselecting to not work, so it practically makes no sense to set both at the same time the same time. a `GtkSingleSelection` %TRUE to allow unselecting Sets the model that @self should wrap. If @model is %NULL, @self will be empty. a `GtkSingleSelection` A `GListModel` to wrap Selects the item at the given position. If the list does not have an item at @position or %GTK_INVALID_LIST_POSITION is given, the behavior depends on the value of the [property@Gtk.SingleSelection:autoselect] property: If it is set, no change will occur and the old item will stay selected. If it is unset, the selection will be unset and no item will be selected. a `GtkSingleSelection` the item to select or %GTK_INVALID_LIST_POSITION If the selection will always select an item. If unselecting the selected item is allowed. The type of items. See [method@Gio.ListModel.get_item_type]. The model being managed. The number of items. See [method@Gio.ListModel.get_n_items]. Position of the selected item. The selected item. `GtkSizeGroup` groups widgets together so they all request the same size. This is typically useful when you want a column of widgets to have the same size, but you can’t use a `GtkGrid`. In detail, the size requested for each widget in a `GtkSizeGroup` is the maximum of the sizes that would have been requested for each widget in the size group if they were not in the size group. The mode of the size group (see [method@Gtk.SizeGroup.set_mode]) determines whether this applies to the horizontal size, the vertical size, or both sizes. Note that size groups only affect the amount of space requested, not the size that the widgets finally receive. If you want the widgets in a `GtkSizeGroup` to actually be the same size, you need to pack them in such a way that they get the size they request and not more. `GtkSizeGroup` objects are referenced by each widget in the size group, so once you have added all widgets to a `GtkSizeGroup`, you can drop the initial reference to the size group with g_object_unref(). If the widgets in the size group are subsequently destroyed, then they will be removed from the size group and drop their references on the size group; when all widgets have been removed, the size group will be freed. Widgets can be part of multiple size groups; GTK will compute the horizontal size of a widget from the horizontal requisition of all widgets that can be reached from the widget by a chain of size groups of type %GTK_SIZE_GROUP_HORIZONTAL or %GTK_SIZE_GROUP_BOTH, and the vertical size from the vertical requisition of all widgets that can be reached from the widget by a chain of size groups of type %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH. Note that only non-contextual sizes of every widget are ever consulted by size groups (since size groups have no knowledge of what size a widget will be allocated in one dimension, it cannot derive how much height a widget will receive for a given width). When grouping widgets that trade height for width in mode %GTK_SIZE_GROUP_VERTICAL or %GTK_SIZE_GROUP_BOTH: the height for the minimum width will be the requested height for all widgets in the group. The same is of course true when horizontally grouping width for height widgets. Widgets that trade height-for-width should set a reasonably large minimum width by way of [property@Gtk.Label:width-chars] for instance. Widgets with static sizes as well as widgets that grow (such as ellipsizing text) need no such considerations. # GtkSizeGroup as GtkBuildable Size groups can be specified in a UI definition by placing an `<object>` element with `class="GtkSizeGroup"` somewhere in the UI definition. The widgets that belong to the size group are specified by a `<widgets>` element that may contain multiple `<widget>` elements, one for each member of the size group. The ”name” attribute gives the id of the widget. An example of a UI definition fragment with `GtkSizeGroup`: ```xml <object class="GtkSizeGroup"> <property name="mode">horizontal</property> <widgets> <widget name="radio1"/> <widget name="radio2"/> </widgets> </object> ``` Create a new `GtkSizeGroup`. a newly created `GtkSizeGroup` the mode for the new size group. Adds a widget to a `GtkSizeGroup`. In the future, the requisition of the widget will be determined as the maximum of its requisition and the requisition of the other widgets in the size group. Whether this applies horizontally, vertically, or in both directions depends on the mode of the size group. See [method@Gtk.SizeGroup.set_mode]. When the widget is destroyed or no longer referenced elsewhere, it will be removed from the size group. a `GtkSizeGroup` the `GtkWidget` to add Gets the current mode of the size group. the current mode of the size group. a `GtkSizeGroup` Returns the list of widgets associated with @size_group. a `GSList` of widgets. The list is owned by GTK and should not be modified. a `GtkSizeGroup` Removes a widget from a `GtkSizeGroup`. a `GtkSizeGroup` the `GtkWidget` to remove Sets the `GtkSizeGroupMode` of the size group. The mode of the size group determines whether the widgets in the size group should all have the same horizontal requisition (%GTK_SIZE_GROUP_HORIZONTAL) all have the same vertical requisition (%GTK_SIZE_GROUP_VERTICAL), or should all have the same requisition in both directions (%GTK_SIZE_GROUP_BOTH). a `GtkSizeGroup` the mode to set for the size group. The direction in which the size group affects requested sizes. The mode of the size group determines the directions in which the size group affects the requested sizes of its component widgets. group has no effect group affects horizontal requisition group affects vertical requisition group affects both horizontal and vertical requisition Specifies a preference for height-for-width or width-for-height geometry management. Prefer height-for-width geometry management Prefer width-for-height geometry management Don’t trade height-for-width or width-for-height `GtkSliceListModel` is a list model that presents a slice of another model. This is useful when implementing paging by setting the size to the number of elements per page and updating the offset whenever a different page is opened. `GtkSliceListModel` passes through sections from the underlying model. Creates a new slice model. It presents the slice from @offset to offset + @size of the given @model. A new `GtkSliceListModel` The model to use the offset of the slice maximum size of the slice Gets the model that is currently being used or %NULL if none. The model in use a `GtkSliceListModel` Gets the offset set via gtk_slice_list_model_set_offset(). The offset a `GtkSliceListModel` Gets the size set via gtk_slice_list_model_set_size(). The size a `GtkSliceListModel` Sets the model to show a slice of. The model's item type must conform to @self's item type. a `GtkSliceListModel` The model to be sliced Sets the offset into the original model for this slice. If the offset is too large for the sliced model, @self will end up empty. a `GtkSliceListModel` the new offset to use Sets the maximum size. @self will never have more items than @size. It can however have fewer items if the offset is too large or the model sliced from doesn't have enough items. a `GtkSliceListModel` the maximum size The type of items. See [method@Gio.ListModel.get_item_type]. Child model to take slice from. The number of items. See [method@Gio.ListModel.get_n_items]. Offset of slice. Maximum size of slice. `GtkSnapshot` assists in creating [class@Gsk.RenderNode]s for widgets. It functions in a similar way to a cairo context, and maintains a stack of render nodes and their associated transformations. The node at the top of the stack is the one that `gtk_snapshot_append_…()` functions operate on. Use the `gtk_snapshot_push_…()` functions and [method@Snapshot.pop] to change the current node. The typical way to obtain a `GtkSnapshot` object is as an argument to the [vfunc@Gtk.Widget.snapshot] vfunc. If you need to create your own `GtkSnapshot`, use [ctor@Gtk.Snapshot.new]. Creates a new `GtkSnapshot`. a newly-allocated `GtkSnapshot` Appends a stroked border rectangle inside the given @outline. The four sides of the border can have different widths and colors. a `GtkSnapshot` the outline of the border the stroke width of the border on the top, right, bottom and left side respectively. the color used on the top, right, bottom and left side. Creates a new [class@Gsk.CairoNode] and appends it to the current render node of @snapshot, without changing the current node. a `cairo_t` suitable for drawing the contents of the newly created render node a `GtkSnapshot` the bounds for the new node Creates a new render node drawing the @color into the given @bounds and appends it to the current render node of @snapshot. You should try to avoid calling this function if @color is transparent. a `GtkSnapshot` the color to draw the bounds for the new node Appends a conic gradient node with the given stops to @snapshot. a `GtkSnapshot` the rectangle to render the gradient into the center point of the conic gradient the clockwise rotation in degrees of the starting angle. 0 means the starting angle is the top. the color stops defining the gradient the number of elements in @stops A convenience method to fill a path with a color. See [method@Gtk.Snapshot.push_fill] if you need to fill a path with more complex content than a color. a `GtkSnapshot` The path describing the area to fill The fill rule to use the color to fill the path with Appends an inset shadow into the box given by @outline. a `GtkSnapshot` outline of the region surrounded by shadow color of the shadow horizontal offset of shadow vertical offset of shadow how far the shadow spreads towards the inside how much blur to apply to the shadow Creates render nodes for rendering @layout in the given foregound @color and appends them to the current node of @snapshot without changing the current node. The current theme's foreground color for a widget can be obtained with [method@Gtk.Widget.get_color]. Note that if the layout does not produce any visible output, then nodes may not be added to the @snapshot. a `GtkSnapshot` the `PangoLayout` to render the foreground color to render the layout in Appends a linear gradient node with the given stops to @snapshot. a `GtkSnapshot` the rectangle to render the linear gradient into the point at which the linear gradient will begin the point at which the linear gradient will finish the color stops defining the gradient the number of elements in @stops Appends @node to the current render node of @snapshot, without changing the current node. If @snapshot does not have a current node yet, @node will become the initial node. a `GtkSnapshot` a `GskRenderNode` Appends an outset shadow node around the box given by @outline. a `GtkSnapshot` outline of the region surrounded by shadow color of the shadow horizontal offset of shadow vertical offset of shadow how far the shadow spreads towards the outside how much blur to apply to the shadow Appends a radial gradient node with the given stops to @snapshot. a `GtkSnapshot` the rectangle to render the readial gradient into the center point for the radial gradient the horizontal radius the vertical radius the start position (on the horizontal axis) the end position (on the horizontal axis) the color stops defining the gradient the number of elements in @stops Appends a repeating linear gradient node with the given stops to @snapshot. a `GtkSnapshot` the rectangle to render the linear gradient into the point at which the linear gradient will begin the point at which the linear gradient will finish the color stops defining the gradient the number of elements in @stops Appends a repeating radial gradient node with the given stops to @snapshot. a `GtkSnapshot` the rectangle to render the readial gradient into the center point for the radial gradient the horizontal radius the vertical radius the start position (on the horizontal axis) the end position (on the horizontal axis) the color stops defining the gradient the number of elements in @stops Creates a new render node drawing the @texture into the given @bounds and appends it to the current render node of @snapshot. In contrast to [method@Gtk.Snapshot.append_texture], this function provides control about how the filter that is used when scaling. a `GtkSnapshot` the texture to render the filter to use the bounds for the new node A convenience method to stroke a path with a color. See [method@Gtk.Snapshot.push_stroke] if you need to stroke a path with more complex content than a color. a `GtkSnapshot` The path describing the area to fill The stroke attributes the color to fill the path with Creates a new render node drawing the @texture into the given @bounds and appends it to the current render node of @snapshot. If the texture needs to be scaled to fill @bounds, linear filtering is used. See [method@Gtk.Snapshot.append_scaled_texture] if you need other filtering, such as nearest-neighbour. a `GtkSnapshot` the texture to render the bounds for the new node Returns the node that was constructed by @snapshot and frees @snapshot. See also [method@Gtk.Snapshot.to_node]. a newly-created [class@Gsk.RenderNode] a `GtkSnapshot` Returns a paintable for the node that was constructed by @snapshot and frees @snapshot. a newly-created [iface@Gdk.Paintable] a `GtkSnapshot` The size of the resulting paintable or %NULL to use the bounds of the snapshot Removes the top element from the stack of render nodes and adds it to the nearest [class@Gsk.GLShaderNode] below it. This must be called the same number of times as the number of textures is needed for the shader in [method@Gtk.Snapshot.push_gl_shader]. GTK's new Vulkan-focused rendering does not support this feature. Use [class@Gtk.GLArea] for OpenGL rendering. a `GtkSnapshot` Applies a perspective projection transform. See [method@Gsk.Transform.perspective] for a discussion on the details. a `GtkSnapshot` distance of the z=0 plane Removes the top element from the stack of render nodes, and appends it to the node underneath it. a `GtkSnapshot` Blends together two images with the given blend mode. Until the first call to [method@Gtk.Snapshot.pop], the bottom image for the blend operation will be recorded. After that call, the top image to be blended will be recorded until the second call to [method@Gtk.Snapshot.pop]. Calling this function requires two subsequent calls to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` blend mode to use Blurs an image. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the blur radius to use. Must be positive Clips an image to a rectangle. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the rectangle to clip to Modifies the colors of an image by applying an affine transformation in RGB space. In particular, the colors will be transformed by applying pixel = transpose(color_matrix) * pixel + color_offset for every pixel. The transformation operates on unpremultiplied colors, with color components ordered R, G, B, A. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the color matrix to use the color offset to use Snapshots a cross-fade operation between two images with the given @progress. Until the first call to [method@Gtk.Snapshot.pop], the start image will be snapshot. After that call, the end image will be recorded until the second call to [method@Gtk.Snapshot.pop]. Calling this function requires two subsequent calls to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` progress between 0.0 and 1.0 Inserts a debug node with a message. Debug nodes don't affect the rendering at all, but can be helpful in identifying parts of a render node tree dump, for example in the GTK inspector. a `GtkSnapshot` a printf-style format string arguments for @message Fills the area given by @path and @fill_rule with an image and discards everything outside of it. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. If you want to fill the path with a color, [method@Gtk.Snapshot.append_fill] may be more convenient. a `GtkSnapshot` The path describing the area to fill The fill rule to use Push a [class@Gsk.GLShaderNode]. The node uses the given [class@Gsk.GLShader] and uniform values Additionally this takes a list of @n_children other nodes which will be passed to the [class@Gsk.GLShaderNode]. The @take_args argument is a block of data to use for uniform arguments, as per types and offsets defined by the @shader. Normally this is generated by [method@Gsk.GLShader.format_args] or [struct@Gsk.ShaderArgsBuilder]. The snapshotter takes ownership of @take_args, so the caller should not free it after this. If the renderer doesn't support GL shaders, or if there is any problem when compiling the shader, then the node will draw pink. You should use [method@Gsk.GLShader.compile] to ensure the @shader will work for the renderer before using it. If the shader requires textures (see [method@Gsk.GLShader.get_n_textures]), then it is expected that you call [method@Gtk.Snapshot.gl_shader_pop_texture] the number of times that are required. Each of these calls will generate a node that is added as a child to the `GskGLShaderNode`, which in turn will render these offscreen and pass as a texture to the shader. Once all textures (if any) are pop:ed, you must call the regular [method@Gtk.Snapshot.pop]. If you want to use pre-existing textures as input to the shader rather than rendering new ones, use [method@Gtk.Snapshot.append_texture] to push a texture node. These will be used directly rather than being re-rendered. For details on how to write shaders, see [class@Gsk.GLShader]. GTK's new Vulkan-focused rendering does not support this feature. Use [class@Gtk.GLArea] for OpenGL rendering. a `GtkSnapshot` The code to run the rectangle to render into Data block with arguments for the shader. Until the first call to [method@Gtk.Snapshot.pop], the mask image for the mask operation will be recorded. After that call, the source image will be recorded until the second call to [method@Gtk.Snapshot.pop]. Calling this function requires 2 subsequent calls to gtk_snapshot_pop(). a #GtkSnapshot mask mode to use Modifies the opacity of an image. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the opacity to use Creates a node that repeats the child node. The child is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the bounds within which to repeat the bounds of the child or %NULL to use the full size of the collected child node Clips an image to a rounded rectangle. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the rounded rectangle to clip to Applies a shadow to an image. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. a `GtkSnapshot` the first shadow specification number of shadow specifications Strokes the given @path with the attributes given by @stroke and an image. The image is recorded until the next call to [method@Gtk.Snapshot.pop]. Note that the strokes are subject to the same transformation as everything else, so uneven scaling will cause horizontal and vertical strokes to have different widths. If you want to stroke the path with a color, [method@Gtk.Snapshot.append_stroke] may be more convenient. a #GtkSnapshot The path to stroke The stroke attributes Creates a render node for the CSS background according to @context, and appends it to the current node of @snapshot, without changing the current node. a `GtkSnapshot` the style context that defines the background X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Creates a render node for the focus outline according to @context, and appends it to the current node of @snapshot, without changing the current node. a `GtkSnapshot` the style context that defines the focus ring X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Creates a render node for the CSS border according to @context, and appends it to the current node of @snapshot, without changing the current node. a `GtkSnapshot` the style context that defines the frame X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Draws a text caret using @snapshot at the specified index of @layout. snapshot to render to a `GtkStyleContext` X origin Y origin the `PangoLayout` of the text the index in the `PangoLayout` the `PangoDirection` of the text Creates a render node for rendering @layout according to the style information in @context, and appends it to the current node of @snapshot, without changing the current node. a `GtkSnapshot` the style context that defines the text X origin of the rectangle Y origin of the rectangle the `PangoLayout` to render Restores @snapshot to the state saved by a preceding call to [method@Snapshot.save] and removes that state from the stack of saved states. a `GtkSnapshot` Rotates @@snapshot's coordinate system by @angle degrees in 2D space - or in 3D speak, rotates around the Z axis. The rotation happens around the origin point of (0, 0) in the @snapshot's current coordinate system. To rotate around axes other than the Z axis, use [method@Gsk.Transform.rotate_3d]. a `GtkSnapshot` the rotation angle, in degrees (clockwise) Rotates @snapshot's coordinate system by @angle degrees around @axis. For a rotation in 2D space, use [method@Gsk.Transform.rotate]. a `GtkSnapshot` the rotation angle, in degrees (clockwise) The rotation axis Makes a copy of the current state of @snapshot and saves it on an internal stack. When [method@Gtk.Snapshot.restore] is called, @snapshot will be restored to the saved state. Multiple calls to [method@Gtk.Snapshot.save] and [method@Gtk.Snapshot.restore] can be nested; each call to `gtk_snapshot_restore()` restores the state from the matching paired `gtk_snapshot_save()`. It is necessary to clear all saved states with corresponding calls to `gtk_snapshot_restore()`. a `GtkSnapshot` Scales @snapshot's coordinate system in 2-dimensional space by the given factors. Use [method@Gtk.Snapshot.scale_3d] to scale in all 3 dimensions. a `GtkSnapshot` scaling factor on the X axis scaling factor on the Y axis Scales @snapshot's coordinate system by the given factors. a `GtkSnapshot` scaling factor on the X axis scaling factor on the Y axis scaling factor on the Z axis Returns the render node that was constructed by @snapshot. Note that this function may return %NULL if nothing has been added to the snapshot or if its content does not produce pixels to be rendered. After calling this function, it is no longer possible to add more nodes to @snapshot. The only function that should be called after this is [method@GObject.Object.unref]. the constructed `GskRenderNode` or %NULL if there are no nodes to render. a `GtkSnapshot` Returns a paintable encapsulating the render node that was constructed by @snapshot. After calling this function, it is no longer possible to add more nodes to @snapshot. The only function that should be called after this is [method@GObject.Object.unref]. a new `GdkPaintable` a `GtkSnapshot` The size of the resulting paintable or %NULL to use the bounds of the snapshot Transforms @snapshot's coordinate system with the given @transform. a `GtkSnapshot` the transform to apply Transforms @snapshot's coordinate system with the given @matrix. a `GtkSnapshot` the matrix to multiply the transform with Translates @snapshot's coordinate system by @point in 2-dimensional space. a `GtkSnapshot` the point to translate the snapshot by Translates @snapshot's coordinate system by @point. a `GtkSnapshot` the point to translate the snapshot by A `GListModel` that sorts the elements of an underlying model according to a `GtkSorter`. The model is a stable sort. If two items compare equal according to the sorter, the one that appears first in the original model will also appear first after sorting. Note that if you change the sorter, the previous order will have no influence on the new order. If you want that, consider using a `GtkMultiSorter` and appending the previous sorter to it. The model can be set up to do incremental sorting, so that sorting long lists doesn't block the UI. See [method@Gtk.SortListModel.set_incremental] for details. `GtkSortListModel` is a generic model and because of that it cannot take advantage of any external knowledge when sorting. If you run into performance issues with `GtkSortListModel`, it is strongly recommended that you write your own sorting list model. `GtkSortListModel` allows sorting the items into sections. It implements `GtkSectionModel` and when [property@Gtk.SortListModel:section-sorter] is set, it will sort all items with that sorter and items comparing equal with it will be put into the same section. The [property@Gtk.SortListModel:sorter] will then be used to sort items inside their sections. Creates a new sort list model that uses the @sorter to sort @model. a new `GtkSortListModel` the model to sort the `GtkSorter` to sort @model with, Returns whether incremental sorting is enabled. See [method@Gtk.SortListModel.set_incremental]. %TRUE if incremental sorting is enabled a `GtkSortListModel` Gets the model currently sorted or %NULL if none. The model that gets sorted a `GtkSortListModel` Estimates progress of an ongoing sorting operation. The estimate is the number of items that would still need to be sorted to finish the sorting operation if this was a linear algorithm. So this number is not related to how many items are already correctly sorted. If you want to estimate the progress, you can use code like this: ```c pending = gtk_sort_list_model_get_pending (self); model = gtk_sort_list_model_get_model (self); progress = 1.0 - pending / (double) MAX (1, g_list_model_get_n_items (model)); ``` If no sort operation is ongoing - in particular when [property@Gtk.SortListModel:incremental] is %FALSE - this function returns 0. a progress estimate of remaining items to sort a `GtkSortListModel` Gets the section sorter that is used to sort items of @self into sections. the sorter of #self a `GtkSortListModel` Gets the sorter that is used to sort @self. the sorter of #self a `GtkSortListModel` Sets the sort model to do an incremental sort. When incremental sorting is enabled, the `GtkSortListModel` will not do a complete sort immediately, but will instead queue an idle handler that incrementally sorts the items towards their correct position. This of course means that items do not instantly appear in the right place. It also means that the total sorting time is a lot slower. When your filter blocks the UI while sorting, you might consider turning this on. Depending on your model and sorters, this may become interesting around 10,000 to 100,000 items. By default, incremental sorting is disabled. See [method@Gtk.SortListModel.get_pending] for progress information about an ongoing incremental sorting operation. a `GtkSortListModel` %TRUE to sort incrementally Sets the model to be sorted. The @model's item type must conform to the item type of @self. a `GtkSortListModel` The model to be sorted Sets a new section sorter on @self. a `GtkSortListModel` the `GtkSorter` to sort @model with Sets a new sorter on @self. a `GtkSortListModel` the `GtkSorter` to sort @model with If the model should sort items incrementally. The type of items. See [method@Gio.ListModel.get_item_type]. The model being sorted. The number of items. See [method@Gio.ListModel.get_n_items]. Estimate of unsorted items remaining. The section sorter for this model, if one is set. The sorter for this model. Determines the direction of a sort. Sorting is in ascending order. Sorting is in descending order. `GtkSorter` is an object to describe sorting criteria. Its primary user is [class@Gtk.SortListModel] The model will use a sorter to determine the order in which its items should appear by calling [method@Gtk.Sorter.compare] for pairs of items. Sorters may change their sorting behavior through their lifetime. In that case, they will emit the [signal@Gtk.Sorter::changed] signal to notify that the sort order is no longer valid and should be updated by calling gtk_sorter_compare() again. GTK provides various pre-made sorter implementations for common sorting operations. [class@Gtk.ColumnView] has built-in support for sorting lists via the [property@Gtk.ColumnViewColumn:sorter] property, where the user can change the sorting by clicking on list headers. Of course, in particular for large lists, it is also possible to subclass `GtkSorter` and provide one's own sorter. Compares two given items according to the sort order implemented by the sorter. Sorters implement a partial order: * It is reflexive, ie a = a * It is antisymmetric, ie if a < b and b < a, then a = b * It is transitive, ie given any 3 items with a ≤ b and b ≤ c, then a ≤ c The sorter may signal it conforms to additional constraints via the return value of [method@Gtk.Sorter.get_order]. %GTK_ORDERING_EQUAL if @item1 == @item2, %GTK_ORDERING_SMALLER if @item1 < @item2, %GTK_ORDERING_LARGER if @item1 > @item2 a `GtkSorter` first item to compare second item to compare Gets the order that @self conforms to. See [enum@Gtk.SorterOrder] for details of the possible return values. This function is intended to allow optimizations. The order a `GtkSorter` Notifies all users of the sorter that it has changed. This emits the [signal@Gtk.Sorter::changed] signal. Users of the sorter should then update the sort order via [method@Gtk.Sorter.compare]. Depending on the @change parameter, it may be possible to update the sort order without a full resorting. Refer to the [enum@Gtk.SorterChange] documentation for details. This function is intended for implementers of `GtkSorter` subclasses and should not be called from other functions. a `GtkSorter` How the sorter changed Compares two given items according to the sort order implemented by the sorter. Sorters implement a partial order: * It is reflexive, ie a = a * It is antisymmetric, ie if a < b and b < a, then a = b * It is transitive, ie given any 3 items with a ≤ b and b ≤ c, then a ≤ c The sorter may signal it conforms to additional constraints via the return value of [method@Gtk.Sorter.get_order]. %GTK_ORDERING_EQUAL if @item1 == @item2, %GTK_ORDERING_SMALLER if @item1 < @item2, %GTK_ORDERING_LARGER if @item1 > @item2 a `GtkSorter` first item to compare second item to compare Gets the order that @self conforms to. See [enum@Gtk.SorterOrder] for details of the possible return values. This function is intended to allow optimizations. The order a `GtkSorter` Emitted whenever the sorter changed. Users of the sorter should then update the sort order again via gtk_sorter_compare(). [class@Gtk.SortListModel] handles this signal automatically. Depending on the @change parameter, it may be possible to update the sort order without a full resorting. Refer to the [enum@Gtk.SorterChange] documentation for details. how the sorter changed Describes changes in a sorter in more detail and allows users to optimize resorting. The sorter change cannot be described by any of the other enumeration values The sort order was inverted. Comparisons that returned %GTK_ORDERING_SMALLER now return %GTK_ORDERING_LARGER and vice versa. Other comparisons return the same values as before. The sorter is less strict: Comparisons may now return %GTK_ORDERING_EQUAL that did not do so before. The sorter is more strict: Comparisons that did return %GTK_ORDERING_EQUAL may not do so anymore. The virtual table for `GtkSorter`. Compare two items. See gtk_sorter_compare() for details. %GTK_ORDERING_EQUAL if @item1 == @item2, %GTK_ORDERING_SMALLER if @item1 < @item2, %GTK_ORDERING_LARGER if @item1 > @item2 a `GtkSorter` first item to compare second item to compare Get the `GtkSorderOrder` that applies to the current sorter. If unimplemented, it returns %GTK_SORTER_ORDER_PARTIAL. The order a `GtkSorter` Describes the type of order that a `GtkSorter` may produce. A partial order. Any `GtkOrdering` is possible. No order, all elements are considered equal. gtk_sorter_compare() will only return %GTK_ORDERING_EQUAL. A total order. gtk_sorter_compare() will only return %GTK_ORDERING_EQUAL if an item is compared with itself. Two different items will never cause this value to be returned. A `GtkSpinButton` is an ideal way to allow the user to set the value of some attribute.  Rather than having to directly type a number into a `GtkEntry`, `GtkSpinButton` allows the user to click on one of two arrows to increment or decrement the displayed value. A value can still be typed in, with the bonus that it can be checked to ensure it is in a given range. The main properties of a `GtkSpinButton` are through an adjustment. See the [class@Gtk.Adjustment] documentation for more details about an adjustment's properties. Note that `GtkSpinButton` will by default make its entry large enough to accommodate the lower and upper bounds of the adjustment. If this is not desired, the automatic sizing can be turned off by explicitly setting [property@Gtk.Editable:width-chars] to a value != -1. ## Using a GtkSpinButton to get an integer ```c // Provides a function to retrieve an integer value from a GtkSpinButton // and creates a spin button to model percentage values. int grab_int_value (GtkSpinButton *button, gpointer user_data) { return gtk_spin_button_get_value_as_int (button); } void create_integer_spin_button (void) { GtkWidget *window, *button; GtkAdjustment *adjustment; adjustment = gtk_adjustment_new (50.0, 0.0, 100.0, 1.0, 5.0, 0.0); window = gtk_window_new (); // creates the spinbutton, with no decimal places button = gtk_spin_button_new (adjustment, 1.0, 0); gtk_window_set_child (GTK_WINDOW (window), button); gtk_window_present (GTK_WINDOW (window)); } ``` ## Using a GtkSpinButton to get a floating point value ```c // Provides a function to retrieve a floating point value from a // GtkSpinButton, and creates a high precision spin button. float grab_float_value (GtkSpinButton *button, gpointer user_data) { return gtk_spin_button_get_value (button); } void create_floating_spin_button (void) { GtkWidget *window, *button; GtkAdjustment *adjustment; adjustment = gtk_adjustment_new (2.500, 0.0, 5.0, 0.001, 0.1, 0.0); window = gtk_window_new (); // creates the spinbutton, with three decimal places button = gtk_spin_button_new (adjustment, 0.001, 3); gtk_window_set_child (GTK_WINDOW (window), button); gtk_window_present (GTK_WINDOW (window)); } ``` # Shortcuts and Gestures The following signals have default keybindings: - [signal@Gtk.SpinButton::change-value] # CSS nodes ``` spinbutton.horizontal ├── text │ ├── undershoot.left │ ╰── undershoot.right ├── button.down ╰── button.up ``` ``` spinbutton.vertical ├── button.up ├── text │ ├── undershoot.left │ ╰── undershoot.right ╰── button.down ``` `GtkSpinButton`s main CSS node has the name spinbutton. It creates subnodes for the entry and the two buttons, with these names. The button nodes have the style classes .up and .down. The `GtkText` subnodes (if present) are put below the text node. The orientation of the spin button is reflected in the .vertical or .horizontal style class on the main node. # Accessibility `GtkSpinButton` uses the %GTK_ACCESSIBLE_ROLE_SPIN_BUTTON role. Creates a new `GtkSpinButton`. The new `GtkSpinButton` the `GtkAdjustment` that this spin button should use specifies by how much the rate of change in the value will accelerate if you continue to hold down an up/down button or arrow key the number of decimal places to display Creates a new `GtkSpinButton` with the given properties. This is a convenience constructor that allows creation of a numeric `GtkSpinButton` without manually creating an adjustment. The value is initially set to the minimum value and a page increment of 10 * @step is the default. The precision of the spin button is equivalent to the precision of @step. Note that the way in which the precision is derived works best if @step is a power of ten. If the resulting precision is not suitable for your needs, use [method@Gtk.SpinButton.set_digits] to correct it. The new `GtkSpinButton` Minimum allowable value Maximum allowable value Increment added or subtracted by spinning the widget Changes the properties of an existing spin button. The adjustment, climb rate, and number of decimal places are updated accordingly. a `GtkSpinButton` a `GtkAdjustment` to replace the spin button’s existing adjustment, or %NULL to leave its current adjustment unchanged the new climb rate the number of decimal places to display in the spin button Retrieves the value set by [method@Gtk.SpinButton.set_activates_default]. %TRUE if the spin button will activate the default widget a `GtkSpinButton` Get the adjustment associated with a `GtkSpinButton`. the `GtkAdjustment` of @spin_button a `GtkSpinButton` Returns the acceleration rate for repeated changes. the acceleration rate a `GtkSpinButton` Fetches the precision of @spin_button. the current precision a `GtkSpinButton` Gets the current step and page the increments used by @spin_button. See [method@Gtk.SpinButton.set_increments]. a `GtkSpinButton` location to store step increment location to store page increment Returns whether non-numeric text can be typed into the spin button. %TRUE if only numeric text can be entered a `GtkSpinButton` Gets the range allowed for @spin_button. See [method@Gtk.SpinButton.set_range]. a `GtkSpinButton` location to store minimum allowed value location to store maximum allowed value Returns whether the values are corrected to the nearest step. %TRUE if values are snapped to the nearest step a `GtkSpinButton` Gets the update behavior of a spin button. See [method@Gtk.SpinButton.set_update_policy]. the current update policy a `GtkSpinButton` Get the value in the @spin_button. the value of @spin_button a `GtkSpinButton` Get the value @spin_button represented as an integer. the value of @spin_button a `GtkSpinButton` Returns whether the spin button’s value wraps around to the opposite limit when the upper or lower limit of the range is exceeded. %TRUE if the spin button wraps around a `GtkSpinButton` Sets whether activating the spin button will activate the default widget for the window containing the spin button. See [signal@Gtk.SpinButton::activate] for what counts as activation. a `GtkSpinButton` %TRUE to activate window’s default widget on activation Replaces the `GtkAdjustment` associated with @spin_button. a `GtkSpinButton` a `GtkAdjustment` to replace the existing adjustment Sets the acceleration rate for repeated changes when you hold down a button or key. a `GtkSpinButton` the rate of acceleration, must be >= 0 Set the precision to be displayed by @spin_button. Up to 20 digit precision is allowed. a `GtkSpinButton` the number of digits after the decimal point to be displayed for the spin button’s value Sets the step and page increments for spin_button. This affects how quickly the value changes when the spin button’s arrows are activated. a `GtkSpinButton` increment applied for a button 1 press. increment applied for a button 2 press. Sets the flag that determines if non-numeric text can be typed into the spin button. a `GtkSpinButton` flag indicating if only numeric entry is allowed Sets the minimum and maximum allowable values for @spin_button. If the current value is outside this range, it will be adjusted to fit within the range, otherwise it will remain unchanged. a `GtkSpinButton` minimum allowable value maximum allowable value Sets the policy as to whether values are corrected to the nearest step increment when a spin button is activated after providing an invalid value. a `GtkSpinButton` a flag indicating if invalid values should be corrected Sets the update behavior of a spin button. This determines whether the spin button is always updated or only when a valid value is set. a `GtkSpinButton` a `GtkSpinButtonUpdatePolicy` value Sets the value of @spin_button. a `GtkSpinButton` the new value Sets the flag that determines if a spin button value wraps around to the opposite limit when the upper or lower limit of the range is exceeded. a `GtkSpinButton` a flag indicating if wrapping behavior is performed Increment or decrement a spin button’s value in a specified direction by a specified amount. a `GtkSpinButton` a `GtkSpinType` indicating the direction to spin step increment to apply in the specified direction Manually force an update of the spin button. a `GtkSpinButton` Whether to activate the default widget when the spin button is activated. See [signal@Gtk.SpinButton::activate] for what counts as activation. The adjustment that holds the value of the spin button. The acceleration rate when you hold down a button or key. The number of decimal places to display. Whether non-numeric characters should be ignored. Whether erroneous values are automatically changed to the spin buttons nearest step increment. Whether the spin button should update always, or only when the value is acceptable. The current value. Whether a spin button should wrap upon reaching its limits. Emitted when the spin button is activated. The keybindings for this signal are all forms of the <kbd>Enter</kbd> key. If the <kbd>Enter</kbd> key results in the value being committed to the spin button, then activation does not occur until <kbd>Enter</kbd> is pressed again. Emitted when the user initiates a value change. This is a [keybinding signal](class.SignalAction.html). Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal are Up/Down and PageUp/PageDown. a `GtkScrollType` to specify the speed and amount of change Emitted to convert the users input into a double value. The signal handler is expected to use [method@Gtk.Editable.get_text] to retrieve the text of the spinbutton and set @new_value to the new value. The default conversion uses g_strtod(). %TRUE for a successful conversion, %FALSE if the input was not handled, and %GTK_INPUT_ERROR if the conversion failed. return location for the new value Emitted to tweak the formatting of the value for display. ```c // show leading zeros static gboolean on_output (GtkSpinButton *spin, gpointer data) { char *text; int value; value = gtk_spin_button_get_value_as_int (spin); text = g_strdup_printf ("%02d", value); gtk_editable_set_text (GTK_EDITABLE (spin), text): g_free (text); return TRUE; } ``` %TRUE if the value has been displayed Emitted when the value is changed. Also see the [signal@Gtk.SpinButton::output] signal. Emitted right after the spinbutton wraps from its maximum to its minimum value or vice-versa. Determines whether the spin button displays values outside the adjustment bounds. See [method@Gtk.SpinButton.set_update_policy]. When refreshing your `GtkSpinButton`, the value is always displayed When refreshing your `GtkSpinButton`, the value is only displayed if it is valid within the bounds of the spin button's adjustment The values of the GtkSpinType enumeration are used to specify the change to make in gtk_spin_button_spin(). Increment by the adjustments step increment. Decrement by the adjustments step increment. Increment by the adjustments page increment. Decrement by the adjustments page increment. Go to the adjustments lower bound. Go to the adjustments upper bound. Change by a specified amount. A `GtkSpinner` widget displays an icon-size spinning animation. It is often used as an alternative to a [class@Gtk.ProgressBar] for displaying indefinite activity, instead of actual progress.  To start the animation, use [method@Gtk.Spinner.start], to stop it use [method@Gtk.Spinner.stop]. # CSS nodes `GtkSpinner` has a single CSS node with the name spinner. When the animation is active, the :checked pseudoclass is added to this node. Returns a new spinner widget. Not yet started. a new `GtkSpinner` Returns whether the spinner is spinning. %TRUE if the spinner is active a `GtkSpinner` Sets the activity of the spinner. a `GtkSpinner` whether the spinner should be spinning Starts the animation of the spinner. a `GtkSpinner` Stops the animation of the spinner. a `GtkSpinner` Whether the spinner is spinning `GtkStack` is a container which only shows one of its children at a time. In contrast to `GtkNotebook`, `GtkStack` does not provide a means for users to change the visible child. Instead, a separate widget such as [class@Gtk.StackSwitcher] or [class@Gtk.StackSidebar] can be used with `GtkStack` to provide this functionality. Transitions between pages can be animated as slides or fades. This can be controlled with [method@Gtk.Stack.set_transition_type]. These animations respect the [property@Gtk.Settings:gtk-enable-animations] setting. `GtkStack` maintains a [class@Gtk.StackPage] object for each added child, which holds additional per-child properties. You obtain the `GtkStackPage` for a child with [method@Gtk.Stack.get_page] and you can obtain a `GtkSelectionModel` containing all the pages with [method@Gtk.Stack.get_pages]. # GtkStack as GtkBuildable To set child-specific properties in a .ui file, create `GtkStackPage` objects explicitly, and set the child widget as a property on it: ```xml <object class="GtkStack" id="stack"> <child> <object class="GtkStackPage"> <property name="name">page1</property> <property name="title">In the beginning…</property> <property name="child"> <object class="GtkLabel"> <property name="label">It was dark</property> </object> </property> </object> </child> ``` # CSS nodes `GtkStack` has a single CSS node named stack. # Accessibility `GtkStack` uses the %GTK_ACCESSIBLE_ROLE_TAB_PANEL for the stack pages, which are the accessible parent objects of the child widgets. Creates a new `GtkStack`. a new `GtkStack` Adds a child to @stack. the `GtkStackPage` for @child a `GtkStack` the widget to add Adds a child to @stack. The child is identified by the @name. the `GtkStackPage` for @child a `GtkStack` the widget to add the name for @child Adds a child to @stack. The child is identified by the @name. The @title will be used by `GtkStackSwitcher` to represent @child in a tab bar, so it should be short. the `GtkStackPage` for @child a `GtkStack` the widget to add the name for @child a human-readable title for @child Finds the child with the name given as the argument. Returns %NULL if there is no child with this name. the requested child of the `GtkStack` a `GtkStack` the name of the child to find Gets whether @stack is horizontally homogeneous. whether @stack is horizontally homogeneous. a `GtkStack` Returns whether the `GtkStack` is set up to interpolate between the sizes of children on page switch. %TRUE if child sizes are interpolated A `GtkStack` Returns the `GtkStackPage` object for @child. the `GtkStackPage` for @child a `GtkStack` a child of @stack Returns a `GListModel` that contains the pages of the stack. This can be used to keep an up-to-date view. The model also implements [iface@Gtk.SelectionModel] and can be used to track and modify the visible page. a `GtkSelectionModel` for the stack's children a `GtkStack` Returns the amount of time (in milliseconds) that transitions between pages in @stack will take. the transition duration a `GtkStack` Returns whether the @stack is currently in a transition from one page to another. %TRUE if the transition is currently running, %FALSE otherwise. a `GtkStack` Gets the type of animation that will be used for transitions between pages in @stack. the current transition type of @stack a `GtkStack` Gets whether @stack is vertically homogeneous. whether @stack is vertically homogeneous. a `GtkStack` Gets the currently visible child of @stack. Returns %NULL if there are no visible children. the visible child of the `GtkStack` a `GtkStack` Returns the name of the currently visible child of @stack. Returns %NULL if there is no visible child. the name of the visible child of the `GtkStack` a `GtkStack` Removes a child widget from @stack. a `GtkStack` the child to remove Sets the `GtkStack` to be horizontally homogeneous or not. If it is homogeneous, the `GtkStack` will request the same width for all its children. If it isn't, the stack may change width when a different child becomes visible. a `GtkStack` %TRUE to make @stack horizontally homogeneous Sets whether or not @stack will interpolate its size when changing the visible child. If the [property@Gtk.Stack:interpolate-size] property is set to %TRUE, @stack will interpolate its size between the current one and the one it'll take after changing the visible child, according to the set transition duration. A `GtkStack` the new value Sets the duration that transitions between pages in @stack will take. a `GtkStack` the new duration, in milliseconds Sets the type of animation that will be used for transitions between pages in @stack. Available types include various kinds of fades and slides. The transition type can be changed without problems at runtime, so it is possible to change the animation based on the page that is about to become current. a `GtkStack` the new transition type Sets the `GtkStack` to be vertically homogeneous or not. If it is homogeneous, the `GtkStack` will request the same height for all its children. If it isn't, the stack may change height when a different child becomes visible. a `GtkStack` %TRUE to make @stack vertically homogeneous Makes @child the visible child of @stack. If @child is different from the currently visible child, the transition between the two will be animated with the current transition type of @stack. Note that the @child widget has to be visible itself (see [method@Gtk.Widget.show]) in order to become the visible child of @stack. a `GtkStack` a child of @stack Makes the child with the given name visible. Note that the child widget has to be visible itself (see [method@Gtk.Widget.show]) in order to become the visible child of @stack. a `GtkStack` the name of the child to make visible the transition type to use Makes the child with the given name visible. If @child is different from the currently visible child, the transition between the two will be animated with the current transition type of @stack. Note that the child widget has to be visible itself (see [method@Gtk.Widget.show]) in order to become the visible child of @stack. a `GtkStack` the name of the child to make visible %TRUE if the stack allocates the same width for all children. Whether or not the size should smoothly change during the transition. A selection model with the stack pages. The animation duration, in milliseconds. Whether or not the transition is currently running. The type of animation used to transition. %TRUE if the stack allocates the same height for all children. The widget currently visible in the stack. The name of the widget currently visible in the stack. `GtkStackPage` is an auxiliary class used by `GtkStack`. Returns the stack child to which @self belongs. the child to which @self belongs a `GtkStackPage` Returns the icon name of the page. The value of the [property@Gtk.StackPage:icon-name] property a `GtkStackPage` Returns the name of the page. The value of the [property@Gtk.StackPage:name] property a `GtkStackPage` Returns whether the page is marked as “needs attention”. The value of the [property@Gtk.StackPage:needs-attention] property. a `GtkStackPage` Gets the page title. The value of the [property@Gtk.StackPage:title] property a `GtkStackPage` Gets whether underlines in the page title indicate mnemonics. The value of the [property@Gtk.StackPage:use-underline] property a `GtkStackPage` Returns whether @page is visible in its `GtkStack`. This is independent from the [property@Gtk.Widget:visible] property of its widget. %TRUE if @page is visible a `GtkStackPage` Sets the icon name of the page. a `GtkStackPage` the new value to set Sets the name of the page. a `GtkStackPage` the new value to set Sets whether the page is marked as “needs attention”. a `GtkStackPage` the new value to set Sets the page title. a `GtkStackPage` the new value to set Sets whether underlines in the page title indicate mnemonics. a `GtkStackPage` the new value to set Sets whether @page is visible in its `GtkStack`. a `GtkStackPage` The new property value The child that this page is for. The icon name of the child page. The name of the child page. Whether the page requires the user attention. This is used by the [class@Gtk.StackSwitcher] to change the appearance of the corresponding button when a page needs attention and it is not the current one. The title of the child page. If set, an underline in the title indicates a mnemonic. Whether this page is visible. A `GtkStackSidebar` uses a sidebar to switch between `GtkStack` pages. In order to use a `GtkStackSidebar`, you simply use a `GtkStack` to organize your UI flow, and add the sidebar to your sidebar area. You can use [method@Gtk.StackSidebar.set_stack] to connect the `GtkStackSidebar` to the `GtkStack`. # CSS nodes `GtkStackSidebar` has a single CSS node with name stacksidebar and style class .sidebar. When circumstances require it, `GtkStackSidebar` adds the .needs-attention style class to the widgets representing the stack pages. Creates a new `GtkStackSidebar`. the new `GtkStackSidebar` Retrieves the stack. the associated `GtkStack` or %NULL if none has been set explicitly a `GtkStackSidebar` Set the `GtkStack` associated with this `GtkStackSidebar`. The sidebar widget will automatically update according to the order and items within the given `GtkStack`. a `GtkStackSidebar` a `GtkStack` The stack. The `GtkStackSwitcher` shows a row of buttons to switch between `GtkStack` pages.  It acts as a controller for the associated `GtkStack`. All the content for the buttons comes from the properties of the stacks [class@Gtk.StackPage] objects; the button visibility in a `GtkStackSwitcher` widget is controlled by the visibility of the child in the `GtkStack`. It is possible to associate multiple `GtkStackSwitcher` widgets with the same `GtkStack` widget. # CSS nodes `GtkStackSwitcher` has a single CSS node named stackswitcher and style class .stack-switcher. When circumstances require it, `GtkStackSwitcher` adds the .needs-attention style class to the widgets representing the stack pages. # Accessibility `GtkStackSwitcher` uses the %GTK_ACCESSIBLE_ROLE_TAB_LIST role and uses the %GTK_ACCESSIBLE_ROLE_TAB for its buttons. # Orientable Since GTK 4.4, `GtkStackSwitcher` implements `GtkOrientable` allowing the stack switcher to be made vertical with `gtk_orientable_set_orientation()`. Create a new `GtkStackSwitcher`. a new `GtkStackSwitcher`. Retrieves the stack. the stack a `GtkStackSwitcher` Sets the stack to control. a `GtkStackSwitcher` a `GtkStack` The stack. Possible transitions between pages in a `GtkStack` widget. New values may be added to this enumeration over time. No transition A cross-fade Slide from left to right Slide from right to left Slide from bottom up Slide from top down Slide from left or right according to the children order Slide from top down or bottom up according to the order Cover the old page by sliding up Cover the old page by sliding down Cover the old page by sliding to the left Cover the old page by sliding to the right Uncover the new page by sliding up Uncover the new page by sliding down Uncover the new page by sliding to the left Uncover the new page by sliding to the right Cover the old page sliding up or uncover the new page sliding down, according to order Cover the old page sliding down or uncover the new page sliding up, according to order Cover the old page sliding left or uncover the new page sliding right, according to order Cover the old page sliding right or uncover the new page sliding left, according to order Pretend the pages are sides of a cube and rotate that cube to the left Pretend the pages are sides of a cube and rotate that cube to the right Pretend the pages are sides of a cube and rotate that cube to the left or right according to the children order Describes a widget state. Widget states are used to match the widget against CSS pseudo-classes. Note that GTK extends the regular CSS classes and sometimes uses different names. State during normal operation Widget is active Widget has a mouse pointer over it Widget is selected Widget is insensitive Widget is inconsistent Widget has the keyboard focus Widget is in a background toplevel window Widget is in left-to-right text direction Widget is in right-to-left text direction Widget is a link The location the widget points to has already been visited Widget is checked Widget is highlighted as a drop target for DND Widget has the visible focus Widget contains the keyboard focus A `GtkStatusbar` widget is usually placed along the bottom of an application's main [class@Gtk.Window].  A `GtkStatusBar` may provide a regular commentary of the application's status (as is usually the case in a web browser, for example), or may be used to simply output a message when the status changes, (when an upload is complete in an FTP client, for example). Status bars in GTK maintain a stack of messages. The message at the top of the each bar’s stack is the one that will currently be displayed. Any messages added to a statusbar’s stack must specify a context id that is used to uniquely identify the source of a message. This context id can be generated by [method@Gtk.Statusbar.get_context_id], given a message and the statusbar that it will be added to. Note that messages are stored in a stack, and when choosing which message to display, the stack structure is adhered to, regardless of the context identifier of a message. One could say that a statusbar maintains one stack of messages for display purposes, but allows multiple message producers to maintain sub-stacks of the messages they produced (via context ids). Status bars are created using [ctor@Gtk.Statusbar.new]. Messages are added to the bar’s stack with [method@Gtk.Statusbar.push]. The message at the top of the stack can be removed using [method@Gtk.Statusbar.pop]. A message can be removed from anywhere in the stack if its message id was recorded at the time it was added. This is done using [method@Gtk.Statusbar.remove]. ## CSS node `GtkStatusbar` has a single CSS node with name `statusbar`. This widget will be removed in GTK 5 Creates a new `GtkStatusbar` ready for messages. This widget will be removed in GTK 5 the new `GtkStatusbar` Returns a new context identifier, given a description of the actual context. Note that the description is not shown in the UI. This widget will be removed in GTK 5 an integer id a `GtkStatusbar` textual description of what context the new message is being used in Removes the first message in the `GtkStatusbar`’s stack with the given context id. Note that this may not change the displayed message, if the message at the top of the stack has a different context id. This widget will be removed in GTK 5 a `GtkStatusbar` a context identifier Pushes a new message onto a statusbar’s stack. This widget will be removed in GTK 5 a message id that can be used with [method@Gtk.Statusbar.remove]. a `GtkStatusbar` the message’s context id, as returned by gtk_statusbar_get_context_id() the message to add to the statusbar Forces the removal of a message from a statusbar’s stack. The exact @context_id and @message_id must be specified. This widget will be removed in GTK 5 a `GtkStatusbar` a context identifier a message identifier, as returned by [method@Gtk.Statusbar.push] Forces the removal of all messages from a statusbar's stack with the exact @context_id. This widget will be removed in GTK 5 a `GtkStatusbar` a context identifier Emitted whenever a new message is popped off a statusbar's stack. This widget will be removed in GTK 5 the context id of the relevant message/statusbar the message that was just popped Emitted whenever a new message gets pushed onto a statusbar's stack. This widget will be removed in GTK 5 the context id of the relevant message/statusbar the message that was pushed `GtkStringFilter` determines whether to include items by comparing strings to a fixed search term. The strings are obtained from the items by evaluating a `GtkExpression` set with [method@Gtk.StringFilter.set_expression], and they are compared against a search term set with [method@Gtk.StringFilter.set_search]. `GtkStringFilter` has several different modes of comparison - it can match the whole string, just a prefix, or any substring. Use [method@Gtk.StringFilter.set_match_mode] choose a mode. It is also possible to make case-insensitive comparisons, with [method@Gtk.StringFilter.set_ignore_case]. Creates a new string filter. You will want to set up the filter by providing a string to search for and by providing a property to look up on the item. a new `GtkStringFilter` The expression to evaluate Gets the expression that the string filter uses to obtain strings from items. a `GtkExpression` a `GtkStringFilter` Returns whether the filter ignores case differences. %TRUE if the filter ignores case a `GtkStringFilter` Returns the match mode that the filter is using. the match mode of the filter a `GtkStringFilter` Gets the search term. The search term a `GtkStringFilter` Sets the expression that the string filter uses to obtain strings from items. The expression must have a value type of %G_TYPE_STRING. a `GtkStringFilter` a `GtkExpression` Sets whether the filter ignores case differences. a `GtkStringFilter` %TRUE to ignore case Sets the match mode for the filter. a `GtkStringFilter` the new match mode Sets the string to search for. a `GtkStringFilter` The string to search for or %NULL to clear the search The expression to evaluate on item to get a string to compare with. If matching is case sensitive. If exact matches are necessary or if substrings are allowed. The search term. Specifies how search strings are matched inside text. The search string and text must match exactly. The search string must be contained as a substring inside the text. The text must begin with the search string. `GtkStringList` is a list model that wraps an array of strings. The objects in the model are of type [class@Gtk.StringObject] and have a "string" property that can be used inside expressions. `GtkStringList` is well-suited for any place where you would typically use a `char*[]`, but need a list model. ## GtkStringList as GtkBuildable The `GtkStringList` implementation of the `GtkBuildable` interface supports adding items directly using the `<items>` element and specifying `<item>` elements for each item. Each `<item>` element supports the regular translation attributes “translatable”, “context” and “comments”. Here is a UI definition fragment specifying a `GtkStringList` ```xml <object class="GtkStringList"> <items> <item translatable="yes">Factory</item> <item translatable="yes">Home</item> <item translatable="yes">Subway</item> </items> </object> ``` Creates a new `GtkStringList` with the given @strings. a new `GtkStringList` The strings to put in the model Appends @string to @self. The @string will be copied. See [method@Gtk.StringList.take] for a way to avoid that. a `GtkStringList` the string to insert Gets the string that is at @position in @self. If @self does not contain @position items, %NULL is returned. This function returns the const char *. To get the object wrapping it, use g_list_model_get_item(). the string at the given position a `GtkStringList` the position to get the string for Removes the string at @position from @self. @position must be smaller than the current length of the list. a `GtkStringList` the position of the string that is to be removed Changes @self by removing @n_removals strings and adding @additions to it. This function is more efficient than [method@Gtk.StringList.append] and [method@Gtk.StringList.remove], because it only emits the ::items-changed signal once for the change. This function copies the strings in @additions. The parameters @position and @n_removals must be correct (ie: @position + @n_removals must be less than or equal to the length of the list at the time this function is called). a `GtkStringList` the position at which to make the change the number of strings to remove The strings to add Adds @string to self at the end, and takes ownership of it. This variant of [method@Gtk.StringList.append] is convenient for formatting strings: ```c gtk_string_list_take (self, g_strdup_print ("%d dollars", lots)); ``` a `GtkStringList` the string to insert The type of items. See [method@Gio.ListModel.get_item_type]. The number of items. See [method@Gio.ListModel.get_n_items]. The strings in the model. `GtkStringObject` is the type of items in a `GtkStringList`. A `GtkStringObject` is a wrapper around a `const char*`; it has a [property@Gtk.StringObject:string] property that can be used for property bindings and expressions. Wraps a string in an object for use with `GListModel`. a new `GtkStringObject` The string to wrap Returns the string contained in a `GtkStringObject`. the string of @self a `GtkStringObject` The string. `GtkStringSorter` is a `GtkSorter` that compares strings. It does the comparison in a linguistically correct way using the current locale by normalizing Unicode strings and possibly case-folding them before performing the comparison. To obtain the strings to compare, this sorter evaluates a [class@Gtk.Expression]. Creates a new string sorter that compares items using the given @expression. Unless an expression is set on it, this sorter will always compare items as invalid. a new `GtkStringSorter` The expression to evaluate Gets which collation method the sorter uses. The collation method a `GtkStringSorter` Gets the expression that is evaluated to obtain strings from items. a `GtkExpression` a `GtkStringSorter` Gets whether the sorter ignores case differences. %TRUE if @self is ignoring case differences a `GtkStringSorter` Sets the collation method to use for sorting. a `GtkStringSorter` the collation method Sets the expression that is evaluated to obtain strings from items. The expression must have the type %G_TYPE_STRING. a `GtkStringSorter` a `GtkExpression` Sets whether the sorter will ignore case differences. a `GtkStringSorter` %TRUE to ignore case differences The collation method to use for sorting. The `GTK_COLLATION_NONE` value is useful when the expression already returns collation keys, or strings that need to be compared byte-by-byte. The default value, `GTK_COLLATION_UNICODE`, compares strings according to the [Unicode collation algorithm](https://www.unicode.org/reports/tr10/). The expression to evaluate on item to get a string to compare with. If sorting is case sensitive. `GtkStyleContext` stores styling information affecting a widget. In order to construct the final style information, `GtkStyleContext` queries information from all attached `GtkStyleProviders`. Style providers can be either attached explicitly to the context through [method@Gtk.StyleContext.add_provider], or to the display through [func@Gtk.StyleContext.add_provider_for_display]. The resulting style is a combination of all providers’ information in priority order. For GTK widgets, any `GtkStyleContext` returned by [method@Gtk.Widget.get_style_context] will already have a `GdkDisplay` and RTL/LTR information set. The style context will also be updated automatically if any of these settings change on the widget. ## Style Classes Widgets can add style classes to their context, which can be used to associate different styles by class. The documentation for individual widgets lists which style classes it uses itself, and which style classes may be added by applications to affect their appearance. # Custom styling in UI libraries and applications If you are developing a library with custom widgets that render differently than standard components, you may need to add a `GtkStyleProvider` yourself with the %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK priority, either a `GtkCssProvider` or a custom object implementing the `GtkStyleProvider` interface. This way themes may still attempt to style your UI elements in a different way if needed so. If you are using custom styling on an applications, you probably want then to make your style information prevail to the theme’s, so you must use a `GtkStyleProvider` with the %GTK_STYLE_PROVIDER_PRIORITY_APPLICATION priority, keep in mind that the user settings in `XDG_CONFIG_HOME/gtk-4.0/gtk.css` will still take precedence over your changes, as it uses the %GTK_STYLE_PROVIDER_PRIORITY_USER priority. The relevant API has been moved to [class@Gtk.Widget] where applicable; otherwise, there is no replacement for querying the style machinery. Stylable UI elements should use widgets. Adds a global style provider to @display, which will be used in style construction for all `GtkStyleContexts` under @display. GTK uses this to make styling information from `GtkSettings` available. Note: If both priorities are the same, A `GtkStyleProvider` added through [method@Gtk.StyleContext.add_provider] takes precedence over another added through this function. a `GdkDisplay` a `GtkStyleProvider` the priority of the style provider. The lower it is, the earlier it will be used in the style construction. Typically this will be in the range between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and %GTK_STYLE_PROVIDER_PRIORITY_USER Removes @provider from the global style providers list in @display. a `GdkDisplay` a `GtkStyleProvider` Adds a style class to @context, so later uses of the style context will make use of this new class for styling. In the CSS file format, a `GtkEntry` defining a “search” class, would be matched by: ```css entry.search { ... } ``` While any widget defining a “search” class would be matched by: ```css .search { ... } ``` Use [method@Gtk.Widget.add_css_class] instead a `GtkStyleContext` class name to use in styling Adds a style provider to @context, to be used in style construction. Note that a style provider added by this function only affects the style of the widget to which @context belongs. If you want to affect the style of all widgets, use [func@Gtk.StyleContext.add_provider_for_display]. Note: If both priorities are the same, a `GtkStyleProvider` added through this function takes precedence over another added through [func@Gtk.StyleContext.add_provider_for_display]. Use style classes instead a `GtkStyleContext` a `GtkStyleProvider` the priority of the style provider. The lower it is, the earlier it will be used in the style construction. Typically this will be in the range between %GTK_STYLE_PROVIDER_PRIORITY_FALLBACK and %GTK_STYLE_PROVIDER_PRIORITY_USER Gets the border for a given state as a `GtkBorder`. This api will be removed in GTK 5 a `GtkStyleContext` return value for the border settings Gets the foreground color for a given state. Use [method@Gtk.Widget.get_color] instead a `GtkStyleContext` return value for the foreground color Returns the `GdkDisplay` to which @context is attached. Use [method@Gtk.Widget.get_display] instead a `GdkDisplay`. a `GtkStyleContext` Gets the margin for a given state as a `GtkBorder`. This api will be removed in GTK 5 a `GtkStyleContext` return value for the margin settings Gets the padding for a given state as a `GtkBorder`. This api will be removed in GTK 5 a `GtkStyleContext` return value for the padding settings Returns the scale used for assets. Use [method@Gtk.Widget.get_scale_factor] instead the scale a `GtkStyleContext` Returns the state used for style matching. This method should only be used to retrieve the `GtkStateFlags` to pass to `GtkStyleContext` methods, like [method@Gtk.StyleContext.get_padding]. If you need to retrieve the current state of a `GtkWidget`, use [method@Gtk.Widget.get_state_flags]. Use [method@Gtk.Widget.get_state_flags] instead the state flags a `GtkStyleContext` Returns %TRUE if @context currently has defined the given class name. Use [method@Gtk.Widget.has_css_class] instead %TRUE if @context has @class_name defined a `GtkStyleContext` a class name Looks up and resolves a color name in the @context color map. This api will be removed in GTK 5 %TRUE if @color_name was found and resolved, %FALSE otherwise a `GtkStyleContext` color name to lookup Return location for the looked up color Removes @class_name from @context. Use [method@Gtk.Widget.remove_css_class] instead a `GtkStyleContext` class name to remove Removes @provider from the style providers list in @context. a `GtkStyleContext` a `GtkStyleProvider` Restores @context state to a previous stage. See [method@Gtk.StyleContext.save]. This API will be removed in GTK 5 a `GtkStyleContext` Saves the @context state. This allows temporary modifications done through [method@Gtk.StyleContext.add_class], [method@Gtk.StyleContext.remove_class], [method@Gtk.StyleContext.set_state] to be quickly reverted in one go through [method@Gtk.StyleContext.restore]. The matching call to [method@Gtk.StyleContext.restore] must be done before GTK returns to the main loop. This API will be removed in GTK 5 a `GtkStyleContext` Attaches @context to the given display. The display is used to add style information from “global” style providers, such as the display's `GtkSettings` instance. If you are using a `GtkStyleContext` returned from [method@Gtk.Widget.get_style_context], you do not need to call this yourself. You should not use this api a `GtkStyleContext` a `GdkDisplay` Sets the scale to use when getting image assets for the style. You should not use this api a `GtkStyleContext` scale Sets the state to be used for style matching. You should not use this api a `GtkStyleContext` state to represent Converts the style context into a string representation. The string representation always includes information about the name, state, id, visibility and style classes of the CSS node that is backing @context. Depending on the flags, more information may be included. This function is intended for testing and debugging of the CSS implementation in GTK. There are no guarantees about the format of the returned string, it may change. This api will be removed in GTK 5 a newly allocated string representing @context a `GtkStyleContext` Flags that determine what to print The display of the style context. Flags that modify the behavior of gtk_style_context_to_string(). New values may be added to this enumeration. Default value. Print the entire tree of CSS nodes starting at the style context's node Show the values of the CSS properties for each node Show information about what changes affect the styles `GtkStyleProvider` is an interface for style information used by `GtkStyleContext`. See [method@Gtk.StyleContext.add_provider] and [func@Gtk.StyleContext.add_provider_for_display] for adding `GtkStyleProviders`. GTK uses the `GtkStyleProvider` implementation for CSS in [class@Gtk.CssProvider]. `GtkSwitch` is a "light switch" that has two states: on or off.  The user can control which state should be active by clicking the empty area, or by dragging the slider. `GtkSwitch` can also express situations where the underlying state changes with a delay. In this case, the slider position indicates the user's recent change (represented by the [property@Gtk.Switch:active] property), while the trough color indicates the present underlying state (represented by the [property@Gtk.Switch:state] property).  See [signal@Gtk.Switch::state-set] for details. # Shortcuts and Gestures `GtkSwitch` supports pan and drag gestures to move the slider. # CSS nodes ``` switch ├── image ├── image ╰── slider ``` `GtkSwitch` has four css nodes, the main node with the name switch and subnodes for the slider and the on and off images. Neither of them is using any style classes. # Accessibility `GtkSwitch` uses the %GTK_ACCESSIBLE_ROLE_SWITCH role. Creates a new `GtkSwitch` widget. the newly created `GtkSwitch` instance Gets whether the `GtkSwitch` is in its “on” or “off” state. %TRUE if the `GtkSwitch` is active, and %FALSE otherwise a `GtkSwitch` Gets the underlying state of the `GtkSwitch`. the underlying state a `GtkSwitch` Changes the state of @self to the desired one. a `GtkSwitch` %TRUE if @self should be active, and %FALSE otherwise Sets the underlying state of the `GtkSwitch`. This function is typically called from a [signal@Gtk.Switch::state-set] signal handler in order to set up delayed state changes. See [signal@Gtk.Switch::state-set] for details. a `GtkSwitch` the new state Whether the `GtkSwitch` widget is in its on or off state. The backend state that is controlled by the switch. Applications should usually set the [property@Gtk.Switch:active] property, except when indicating a change to the backend state which occurs separately from the user's interaction. See [signal@Gtk.Switch::state-set] for details. Emitted to animate the switch. Applications should never connect to this signal, but use the [property@Gtk.Switch:active] property. Emitted to change the underlying state. The ::state-set signal is emitted when the user changes the switch position. The default handler calls [method@Gtk.Switch.set_state] with the value of @state. To implement delayed state change, applications can connect to this signal, initiate the change of the underlying state, and call [method@Gtk.Switch.set_state] when the underlying state change is complete. The signal handler should return %TRUE to prevent the default handler from running. %TRUE to stop the signal emission the new state of the switch The indexes of colors passed to symbolic color rendering, such as [vfunc@Gtk.SymbolicPaintable.snapshot_symbolic]. More values may be added over time. The default foreground color Indication color for errors Indication color for warnings Indication color for success `GtkSymbolicPaintable` is an interface that support symbolic colors in paintables. `GdkPaintable`s implementing the interface will have the [vfunc@Gtk.SymbolicPaintable.snapshot_symbolic] function called and have the colors for drawing symbolic icons passed. At least 4 colors are guaranteed to be passed every time. These 4 colors are the foreground color, and the colors to use for errors, warnings and success information in that order. More colors may be added in the future. Snapshots the paintable with the given colors. If less than 4 colors are provided, GTK will pad the array with default colors. a `GtkSymbolicPaintable` a `GdkSnapshot` to snapshot to width to snapshot in height to snapshot in a pointer to an array of colors The number of colors Snapshots the paintable with the given colors. If less than 4 colors are provided, GTK will pad the array with default colors. a `GtkSymbolicPaintable` a `GdkSnapshot` to snapshot to width to snapshot in height to snapshot in a pointer to an array of colors The number of colors The list of virtual functions for the `GtkSymbolicPaintable` interface. No function must be implemented, default implementations exist for each one. Snapshot the paintable using the given colors. See `GtkSymbolicPaintable::snapshot_symbolic()` for details. If this function is not implemented, [vfunc@Gdk.Paintable.snapshot] will be called. a `GtkSymbolicPaintable` a `GdkSnapshot` to snapshot to width to snapshot in height to snapshot in a pointer to an array of colors The number of colors Values that can be passed to the [vfunc@Gtk.Widget.system_setting_changed] vfunc. The values indicate which system setting has changed. Widgets may need to drop caches, or react otherwise. Most of the values correspond to [class@Settings] properties. More values may be added over time. the [property@Gtk.Settings:gtk-xft-dpi] setting has changed The [property@Gtk.Settings:gtk-font-name] setting has changed The font configuration has changed in a way that requires text to be redrawn. This can be any of the [property@Gtk.Settings:gtk-xft-antialias], [property@Gtk.Settings:gtk-xft-hinting], [property@Gtk.Settings:gtk-xft-hintstyle], [property@Gtk.Settings:gtk-xft-rgba] or [property@Gtk.Settings:gtk-fontconfig-timestamp] settings The display has changed The icon theme has changed in a way that requires icons to be looked up again The priority at which the text view validates onscreen lines in an idle job in the background. Uses the default sort function in a [iface@Gtk.TreeSortable]. See also: [method@Gtk.TreeSortable.set_sort_column_id] Disables sorting in a [iface@Gtk.TreeSortable]. See also: [method@Gtk.TreeSortable.set_sort_column_id] The `GtkText` widget is a single-line text entry widget. `GtkText` is the common implementation of single-line text editing that is shared between [class@Gtk.Entry], [class@Gtk.PasswordEntry], [class@Gtk.SpinButton], and other widgets. In all of these, `GtkText` is used as the delegate for the [iface@Gtk.Editable] implementation. A fairly large set of key bindings are supported by default. If the entered text is longer than the allocation of the widget, the widget will scroll so that the cursor position is visible. When using an entry for passwords and other sensitive information, it can be put into “password mode” using [method@Gtk.Text.set_visibility]. In this mode, entered text is displayed using a “invisible” character. By default, GTK picks the best invisible character that is available in the current font, but it can be changed with [method@Gtk.Text.set_invisible_char]. If you are looking to add icons or progress display in an entry, look at [class@Gtk.Entry]. There other alternatives for more specialized use cases, such as [class@Gtk.SearchEntry]. If you need multi-line editable text, look at [class@Gtk.TextView]. # Shortcuts and Gestures `GtkText` supports the following keyboard shortcuts: - <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. - <kbd>Ctrl</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&sol;</kbd> selects all the text. - <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>A</kbd> or <kbd>Ctrl</kbd>+<kbd>&bsol;</kbd> unselects all. - <kbd>Ctrl</kbd>+<kbd>Z</kbd> undoes the last modification. - <kbd>Ctrl</kbd>+<kbd>Y</kbd> or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Z</kbd> redoes the last undone modification. Additionally, the following signals have default keybindings: - [signal@Gtk.Text::activate] - [signal@Gtk.Text::backspace] - [signal@Gtk.Text::copy-clipboard] - [signal@Gtk.Text::cut-clipboard] - [signal@Gtk.Text::delete-from-cursor] - [signal@Gtk.Text::insert-emoji] - [signal@Gtk.Text::move-cursor] - [signal@Gtk.Text::paste-clipboard] - [signal@Gtk.Text::toggle-overwrite] # Actions `GtkText` defines a set of built-in actions: - `clipboard.copy` copies the contents to the clipboard. - `clipboard.cut` copies the contents to the clipboard and deletes it from the widget. - `clipboard.paste` inserts the contents of the clipboard into the widget. - `menu.popup` opens the context menu. - `misc.insert-emoji` opens the Emoji chooser. - `misc.toggle-visibility` toggles the `GtkText`:visibility property. - `selection.delete` deletes the current selection. - `selection.select-all` selects all of the widgets content. - `text.redo` redoes the last change to the contents. - `text.undo` undoes the last change to the contents. # CSS nodes ``` text[.read-only] ├── placeholder ├── undershoot.left ├── undershoot.right ├── [selection] ├── [block-cursor] ╰── [window.popup] ``` `GtkText` has a main node with the name `text`. Depending on the properties of the widget, the `.read-only` style class may appear. When the entry has a selection, it adds a subnode with the name `selection`. When the entry is in overwrite mode, it adds a subnode with the name `block-cursor` that determines how the block cursor is drawn. The CSS node for a context menu is added as a subnode with the name `popup`. The `undershoot` nodes are used to draw the underflow indication when content is scrolled out of view. These nodes get the `.left` or `.right` style class added depending on where the indication is drawn. When touch is used and touch selection handles are shown, they are using CSS nodes with name `cursor-handle`. They get the `.top` or `.bottom` style class depending on where they are shown in relation to the selection. If there is just a single handle for the text cursor, it gets the style class `.insertion-cursor`. # Accessibility `GtkText` uses the %GTK_ACCESSIBLE_ROLE_NONE role, which causes it to be skipped for accessibility. This is because `GtkText` is expected to be used as a delegate for a `GtkEditable` implementation that will be represented to accessibility. Creates a new `GtkText`. a new `GtkText`. Creates a new `GtkText` with the specified text buffer. a new `GtkText` The buffer to use for the new `GtkText`. Determine the positions of the strong and weak cursors if the insertion point in the layout is at @position. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction are inserted. The rectangle positions are in widget coordinates. a `GtkText` the character position location to store the strong cursor position location to store the weak cursor position Returns whether pressing Enter will activate the default widget for the window containing @self. See [method@Gtk.Text.set_activates_default]. %TRUE if the `GtkText` will activate the default widget a `GtkText` Gets the attribute list that was set on the `GtkText`. See [method@Gtk.Text.set_attributes]. the attribute list a `GtkText` Get the `GtkEntryBuffer` object which holds the text for this widget. A `GtkEntryBuffer` object. a `GtkText` Returns whether Emoji completion is enabled for this `GtkText` widget. %TRUE if Emoji completion is enabled a `GtkText` Gets the menu model for extra items in the context menu. See [method@Gtk.Text.set_extra_menu]. the menu model a `GtkText` Gets the input hints of the `GtkText`. the input hints a `GtkText` Gets the input purpose of the `GtkText`. the input purpose a `GtkText` Retrieves the character displayed when visibility is set to false. Note that GTK does not compute this value unless it needs it, so the value returned by this function is not very useful unless it has been explicitly set with [method@Gtk.Text.set_invisible_char]. the current invisible char, or 0, if @text does not show invisible text at all. a `GtkText` Retrieves the maximum allowed length of the text in @self. See [method@Gtk.Text.set_max_length]. This is equivalent to getting @self's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.get_max_length] on it. the maximum allowed number of characters in `GtkText`, or 0 if there is no maximum. a `GtkText` Gets whether text is overwritten when typing in the `GtkText`. See [method@Gtk.Text.set_overwrite_mode]. whether the text is overwritten when typing a `GtkText` Retrieves the text that will be displayed when @self is empty and unfocused If no placeholder text has been set, %NULL will be returned. the placeholder text a `GtkText` Returns whether the `GtkText` will grow and shrink with the content. %TRUE if @self will propagate the text width a `GtkText` Gets the tabstops that were set on the `GtkText`. See [method@Gtk.Text.set_tabs]. the tabstops a `GtkText` Retrieves the current length of the text in @self. This is equivalent to getting @self's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.get_length] on it. the current number of characters in `GtkText`, or 0 if there are none. a `GtkText` Returns whether the `GtkText` will truncate multi-line text that is pasted into the widget %TRUE if @self will truncate multi-line text a `GtkText` Retrieves whether the text in @self is visible. %TRUE if the text is currently visible a `GtkText` Causes @self to have keyboard focus. It behaves like [method@Gtk.Widget.grab_focus], except that it doesn't select the contents of @self. You only want to call this on some special entries which the user usually doesn't want to replace all text in, such as search-as-you-type entries. %TRUE if focus is now inside @self a `GtkText` If @activates is %TRUE, pressing Enter will activate the default widget for the window containing @self. This usually means that the dialog containing the `GtkText` will be closed, since the default widget is usually one of the dialog buttons. a `GtkText` %TRUE to activate window’s default widget on Enter keypress Sets attributes that are applied to the text. a `GtkText` a `PangoAttrList` Set the `GtkEntryBuffer` object which holds the text for this widget. a `GtkText` a `GtkEntryBuffer` Sets whether Emoji completion is enabled. If it is, typing ':', followed by a recognized keyword, will pop up a window with suggested Emojis matching the keyword. a `GtkText` %TRUE to enable Emoji completion Sets a menu model to add when constructing the context menu for @self. a `GtkText` a `GMenuModel` Sets input hints that allow input methods to fine-tune their behaviour. a `GtkText` the hints Sets the input purpose of the `GtkText`. This can be used by on-screen keyboards and other input methods to adjust their behaviour. a `GtkText` the purpose Sets the character to use when in “password mode”. By default, GTK picks the best invisible char available in the current font. If you set the invisible char to 0, then the user will get no feedback at all; there will be no text on the screen as they type. a `GtkText` a Unicode character Sets the maximum allowed length of the contents of the widget. If the current contents are longer than the given length, then they will be truncated to fit. This is equivalent to getting @self's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.set_max_length] on it. a `GtkText` the maximum length of the `GtkText`, or 0 for no maximum. (other than the maximum length of entries.) The value passed in will be clamped to the range 0-65536. Sets whether the text is overwritten when typing in the `GtkText`. a `GtkText` new value Sets text to be displayed in @self when it is empty. This can be used to give a visual hint of the expected contents of the `GtkText`. a `GtkText` a string to be displayed when @self is empty and unfocused Sets whether the `GtkText` should grow and shrink with the content. a `GtkText` %TRUE to propagate the text width Sets tabstops that are applied to the text. a `GtkText` a `PangoTabArray` Sets whether the `GtkText` should truncate multi-line text that is pasted into the widget. a `GtkText` %TRUE to truncate multi-line text Sets whether the contents of the `GtkText` are visible or not. When visibility is set to %FALSE, characters are displayed as the invisible char, and will also appear that way when the text in the widget is copied to the clipboard. By default, GTK picks the best invisible character available in the current font, but it can be changed with [method@Gtk.Text.set_invisible_char]. Note that you probably want to set [property@Gtk.Text:input-purpose] to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN to inform input methods about the purpose of this self, in addition to setting visibility to %FALSE. a `GtkText` %TRUE if the contents of the `GtkText` are displayed as plaintext Unsets the invisible char. After calling this, the default invisible char is used again. a `GtkText` Whether to activate the default widget when Enter is pressed. A list of Pango attributes to apply to the text of the `GtkText`. This is mainly useful to change the size or weight of the text. The `PangoAttribute`'s @start_index and @end_index must refer to the `GtkEntryBuffer` text, i.e. without the preedit string. The `GtkEntryBuffer` object which stores the text. Whether to suggest Emoji replacements. A menu model whose contents will be appended to the context menu. Which IM (input method) module should be used for this self. See [class@Gtk.IMMulticontext]. Setting this to a non-%NULL value overrides the system-wide IM module setting. See the [property@Gtk.Settings:gtk-im-module] property. Additional hints that allow input methods to fine-tune their behaviour. The purpose of this text field. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN is independent from setting [property@Gtk.Text:visibility]. The character to used when masking contents (in “password mode”). Whether the invisible char has been set for the `GtkText`. Maximum number of characters that are allowed. Zero indicates no limit. If text is overwritten when typing in the `GtkText`. The text that will be displayed in the `GtkText` when it is empty and unfocused. Whether the widget should grow and shrink with the content. Number of pixels scrolled of the screen to the left. A list of tabstops to apply to the text of the `GtkText`. When %TRUE, pasted multi-line text is truncated to the first line. If %FALSE, the text is masked with the “invisible char”. Emitted when the user hits the <kbd>Enter</kbd> key. The default bindings for this signal are all forms of the <kbd>Enter</kbd> key. Emitted when the user asks for it. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Backspace</kbd> and <kbd>Shift</kbd>+<kbd>Backspace</kbd>. Emitted to copy the selection to the clipboard. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>c</kbd> and <kbd>Ctrl</kbd>+<kbd>Insert</kbd>. Emitted to cut the selection to the clipboard. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>x</kbd> and <kbd>Shift</kbd>+<kbd>Delete</kbd>. Emitted when the user initiates a text deletion. This is a [keybinding signal](class.SignalAction.html). If the @type is %GTK_DELETE_CHARS, GTK deletes the selection if there is one, otherwise it deletes the requested number of characters. The default bindings for this signal are <kbd>Delete</kbd> for deleting a character and <kbd>Ctrl</kbd>+<kbd>Delete</kbd> for deleting a word. the granularity of the deletion, as a `GtkDeleteType` the number of @type units to delete Emitted when the user initiates the insertion of a fixed string at the cursor. This is a [keybinding signal](class.SignalAction.html). This signal has no default bindings. the string to insert Emitted to present the Emoji chooser for the widget. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>.</kbd> and <kbd>Ctrl</kbd>+<kbd>;</kbd> Emitted when the user initiates a cursor movement. If the cursor is not visible in @self, this signal causes the viewport to be moved instead. This is a [keybinding signal](class.SignalAction.html). Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the <kbd>Shift</kbd> modifier extends the selection, the variant without it does not. There are too many key combinations to list them all here. - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move by individual characters/lines - <kbd>Ctrl</kbd>+<kbd>←</kbd>, etc. move by words/paragraphs - <kbd>Home</kbd> and <kbd>End</kbd> move to the ends of the buffer the granularity of the move, as a `GtkMovementStep` the number of @step units to move %TRUE if the move should extend the selection Emitted to paste the contents of the clipboard. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>v</kbd> and <kbd>Shift</kbd>+<kbd>Insert</kbd>. Emitted when the preedit text changes. If an input method is used, the typed text will not immediately be committed to the buffer. So if you are interested in the text, connect to this signal. the current preedit string Emitted to toggle the overwrite mode of the `GtkText`. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal is <kbd>Insert</kbd>. Stores text and attributes for display in a `GtkTextView`. You may wish to begin by reading the [text widget conceptual overview](section-text-widget.html), which gives an overview of all the objects and data types related to the text widget and how they work together. GtkTextBuffer can support undoing changes to the buffer content, see [method@Gtk.TextBuffer.set_enable_undo]. Creates a new text buffer. a new text buffer a tag table, or %NULL to create a new one Emits the “apply-tag” signal on @buffer. The default handler for the signal applies @tag to the given range. @start and @end do not have to be in order. a `GtkTextBuffer` a `GtkTextTag` one bound of range to be tagged other bound of range to be tagged Called to indicate that the buffer operations between here and a call to gtk_text_buffer_end_user_action() are part of a single user-visible operation. The operations between gtk_text_buffer_begin_user_action() and gtk_text_buffer_end_user_action() can then be grouped when creating an undo stack. `GtkTextBuffer` maintains a count of calls to gtk_text_buffer_begin_user_action() that have not been closed with a call to gtk_text_buffer_end_user_action(), and emits the “begin-user-action” and “end-user-action” signals only for the outermost pair of calls. This allows you to build user actions from other user actions. The “interactive” buffer mutation functions, such as [method@Gtk.TextBuffer.insert_interactive], automatically call begin/end user action around the buffer operations they perform, so there's no need to add extra calls if you user action consists solely of a single call to one of those functions. a `GtkTextBuffer` The class handler for the `GtkTextBuffer::changed` signal. The class handler for the `GtkTextBuffer::delete-range` signal. Ends a user-visible operation. Should be paired with a call to [method@Gtk.TextBuffer.begin_user_action]. See that function for a full explanation. a `GtkTextBuffer` Inserts a child widget anchor into the text buffer at @iter. The anchor will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode “object replacement character” 0xFFFC. Note that the “slice” variants for obtaining portions of the buffer as a string include this character for child anchors, but the “text” variants do not. E.g. see [method@Gtk.TextBuffer.get_slice] and [method@Gtk.TextBuffer.get_text]. Consider [method@Gtk.TextBuffer.create_child_anchor] as a more convenient alternative to this function. The buffer will add a reference to the anchor, so you can unref it after insertion. a `GtkTextBuffer` location to insert the anchor a `GtkTextChildAnchor` Inserts an image into the text buffer at @iter. The image will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode “object replacement character” 0xFFFC. Note that the “slice” variants for obtaining portions of the buffer as a string include this character for paintable, but the “text” variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and [method@Gtk.TextBuffer.get_text]. a `GtkTextBuffer` location to insert the paintable a `GdkPaintable` The class handler for the `GtkTextBuffer::insert-text` signal. The class handler for the `GtkTextBuffer::mark-deleted` signal. The class handler for the `GtkTextBuffer::mark-set` signal. The class handler for the `GtkTextBuffer::modified-changed` signal. The class handler for the `GtkTextBuffer::paste-done` signal. Redoes the next redoable action on the buffer, if there is one. a `GtkTextBuffer` Emits the “remove-tag” signal. The default handler for the signal removes all occurrences of @tag from the given range. @start and @end don’t have to be in order. a `GtkTextBuffer` a `GtkTextTag` one bound of range to be untagged other bound of range to be untagged Undoes the last undoable action on the buffer, if there is one. a `GtkTextBuffer` Adds the mark at position @where. The mark must not be added to another buffer, and if its name is not %NULL then there must not be another mark in the buffer with the same name. Emits the [signal@Gtk.TextBuffer::mark-set] signal as notification of the mark's initial placement. a `GtkTextBuffer` the mark to add location to place mark Adds @clipboard to the list of clipboards in which the selection contents of @buffer are available. In most cases, @clipboard will be the `GdkClipboard` returned by [method@Gtk.Widget.get_primary_clipboard] for a view of @buffer. a `GtkTextBuffer` a `GdkClipboard` Emits the “apply-tag” signal on @buffer. The default handler for the signal applies @tag to the given range. @start and @end do not have to be in order. a `GtkTextBuffer` a `GtkTextTag` one bound of range to be tagged other bound of range to be tagged Emits the “apply-tag” signal on @buffer. Calls [method@Gtk.TextTagTable.lookup] on the buffer’s tag table to get a `GtkTextTag`, then calls [method@Gtk.TextBuffer.apply_tag]. a `GtkTextBuffer` name of a named `GtkTextTag` one bound of range to be tagged other bound of range to be tagged Performs the appropriate action as if the user hit the delete key with the cursor at the position specified by @iter. In the normal case a single character will be deleted, but when combining accents are involved, more than one character can be deleted, and when precomposed character and accent combinations are involved, less than one character will be deleted. Because the buffer is modified, all outstanding iterators become invalid after calling this function; however, the @iter will be re-initialized to point to the location where text was deleted. %TRUE if the buffer was modified a `GtkTextBuffer` a position in @buffer whether the deletion is caused by user interaction whether the buffer is editable by default Denotes the beginning of an action that may not be undone. This will cause any previous operations in the undo/redo queue to be cleared. This should be paired with a call to [method@Gtk.TextBuffer.end_irreversible_action] after the irreversible action has completed. You may nest calls to gtk_text_buffer_begin_irreversible_action() and gtk_text_buffer_end_irreversible_action() pairs. a `GtkTextBuffer` Called to indicate that the buffer operations between here and a call to gtk_text_buffer_end_user_action() are part of a single user-visible operation. The operations between gtk_text_buffer_begin_user_action() and gtk_text_buffer_end_user_action() can then be grouped when creating an undo stack. `GtkTextBuffer` maintains a count of calls to gtk_text_buffer_begin_user_action() that have not been closed with a call to gtk_text_buffer_end_user_action(), and emits the “begin-user-action” and “end-user-action” signals only for the outermost pair of calls. This allows you to build user actions from other user actions. The “interactive” buffer mutation functions, such as [method@Gtk.TextBuffer.insert_interactive], automatically call begin/end user action around the buffer operations they perform, so there's no need to add extra calls if you user action consists solely of a single call to one of those functions. a `GtkTextBuffer` Copies the currently-selected text to a clipboard. a `GtkTextBuffer` the `GdkClipboard` object to copy to Creates and inserts a child anchor. This is a convenience function which simply creates a child anchor with [ctor@Gtk.TextChildAnchor.new] and inserts it into the buffer with [method@Gtk.TextBuffer.insert_child_anchor]. The new anchor is owned by the buffer; no reference count is returned to the caller of this function. the created child anchor a `GtkTextBuffer` location in the buffer Creates a mark at position @where. If @mark_name is %NULL, the mark is anonymous; otherwise, the mark can be retrieved by name using [method@Gtk.TextBuffer.get_mark]. If a mark has left gravity, and text is inserted at the mark’s current location, the mark will be moved to the left of the newly-inserted text. If the mark has right gravity (@left_gravity = %FALSE), the mark will end up on the right of newly-inserted text. The standard left-to-right cursor is a mark with right gravity (when you type, the cursor stays on the right side of the text you’re typing). The caller of this function does not own a reference to the returned `GtkTextMark`, so you can ignore the return value if you like. Marks are owned by the buffer and go away when the buffer does. Emits the [signal@Gtk.TextBuffer::mark-set] signal as notification of the mark's initial placement. the new `GtkTextMark` object a `GtkTextBuffer` name for mark location to place mark whether the mark has left gravity Creates a tag and adds it to the tag table for @buffer. Equivalent to calling [ctor@Gtk.TextTag.new] and then adding the tag to the buffer’s tag table. The returned tag is owned by the buffer’s tag table, so the ref count will be equal to one. If @tag_name is %NULL, the tag is anonymous. If @tag_name is non-%NULL, a tag called @tag_name must not already exist in the tag table for this buffer. The @first_property_name argument and subsequent arguments are a list of properties to set on the tag, as with g_object_set(). a new tag a `GtkTextBuffer` name of the new tag name of first property to set %NULL-terminated list of property names and values Copies the currently-selected text to a clipboard, then deletes said text if it’s editable. a `GtkTextBuffer` the `GdkClipboard` object to cut to default editability of the buffer Deletes text between @start and @end. The order of @start and @end is not actually relevant; gtk_text_buffer_delete() will reorder them. This function actually emits the “delete-range” signal, and the default handler of that signal deletes the text. Because the buffer is modified, all outstanding iterators become invalid after calling this function; however, the @start and @end will be re-initialized to point to the location where text was deleted. a `GtkTextBuffer` a position in @buffer another position in @buffer Deletes all editable text in the given range. Calls [method@Gtk.TextBuffer.delete] for each editable sub-range of [@start,@end). @start and @end are revalidated to point to the location of the last deleted range, or left untouched if no text was deleted. whether some text was actually deleted a `GtkTextBuffer` start of range to delete end of range whether the buffer is editable by default Deletes @mark, so that it’s no longer located anywhere in the buffer. Removes the reference the buffer holds to the mark, so if you haven’t called g_object_ref() on the mark, it will be freed. Even if the mark isn’t freed, most operations on @mark become invalid, until it gets added to a buffer again with [method@Gtk.TextBuffer.add_mark]. Use [method@Gtk.TextMark.get_deleted] to find out if a mark has been removed from its buffer. The [signal@Gtk.TextBuffer::mark-deleted] signal will be emitted as notification after the mark is deleted. a `GtkTextBuffer` a `GtkTextMark` in @buffer Deletes the mark named @name; the mark must exist. See [method@Gtk.TextBuffer.delete_mark] for details. a `GtkTextBuffer` name of a mark in @buffer Deletes the range between the “insert” and “selection_bound” marks, that is, the currently-selected text. If @interactive is %TRUE, the editability of the selection will be considered (users can’t delete uneditable text). whether there was a non-empty selection to delete a `GtkTextBuffer` whether the deletion is caused by user interaction whether the buffer is editable by default Denotes the end of an action that may not be undone. This will cause any previous operations in the undo/redo queue to be cleared. This should be called after completing modifications to the text buffer after [method@Gtk.TextBuffer.begin_irreversible_action] was called. You may nest calls to gtk_text_buffer_begin_irreversible_action() and gtk_text_buffer_end_irreversible_action() pairs. a `GtkTextBuffer` Ends a user-visible operation. Should be paired with a call to [method@Gtk.TextBuffer.begin_user_action]. See that function for a full explanation. a `GtkTextBuffer` Retrieves the first and last iterators in the buffer, i.e. the entire buffer lies within the range [@start,@end). a `GtkTextBuffer` iterator to initialize with first position in the buffer iterator to initialize with the end iterator Gets whether there is a redoable action in the history. %TRUE if there is a redoable action a `GtkTextBuffer` Gets whether there is an undoable action in the history. %TRUE if there is an undoable action a `GtkTextBuffer` Gets the number of characters in the buffer. Note that characters and bytes are not the same, you can’t e.g. expect the contents of the buffer in string form to be this many bytes long. The character count is cached, so this function is very fast. number of characters in the buffer a `GtkTextBuffer` Gets whether the buffer is saving modifications to the buffer to allow for undo and redo actions. See [method@Gtk.TextBuffer.begin_irreversible_action] and [method@Gtk.TextBuffer.end_irreversible_action] to create changes to the buffer that cannot be undone. %TRUE if undoing and redoing changes to the buffer is allowed. a `GtkTextBuffer` Initializes @iter with the “end iterator,” one past the last valid character in the text buffer. If dereferenced with [method@Gtk.TextIter.get_char], the end iterator has a character value of 0. The entire buffer lies in the range from the first position in the buffer (call [method@Gtk.TextBuffer.get_start_iter] to get character position 0) to the end iterator. a `GtkTextBuffer` iterator to initialize Indicates whether the buffer has some text currently selected. %TRUE if the there is text selected a `GtkTextBuffer` Returns the mark that represents the cursor (insertion point). Equivalent to calling [method@Gtk.TextBuffer.get_mark] to get the mark named “insert”, but very slightly more efficient, and involves less typing. insertion point mark a `GtkTextBuffer` Obtains the location of @anchor within @buffer. a `GtkTextBuffer` an iterator to be initialized a child anchor that appears in @buffer Initializes @iter to the start of the given line. If @line_number is greater than or equal to the number of lines in the @buffer, the end iterator is returned. whether the exact position has been found a `GtkTextBuffer` iterator to initialize line number counting from 0 Obtains an iterator pointing to @byte_index within the given line. @byte_index must be the start of a UTF-8 character. Note bytes, not characters; UTF-8 may encode one character as multiple bytes. If @line_number is greater than or equal to the number of lines in the @buffer, the end iterator is returned. And if @byte_index is off the end of the line, the iterator at the end of the line is returned. whether the exact position has been found a `GtkTextBuffer` iterator to initialize line number counting from 0 byte index from start of line Obtains an iterator pointing to @char_offset within the given line. Note characters, not bytes; UTF-8 may encode one character as multiple bytes. If @line_number is greater than or equal to the number of lines in the @buffer, the end iterator is returned. And if @char_offset is off the end of the line, the iterator at the end of the line is returned. whether the exact position has been found a `GtkTextBuffer` iterator to initialize line number counting from 0 char offset from start of line Initializes @iter with the current position of @mark. a `GtkTextBuffer` iterator to initialize a `GtkTextMark` in @buffer Initializes @iter to a position @char_offset chars from the start of the entire buffer. If @char_offset is -1 or greater than the number of characters in the buffer, @iter is initialized to the end iterator, the iterator one past the last valid character in the buffer. a `GtkTextBuffer` iterator to initialize char offset from start of buffer, counting from 0, or -1 Obtains the number of lines in the buffer. This value is cached, so the function is very fast. number of lines in the buffer a `GtkTextBuffer` Returns the mark named @name in buffer @buffer, or %NULL if no such mark exists in the buffer. a `GtkTextMark` a `GtkTextBuffer` a mark name Gets the maximum number of undo levels to perform. If 0, unlimited undo actions may be performed. Note that this may have a memory usage impact as it requires storing an additional copy of the inserted or removed text within the text buffer. The max number of undo levels allowed (0 indicates unlimited). a `GtkTextBuffer` Indicates whether the buffer has been modified since the last call to [method@Gtk.TextBuffer.set_modified] set the modification flag to %FALSE. Used for example to enable a “save” function in a text editor. %TRUE if the buffer has been modified a `GtkTextBuffer` Returns the mark that represents the selection bound. Equivalent to calling [method@Gtk.TextBuffer.get_mark] to get the mark named “selection_bound”, but very slightly more efficient, and involves less typing. The currently-selected text in @buffer is the region between the “selection_bound” and “insert” marks. If “selection_bound” and “insert” are in the same place, then there is no current selection. [method@Gtk.TextBuffer.get_selection_bounds] is another convenient function for handling the selection, if you just want to know whether there’s a selection and what its bounds are. selection bound mark a `GtkTextBuffer` Returns %TRUE if some text is selected; places the bounds of the selection in @start and @end. If the selection has length 0, then @start and @end are filled in with the same value. @start and @end will be in ascending order. If @start and @end are %NULL, then they are not filled in, but the return value still indicates whether text is selected. whether the selection has nonzero length a `GtkTextBuffer` a `GtkTextBuffer` iterator to initialize with selection start iterator to initialize with selection end Get a content provider for this buffer. It can be used to make the content of @buffer available in a `GdkClipboard`, see [method@Gdk.Clipboard.set_content]. a new `GdkContentProvider`. a `GtkTextBuffer` Returns the text in the range [@start,@end). Excludes undisplayed text (text marked with tags that set the invisibility attribute) if @include_hidden_chars is %FALSE. The returned string includes a 0xFFFC character whenever the buffer contains embedded images, so byte and character indexes into the returned string do correspond to byte and character indexes into the buffer. Contrast with [method@Gtk.TextBuffer.get_text]. Note that 0xFFFC can occur in normal text as well, so it is not a reliable indicator that a paintable or widget is in the buffer. an allocated UTF-8 string a `GtkTextBuffer` start of a range end of a range whether to include invisible text Initialized @iter with the first position in the text buffer. This is the same as using [method@Gtk.TextBuffer.get_iter_at_offset] to get the iter at character offset 0. a `GtkTextBuffer` iterator to initialize Get the `GtkTextTagTable` associated with this buffer. the buffer’s tag table a `GtkTextBuffer` Returns the text in the range [@start,@end). Excludes undisplayed text (text marked with tags that set the invisibility attribute) if @include_hidden_chars is %FALSE. Does not include characters representing embedded images, so byte and character indexes into the returned string do not correspond to byte and character indexes into the buffer. Contrast with [method@Gtk.TextBuffer.get_slice]. an allocated UTF-8 string a `GtkTextBuffer` start of a range end of a range whether to include invisible text Inserts @len bytes of @text at position @iter. If @len is -1, @text must be nul-terminated and will be inserted in its entirety. Emits the “insert-text” signal; insertion actually occurs in the default handler for the signal. @iter is invalidated when insertion occurs (because the buffer contents change), but the default signal handler revalidates it to point to the end of the inserted text. a `GtkTextBuffer` a position in the buffer text in UTF-8 format length of text in bytes, or -1 Inserts @text in @buffer. Simply calls [method@Gtk.TextBuffer.insert], using the current cursor position as the insertion point. a `GtkTextBuffer` text in UTF-8 format length of text, in bytes Inserts a child widget anchor into the text buffer at @iter. The anchor will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode “object replacement character” 0xFFFC. Note that the “slice” variants for obtaining portions of the buffer as a string include this character for child anchors, but the “text” variants do not. E.g. see [method@Gtk.TextBuffer.get_slice] and [method@Gtk.TextBuffer.get_text]. Consider [method@Gtk.TextBuffer.create_child_anchor] as a more convenient alternative to this function. The buffer will add a reference to the anchor, so you can unref it after insertion. a `GtkTextBuffer` location to insert the anchor a `GtkTextChildAnchor` Inserts @text in @buffer. Like [method@Gtk.TextBuffer.insert], but the insertion will not occur if @iter is at a non-editable location in the buffer. Usually you want to prevent insertions at ineditable locations if the insertion results from a user action (is interactive). @default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. Typically the result of [method@Gtk.TextView.get_editable] is appropriate here. whether text was actually inserted a `GtkTextBuffer` a position in @buffer some UTF-8 text length of text in bytes, or -1 default editability of buffer Inserts @text in @buffer. Calls [method@Gtk.TextBuffer.insert_interactive] at the cursor position. @default_editable indicates the editability of text that doesn't have a tag affecting editability applied to it. Typically the result of [method@Gtk.TextView.get_editable] is appropriate here. whether text was actually inserted a `GtkTextBuffer` text in UTF-8 format length of text in bytes, or -1 default editability of buffer Inserts the text in @markup at position @iter. @markup will be inserted in its entirety and must be nul-terminated and valid UTF-8. Emits the [signal@Gtk.TextBuffer::insert-text] signal, possibly multiple times; insertion actually occurs in the default handler for the signal. @iter will point to the end of the inserted text on return. a `GtkTextBuffer` location to insert the markup a nul-terminated UTF-8 string containing Pango markup length of @markup in bytes, or -1 Inserts an image into the text buffer at @iter. The image will be counted as one character in character counts, and when obtaining the buffer contents as a string, will be represented by the Unicode “object replacement character” 0xFFFC. Note that the “slice” variants for obtaining portions of the buffer as a string include this character for paintable, but the “text” variants do not. e.g. see [method@Gtk.TextBuffer.get_slice] and [method@Gtk.TextBuffer.get_text]. a `GtkTextBuffer` location to insert the paintable a `GdkPaintable` Copies text, tags, and paintables between @start and @end and inserts the copy at @iter. The order of @start and @end doesn’t matter. Used instead of simply getting/inserting text because it preserves images and tags. If @start and @end are in a different buffer from @buffer, the two buffers must share the same tag table. Implemented via emissions of the ::insert-text and ::apply-tag signals, so expect those. a `GtkTextBuffer` a position in @buffer a position in a `GtkTextBuffer` another position in the same buffer as @start Copies text, tags, and paintables between @start and @end and inserts the copy at @iter. Same as [method@Gtk.TextBuffer.insert_range], but does nothing if the insertion point isn’t editable. The @default_editable parameter indicates whether the text is editable at @iter if no tags enclosing @iter affect editability. Typically the result of [method@Gtk.TextView.get_editable] is appropriate here. whether an insertion was possible at @iter a `GtkTextBuffer` a position in @buffer a position in a `GtkTextBuffer` another position in the same buffer as @start default editability of the buffer Inserts @text into @buffer at @iter, applying the list of tags to the newly-inserted text. The last tag specified must be %NULL to terminate the list. Equivalent to calling [method@Gtk.TextBuffer.insert], then [method@Gtk.TextBuffer.apply_tag] on the inserted text; this is just a convenience function. a `GtkTextBuffer` an iterator in @buffer UTF-8 text length of @text, or -1 first tag to apply to @text %NULL-terminated list of tags to apply Inserts @text into @buffer at @iter, applying the list of tags to the newly-inserted text. Same as [method@Gtk.TextBuffer.insert_with_tags], but allows you to pass in tag names instead of tag objects. a `GtkTextBuffer` position in @buffer UTF-8 text length of @text, or -1 name of a tag to apply to @text more tag names Moves @mark to the new location @where. Emits the [signal@Gtk.TextBuffer::mark-set] signal as notification of the move. a `GtkTextBuffer` a `GtkTextMark` new location for @mark in @buffer Moves the mark named @name (which must exist) to location @where. See [method@Gtk.TextBuffer.move_mark] for details. a `GtkTextBuffer` name of a mark new location for mark Pastes the contents of a clipboard. If @override_location is %NULL, the pasted text will be inserted at the cursor position, or the buffer selection will be replaced if the selection is non-empty. Note: pasting is asynchronous, that is, we’ll ask for the paste data and return, and at some point later after the main loop runs, the paste data will be inserted. a `GtkTextBuffer` the `GdkClipboard` to paste from location to insert pasted text whether the buffer is editable by default This function moves the “insert” and “selection_bound” marks simultaneously. If you move them to the same place in two steps with [method@Gtk.TextBuffer.move_mark], you will temporarily select a region in between their old and new locations, which can be pretty inefficient since the temporarily-selected region will force stuff to be recalculated. This function moves them as a unit, which can be optimized. a `GtkTextBuffer` where to put the cursor Redoes the next redoable action on the buffer, if there is one. a `GtkTextBuffer` Removes all tags in the range between @start and @end. Be careful with this function; it could remove tags added in code unrelated to the code you’re currently writing. That is, using this function is probably a bad idea if you have two or more unrelated code sections that add tags. a `GtkTextBuffer` one bound of range to be untagged other bound of range to be untagged Removes a `GdkClipboard` added with [method@Gtk.TextBuffer.add_selection_clipboard] a `GtkTextBuffer` a `GdkClipboard` added to @buffer by [method@Gtk.TextBuffer.add_selection_clipboard] Emits the “remove-tag” signal. The default handler for the signal removes all occurrences of @tag from the given range. @start and @end don’t have to be in order. a `GtkTextBuffer` a `GtkTextTag` one bound of range to be untagged other bound of range to be untagged Emits the “remove-tag” signal. Calls [method@Gtk.TextTagTable.lookup] on the buffer’s tag table to get a `GtkTextTag`, then calls [method@Gtk.TextBuffer.remove_tag]. a `GtkTextBuffer` name of a `GtkTextTag` one bound of range to be untagged other bound of range to be untagged This function moves the “insert” and “selection_bound” marks simultaneously. If you move them in two steps with [method@Gtk.TextBuffer.move_mark], you will temporarily select a region in between their old and new locations, which can be pretty inefficient since the temporarily-selected region will force stuff to be recalculated. This function moves them as a unit, which can be optimized. a `GtkTextBuffer` where to put the “insert” mark where to put the “selection_bound” mark Sets whether or not to enable undoable actions in the text buffer. Undoable actions in this context are changes to the text content of the buffer. Changes to tags and marks are not tracked. If enabled, the user will be able to undo the last number of actions up to [method@Gtk.TextBuffer.get_max_undo_levels]. See [method@Gtk.TextBuffer.begin_irreversible_action] and [method@Gtk.TextBuffer.end_irreversible_action] to create changes to the buffer that cannot be undone. a `GtkTextBuffer` %TRUE to enable undo Sets the maximum number of undo levels to perform. If 0, unlimited undo actions may be performed. Note that this may have a memory usage impact as it requires storing an additional copy of the inserted or removed text within the text buffer. a `GtkTextBuffer` the maximum number of undo actions to perform Used to keep track of whether the buffer has been modified since the last time it was saved. Whenever the buffer is saved to disk, call `gtk_text_buffer_set_modified (@buffer, FALSE)`. When the buffer is modified, it will automatically toggle on the modified bit again. When the modified bit flips, the buffer emits the [signal@Gtk.TextBuffer::modified-changed] signal. a `GtkTextBuffer` modification flag setting Deletes current contents of @buffer, and inserts @text instead. This is automatically marked as an irreversible action in the undo stack. If you wish to mark this action as part of a larger undo operation, call [method@TextBuffer.delete] and [method@TextBuffer.insert] directly instead. If @len is -1, @text must be nul-terminated. @text must be valid UTF-8. a `GtkTextBuffer` UTF-8 text to insert length of @text in bytes Undoes the last undoable action on the buffer, if there is one. a `GtkTextBuffer` Denotes that the buffer can reapply the last undone action. Denotes that the buffer can undo the last applied action. The position of the insert mark. This is an offset from the beginning of the buffer. It is useful for getting notified when the cursor moves. Denotes if support for undoing and redoing changes to the buffer is allowed. Whether the buffer has some text currently selected. The GtkTextTagTable for the buffer. The text content of the buffer. Without child widgets and images, see [method@Gtk.TextBuffer.get_text] for more information. Emitted to apply a tag to a range of text in a `GtkTextBuffer`. Applying actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @start and @end iters (or has to revalidate them). See also: [method@Gtk.TextBuffer.apply_tag], [method@Gtk.TextBuffer.insert_with_tags], [method@Gtk.TextBuffer.insert_range]. the applied tag the start of the range the tag is applied to the end of the range the tag is applied to Emitted at the beginning of a single user-visible operation on a `GtkTextBuffer`. See also: [method@Gtk.TextBuffer.begin_user_action], [method@Gtk.TextBuffer.insert_interactive], [method@Gtk.TextBuffer.insert_range_interactive], [method@Gtk.TextBuffer.delete_interactive], [method@Gtk.TextBuffer.backspace], [method@Gtk.TextBuffer.delete_selection]. Emitted when the content of a `GtkTextBuffer` has changed. Emitted to delete a range from a `GtkTextBuffer`. Note that if your handler runs before the default handler it must not invalidate the @start and @end iters (or has to revalidate them). The default signal handler revalidates the @start and @end iters to both point to the location where text was deleted. Handlers which run after the default handler (see g_signal_connect_after()) do not have access to the deleted text. See also: [method@Gtk.TextBuffer.delete]. the start of the range to be deleted the end of the range to be deleted Emitted at the end of a single user-visible operation on the `GtkTextBuffer`. See also: [method@Gtk.TextBuffer.end_user_action], [method@Gtk.TextBuffer.insert_interactive], [method@Gtk.TextBuffer.insert_range_interactive], [method@Gtk.TextBuffer.delete_interactive], [method@Gtk.TextBuffer.backspace], [method@Gtk.TextBuffer.delete_selection], [method@Gtk.TextBuffer.backspace]. Emitted to insert a `GtkTextChildAnchor` in a `GtkTextBuffer`. Insertion actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @location iter (or has to revalidate it). The default signal handler revalidates it to be placed after the inserted @anchor. See also: [method@Gtk.TextBuffer.insert_child_anchor]. position to insert @anchor in @textbuffer the `GtkTextChildAnchor` to be inserted Emitted to insert a `GdkPaintable` in a `GtkTextBuffer`. Insertion actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @location iter (or has to revalidate it). The default signal handler revalidates it to be placed after the inserted @paintable. See also: [method@Gtk.TextBuffer.insert_paintable]. position to insert @paintable in @textbuffer the `GdkPaintable` to be inserted Emitted to insert text in a `GtkTextBuffer`. Insertion actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @location iter (or has to revalidate it). The default signal handler revalidates it to point to the end of the inserted text. See also: [method@Gtk.TextBuffer.insert], [method@Gtk.TextBuffer.insert_range]. position to insert @text in @textbuffer the UTF-8 text to be inserted length of the inserted text in bytes Emitted as notification after a `GtkTextMark` is deleted. See also: [method@Gtk.TextBuffer.delete_mark]. The mark that was deleted Emitted as notification after a `GtkTextMark` is set. See also: [method@Gtk.TextBuffer.create_mark], [method@Gtk.TextBuffer.move_mark]. The location of @mark in @textbuffer The mark that is set Emitted when the modified bit of a `GtkTextBuffer` flips. See also: [method@Gtk.TextBuffer.set_modified]. Emitted after paste operation has been completed. This is useful to properly scroll the view to the end of the pasted text. See [method@Gtk.TextBuffer.paste_clipboard] for more details. the `GdkClipboard` pasted from Emitted when a request has been made to redo the previously undone operation. Emitted to remove all occurrences of @tag from a range of text in a `GtkTextBuffer`. Removal actually occurs in the default handler. Note that if your handler runs before the default handler it must not invalidate the @start and @end iters (or has to revalidate them). See also: [method@Gtk.TextBuffer.remove_tag]. the tag to be removed the start of the range the tag is removed from the end of the range the tag is removed from Emitted when a request has been made to undo the previous operation or set of operations that have been grouped together. The class structure for `GtkTextBuffer`. The object class structure needs to be the first. The class handler for the `GtkTextBuffer::insert-text` signal. The class handler for the `GtkTextBuffer::insert-paintable` signal. a `GtkTextBuffer` location to insert the paintable a `GdkPaintable` The class handler for the `GtkTextBuffer::insert-child-anchor` signal. a `GtkTextBuffer` location to insert the anchor a `GtkTextChildAnchor` The class handler for the `GtkTextBuffer::delete-range` signal. The class handler for the `GtkTextBuffer::changed` signal. The class handler for the `GtkTextBuffer::modified-changed` signal. The class handler for the `GtkTextBuffer::mark-set` signal. The class handler for the `GtkTextBuffer::mark-deleted` signal. The class handler for the `GtkTextBuffer::apply-tag` signal. a `GtkTextBuffer` a `GtkTextTag` one bound of range to be tagged other bound of range to be tagged The class handler for the `GtkTextBuffer::remove-tag` signal. a `GtkTextBuffer` a `GtkTextTag` one bound of range to be untagged other bound of range to be untagged The class handler for the `GtkTextBuffer::begin-user-action` signal. a `GtkTextBuffer` The class handler for the `GtkTextBuffer::end-user-action` signal. a `GtkTextBuffer` The class handler for the `GtkTextBuffer::paste-done` signal. The class handler for the `GtkTextBuffer::undo` signal a `GtkTextBuffer` The class handler for the `GtkTextBuffer::redo` signal a `GtkTextBuffer` The predicate function used by gtk_text_iter_forward_find_char() and gtk_text_iter_backward_find_char(). %TRUE if the predicate is satisfied, and the iteration should stop, and %FALSE otherwise a Unicode code point data passed to the callback A `GtkTextChildAnchor` is a spot in a `GtkTextBuffer` where child widgets can be “anchored”. The anchor can have multiple widgets anchored, to allow for multiple views. Creates a new `GtkTextChildAnchor`. Usually you would then insert it into a `GtkTextBuffer` with [method@Gtk.TextBuffer.insert_child_anchor]. To perform the creation and insertion in one step, use the convenience function [method@Gtk.TextBuffer.create_child_anchor]. a new `GtkTextChildAnchor` Creates a new `GtkTextChildAnchor` with the given replacement character. Usually you would then insert it into a `GtkTextBuffer` with [method@Gtk.TextBuffer.insert_child_anchor]. a new `GtkTextChildAnchor` a replacement character Determines whether a child anchor has been deleted from the buffer. Keep in mind that the child anchor will be unreferenced when removed from the buffer, so you need to hold your own reference (with g_object_ref()) if you plan to use this function — otherwise all deleted child anchors will also be finalized. %TRUE if the child anchor has been deleted from its buffer a `GtkTextChildAnchor` Gets a list of all widgets anchored at this child anchor. The order in which the widgets are returned is not defined. an array of widgets anchored at @anchor a `GtkTextChildAnchor` return location for the length of the array Reading directions for text. No direction. Left to right text direction. Right to left text direction. Granularity types that extend the text selection. Use the `GtkTextView::extend-selection` signal to customize the selection. Selects the current word. It is triggered by a double-click for example. Selects the current line. It is triggered by a triple-click for example. An iterator for the contents of a `GtkTextBuffer`. You may wish to begin by reading the [text widget conceptual overview](section-text-widget.html), which gives an overview of all the objects and data types related to the text widget and how they work together. Assigns the value of @other to @iter. This function is not useful in applications, because iterators can be assigned with `GtkTextIter i = j;`. The function is used by language bindings. a `GtkTextIter` another `GtkTextIter` Moves backward by one character offset. Returns %TRUE if movement was possible; if @iter was the first in the buffer (character offset 0), this function returns %FALSE for convenience when writing loops. whether movement was possible an iterator Moves @count characters backward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. whether @iter moved and is dereferenceable an iterator number of characters to move Like [method@Gtk.TextIter.forward_cursor_position], but moves backward. %TRUE if we moved a `GtkTextIter` Moves up to @count cursor positions. See [method@Gtk.TextIter.forward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` number of positions to move Same as [method@Gtk.TextIter.forward_find_char], but goes backward from @iter. whether a match was found a `GtkTextIter` function to be called on each character user data for @pred search limit Moves @iter to the start of the previous line. Returns %TRUE if @iter could be moved; i.e. if @iter was at character offset 0, this function returns %FALSE. Therefore, if @iter was already on line 0, but not at the start of the line, @iter is snapped to the start of the line and the function returns %TRUE. (Note that this implies that in a loop calling this function, the line number may not change on every iteration, if your first iteration is on line 0.) whether @iter moved an iterator Moves @count lines backward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. If @count is negative, moves forward by 0 - @count lines. whether @iter moved and is dereferenceable a `GtkTextIter` number of lines to move backward Same as [method@Gtk.TextIter.forward_search], but moves backward. @match_end will never be set to a `GtkTextIter` located after @iter, even if there is a possible @match_start before or at @iter. whether a match was found a `GtkTextIter` where the search begins search string bitmask of flags affecting the search return location for start of match return location for end of match location of last possible @match_start, or %NULL for start of buffer Moves backward to the previous sentence start. If @iter is already at the start of a sentence, moves backward to the next one. Sentence boundaries are determined by Pango and should be correct for nearly any language. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` Calls [method@Gtk.TextIter.backward_sentence_start] up to @count times. If @count is negative, moves forward instead of backward. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` number of sentences to move Moves backward to the next toggle (on or off) of the @tag, or to the next toggle of any tag if @tag is %NULL. If no matching tag toggles are found, returns %FALSE, otherwise %TRUE. Does not return toggles located at @iter, only toggles before @iter. Sets @iter to the location of the toggle, or the start of the buffer if no toggle is found. whether we found a tag toggle before @iter a `GtkTextIter` a `GtkTextTag` Moves @iter backward to the previous visible cursor position. See [method@Gtk.TextIter.backward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` Moves up to @count visible cursor positions. See [method@Gtk.TextIter.backward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` number of positions to move Moves @iter to the start of the previous visible line. Returns %TRUE if @iter could be moved; i.e. if @iter was at character offset 0, this function returns %FALSE. Therefore if @iter was already on line 0, but not at the start of the line, @iter is snapped to the start of the line and the function returns %TRUE. (Note that this implies that in a loop calling this function, the line number may not change on every iteration, if your first iteration is on line 0.) whether @iter moved an iterator Moves @count visible lines backward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. If @count is negative, moves forward by 0 - @count lines. whether @iter moved and is dereferenceable a `GtkTextIter` number of lines to move backward Moves backward to the previous visible word start. If @iter is currently on a word start, moves backward to the next one after that. Word breaks are determined by Pango and should be correct for nearly any language. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` Calls [method@Gtk.TextIter.backward_visible_word_start] up to @count times. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` number of times to move Moves backward to the previous word start. If @iter is currently on a word start, moves backward to the next one after that. Word breaks are determined by Pango and should be correct for nearly any language %TRUE if @iter moved and is not the end iterator a `GtkTextIter` Calls [method@Gtk.TextIter.backward_word_start] up to @count times. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` number of times to move Considering the default editability of the buffer, and tags that affect editability, determines whether text inserted at @iter would be editable. If text inserted at @iter would be editable then the user should be allowed to insert text at @iter. [method@Gtk.TextBuffer.insert_interactive] uses this function to decide whether insertions are allowed at a given position. whether text inserted at @iter would be editable an iterator %TRUE if text is editable by default A qsort()-style function that returns negative if @lhs is less than @rhs, positive if @lhs is greater than @rhs, and 0 if they’re equal. Ordering is in character offset order, i.e. the first character in the buffer is less than the second character in the buffer. -1 if @lhs is less than @rhs, 1 if @lhs is greater, 0 if they are equal a `GtkTextIter` another `GtkTextIter` Creates a dynamically-allocated copy of an iterator. This function is not useful in applications, because iterators can be copied with a simple assignment (`GtkTextIter i = j;`). The function is used by language bindings. a copy of the @iter, free with [method@Gtk.TextIter.free] an iterator Returns whether the character at @iter is within an editable region of text. Non-editable text is “locked” and can’t be changed by the user via `GtkTextView`. If no tags applied to this text affect editability, @default_setting will be returned. You don’t want to use this function to decide whether text can be inserted at @iter, because for insertion you don’t want to know whether the char at @iter is inside an editable range, you want to know whether a new character inserted at @iter would be inside an editable range. Use [method@Gtk.TextIter.can_insert] to handle this case. whether @iter is inside an editable range an iterator %TRUE if text is editable by default Returns %TRUE if @iter points to the start of the paragraph delimiter characters for a line. Delimiters will be either a newline, a carriage return, a carriage return followed by a newline, or a Unicode paragraph separator character. Note that an iterator pointing to the \n of a \r\n pair will not be counted as the end of a line, the line ends before the \r. The end iterator is considered to be at the end of a line, even though there are no paragraph delimiter chars there. whether @iter is at the end of a line an iterator Determines whether @iter ends a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language. %TRUE if @iter is at the end of a sentence. a `GtkTextIter` Returns %TRUE if @tag is toggled off at exactly this point. If @tag is %NULL, returns %TRUE if any tag is toggled off at this point. Note that if this function returns %TRUE, it means that @iter is at the end of the tagged range, but that the character at @iter is outside the tagged range. In other words, unlike [method@Gtk.TextIter.starts_tag], if this function returns %TRUE, [method@Gtk.TextIter.has_tag] will return %FALSE for the same parameters. whether @iter is the end of a range tagged with @tag an iterator a `GtkTextTag` Determines whether @iter ends a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language. %TRUE if @iter is at the end of a word a `GtkTextIter` Tests whether two iterators are equal, using the fastest possible mechanism. This function is very fast; you can expect it to perform better than e.g. getting the character offset for each iterator and comparing the offsets yourself. Also, it’s a bit faster than [method@Gtk.TextIter.compare]. %TRUE if the iterators point to the same place in the buffer a `GtkTextIter` another `GtkTextIter` Moves @iter forward by one character offset. Note that images embedded in the buffer occupy 1 character slot, so this function may actually move onto an image instead of a character, if you have images in your buffer. If @iter is the end iterator or one character before it, @iter will now point at the end iterator, and this function returns %FALSE for convenience when writing loops. whether @iter moved and is dereferenceable an iterator Moves @count characters if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. The return value indicates whether the new position of @iter is different from its original position, and dereferenceable (the last iterator in the buffer is not dereferenceable). If @count is 0, the function does nothing and returns %FALSE. whether @iter moved and is dereferenceable an iterator number of characters to move, may be negative Moves @iter forward by a single cursor position. Cursor positions are (unsurprisingly) positions where the cursor can appear. Perhaps surprisingly, there may not be a cursor position between all characters. The most common example for European languages would be a carriage return/newline sequence. For some Unicode characters, the equivalent of say the letter “a” with an accent mark will be represented as two characters, first the letter then a "combining mark" that causes the accent to be rendered; so the cursor can’t go between those two characters. See also the [struct@Pango.LogAttr] struct and the [func@Pango.break] function. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` Moves up to @count cursor positions. See [method@Gtk.TextIter.forward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` number of positions to move Advances @iter, calling @pred on each character. If @pred returns %TRUE, returns %TRUE and stops scanning. If @pred never returns %TRUE, @iter is set to @limit if @limit is non-%NULL, otherwise to the end iterator. whether a match was found a `GtkTextIter` a function to be called on each character user data for @pred search limit Moves @iter to the start of the next line. If the iter is already on the last line of the buffer, moves the iter to the end of the current line. If after the operation, the iter is at the end of the buffer and not dereferenceable, returns %FALSE. Otherwise, returns %TRUE. whether @iter can be dereferenced an iterator Moves @count lines forward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. If @count is negative, moves backward by 0 - @count lines. whether @iter moved and is dereferenceable a `GtkTextIter` number of lines to move forward Searches forward for @str. Any match is returned by setting @match_start to the first character of the match and @match_end to the first character after the match. The search will not continue past @limit. Note that a search is a linear or O(n) operation, so you may wish to use @limit to avoid locking up your UI on large buffers. @match_start will never be set to a `GtkTextIter` located before @iter, even if there is a possible @match_end after or at @iter. whether a match was found start of search a search string flags affecting how the search is done return location for start of match return location for end of match location of last possible @match_end, or %NULL for the end of the buffer Moves forward to the next sentence end. If @iter is at the end of a sentence, moves to the next end of sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` Calls [method@Gtk.TextIter.forward_sentence_end] @count times. If @count is negative, moves backward instead of forward. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` number of sentences to move Moves @iter forward to the “end iterator”, which points one past the last valid character in the buffer. [method@Gtk.TextIter.get_char] called on the end iterator returns 0, which is convenient for writing loops. a `GtkTextIter` Moves the iterator to point to the paragraph delimiter characters. The possible characters are either a newline, a carriage return, a carriage return/newline in sequence, or the Unicode paragraph separator character. If the iterator is already at the paragraph delimiter characters, moves to the paragraph delimiter characters for the next line. If @iter is on the last line in the buffer, which does not end in paragraph delimiters, moves to the end iterator (end of the last line), and returns %FALSE. %TRUE if we moved and the new location is not the end iterator a `GtkTextIter` Moves forward to the next toggle (on or off) of the @tag, or to the next toggle of any tag if @tag is %NULL. If no matching tag toggles are found, returns %FALSE, otherwise %TRUE. Does not return toggles located at @iter, only toggles after @iter. Sets @iter to the location of the toggle, or to the end of the buffer if no toggle is found. whether we found a tag toggle after @iter a `GtkTextIter` a `GtkTextTag` Moves @iter forward to the next visible cursor position. See [method@Gtk.TextIter.forward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` Moves up to @count visible cursor positions. See [method@Gtk.TextIter.forward_cursor_position] for details. %TRUE if we moved and the new position is dereferenceable a `GtkTextIter` number of positions to move Moves @iter to the start of the next visible line. Returns %TRUE if there was a next line to move to, and %FALSE if @iter was simply moved to the end of the buffer and is now not dereferenceable, or if @iter was already at the end of the buffer. whether @iter can be dereferenced an iterator Moves @count visible lines forward, if possible. If @count would move past the start or end of the buffer, moves to the start or end of the buffer. The return value indicates whether the iterator moved onto a dereferenceable position; if the iterator didn’t move, or moved onto the end iterator, then %FALSE is returned. If @count is 0, the function does nothing and returns %FALSE. If @count is negative, moves backward by 0 - @count lines. whether @iter moved and is dereferenceable a `GtkTextIter` number of lines to move forward Moves forward to the next visible word end. If @iter is currently on a word end, moves forward to the next one after that. Word breaks are determined by Pango and should be correct for nearly any language %TRUE if @iter moved and is not the end iterator a `GtkTextIter` Calls [method@Gtk.TextIter.forward_visible_word_end] up to @count times. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` number of times to move Moves forward to the next word end. If @iter is currently on a word end, moves forward to the next one after that. Word breaks are determined by Pango and should be correct for nearly any language. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` Calls [method@Gtk.TextIter.forward_word_end] up to @count times. %TRUE if @iter moved and is not the end iterator a `GtkTextIter` number of times to move Free an iterator allocated on the heap. This function is intended for use in language bindings, and is not especially useful for applications, because iterators can simply be allocated on the stack. a dynamically-allocated iterator Returns the `GtkTextBuffer` this iterator is associated with. the buffer an iterator Returns the number of bytes in the line containing @iter, including the paragraph delimiters. number of bytes in the line an iterator The Unicode character at this iterator is returned. Equivalent to operator* on a C++ iterator. If the element at this iterator is a non-character element, such as an image embedded in the buffer, the Unicode “unknown” character 0xFFFC is returned. If invoked on the end iterator, zero is returned; zero is not a valid Unicode character. So you can write a loop which ends when this function returns 0. a Unicode character, or 0 if @iter is not dereferenceable an iterator Returns the number of characters in the line containing @iter, including the paragraph delimiters. number of characters in the line an iterator If the location at @iter contains a child anchor, the anchor is returned. Otherwise, %NULL is returned. the anchor at @iter an iterator Returns the language in effect at @iter. If no tags affecting language apply to @iter, the return value is identical to that of [func@Gtk.get_default_language]. language in effect at @iter an iterator Returns the line number containing the iterator. Lines in a `GtkTextBuffer` are numbered beginning with 0 for the first line in the buffer. a line number an iterator Returns the byte index of the iterator, counting from the start of a newline-terminated line. Remember that `GtkTextBuffer` encodes text in UTF-8, and that characters can require a variable number of bytes to represent. distance from start of line, in bytes an iterator Returns the character offset of the iterator, counting from the start of a newline-terminated line. The first character on the line has offset 0. offset from start of line an iterator Returns a list of all `GtkTextMark` at this location. Because marks are not iterable (they don’t take up any "space" in the buffer, they are just marks in between iterable locations), multiple marks can exist in the same place. The returned list is not in any meaningful order. list of `GtkTextMark` an iterator Returns the character offset of an iterator. Each character in a `GtkTextBuffer` has an offset, starting with 0 for the first character in the buffer. Use [method@Gtk.TextBuffer.get_iter_at_offset] to convert an offset back into an iterator. a character offset an iterator If the element at @iter is a paintable, the paintable is returned. Otherwise, %NULL is returned. the paintable at @iter an iterator Returns the text in the given range. A “slice” is an array of characters encoded in UTF-8 format, including the Unicode “unknown” character 0xFFFC for iterable non-character elements in the buffer, such as images. Because images are encoded in the slice, byte and character offsets in the returned array will correspond to byte offsets in the text buffer. Note that 0xFFFC can occur in normal text as well, so it is not a reliable indicator that a paintable or widget is in the buffer. slice of text from the buffer iterator at start of a range iterator at end of a range Returns a list of tags that apply to @iter, in ascending order of priority. The highest-priority tags are last. The `GtkTextTag`s in the list don’t have a reference added, but you have to free the list itself. list of `GtkTextTag` a `GtkTextIter` Returns text in the given range. If the range contains non-text elements such as images, the character and byte offsets in the returned string will not correspond to character and byte offsets in the buffer. If you want offsets to correspond, see [method@Gtk.TextIter.get_slice]. array of characters from the buffer iterator at start of a range iterator at end of a range Returns a list of `GtkTextTag` that are toggled on or off at this point. If @toggled_on is %TRUE, the list contains tags that are toggled on. If a tag is toggled on at @iter, then some non-empty range of characters following @iter has that tag applied to it. If a tag is toggled off, then some non-empty range following @iter does not have the tag applied to it. tags toggled at this point an iterator %TRUE to get toggled-on tags Returns the number of bytes from the start of the line to the given @iter, not counting bytes that are invisible due to tags with the “invisible” flag toggled on. byte index of @iter with respect to the start of the line a `GtkTextIter` Returns the offset in characters from the start of the line to the given @iter, not counting characters that are invisible due to tags with the “invisible” flag toggled on. offset in visible characters from the start of the line a `GtkTextIter` Returns visible text in the given range. Like [method@Gtk.TextIter.get_slice], but invisible text is not included. Invisible text is usually invisible because a `GtkTextTag` with the “invisible” attribute turned on has been applied to it. slice of text from the buffer iterator at start of range iterator at end of range Returns visible text in the given range. Like [method@Gtk.TextIter.get_text], but invisible text is not included. Invisible text is usually invisible because a `GtkTextTag` with the “invisible” attribute turned on has been applied to it. string containing visible text in the range iterator at start of range iterator at end of range Returns %TRUE if @iter points to a character that is part of a range tagged with @tag. See also [method@Gtk.TextIter.starts_tag] and [method@Gtk.TextIter.ends_tag]. whether @iter is tagged with @tag an iterator a `GtkTextTag` Checks whether @iter falls in the range [@start, @end). @start and @end must be in ascending order. %TRUE if @iter is in the range a `GtkTextIter` start of range end of range Determines whether @iter is inside a sentence (as opposed to in between two sentences, e.g. after a period and before the first letter of the next sentence). Sentence boundaries are determined by Pango and should be correct for nearly any language. %TRUE if @iter is inside a sentence. a `GtkTextIter` Determines whether the character pointed by @iter is part of a natural-language word (as opposed to say inside some whitespace). Word breaks are determined by Pango and should be correct for nearly any language. Note that if [method@Gtk.TextIter.starts_word] returns %TRUE, then this function returns %TRUE too, since @iter points to the first character of the word. %TRUE if @iter is inside a word a `GtkTextIter` Determine if @iter is at a cursor position. See [method@Gtk.TextIter.forward_cursor_position] or [struct@Pango.LogAttr] or [func@Pango.break] for details on what a cursor position is. %TRUE if the cursor can be placed at @iter a `GtkTextIter` Returns %TRUE if @iter is the end iterator. This means it is one past the last dereferenceable iterator in the buffer. [method@Gtk.TextIter.is_end] is the most efficient way to check whether an iterator is the end iterator. whether @iter is the end iterator an iterator Returns %TRUE if @iter is the first iterator in the buffer. whether @iter is the first in the buffer an iterator Swaps the value of @first and @second if @second comes before @first in the buffer. That is, ensures that @first and @second are in sequence. Most text buffer functions that take a range call this automatically on your behalf, so there’s no real reason to call it yourself in those cases. There are some exceptions, such as [method@Gtk.TextIter.in_range], that expect a pre-sorted range. a `GtkTextIter` another `GtkTextIter` Moves iterator @iter to the start of the line @line_number. If @line_number is negative or larger than or equal to the number of lines in the buffer, moves @iter to the start of the last line in the buffer. a `GtkTextIter` line number (counted from 0) Same as [method@Gtk.TextIter.set_line_offset], but works with a byte index. The given byte index must be at the start of a character, it can’t be in the middle of a UTF-8 encoded character. a `GtkTextIter` a byte index relative to the start of @iter’s current line Moves @iter within a line, to a new character (not byte) offset. The given character offset must be less than or equal to the number of characters in the line; if equal, @iter moves to the start of the next line. See [method@Gtk.TextIter.set_line_index] if you have a byte index rather than a character offset. a `GtkTextIter` a character offset relative to the start of @iter’s current line Sets @iter to point to @char_offset. @char_offset counts from the start of the entire text buffer, starting with 0. a `GtkTextIter` a character number Like [method@Gtk.TextIter.set_line_index], but the index is in visible bytes, i.e. text with a tag making it invisible is not counted in the index. a `GtkTextIter` a byte index Like [method@Gtk.TextIter.set_line_offset], but the offset is in visible characters, i.e. text with a tag making it invisible is not counted in the offset. a `GtkTextIter` a character offset Returns %TRUE if @iter begins a paragraph. This is the case if [method@Gtk.TextIter.get_line_offset] would return 0. However this function is potentially more efficient than [method@Gtk.TextIter.get_line_offset], because it doesn’t have to compute the offset, it just has to see whether it’s 0. whether @iter begins a line an iterator Determines whether @iter begins a sentence. Sentence boundaries are determined by Pango and should be correct for nearly any language. %TRUE if @iter is at the start of a sentence. a `GtkTextIter` Returns %TRUE if @tag is toggled on at exactly this point. If @tag is %NULL, returns %TRUE if any tag is toggled on at this point. Note that if this function returns %TRUE, it means that @iter is at the beginning of the tagged range, and that the character at @iter is inside the tagged range. In other words, unlike [method@Gtk.TextIter.ends_tag], if this function returns %TRUE, [method@Gtk.TextIter.has_tag] will also return %TRUE for the same parameters. whether @iter is the start of a range tagged with @tag an iterator a `GtkTextTag` Determines whether @iter begins a natural-language word. Word breaks are determined by Pango and should be correct for nearly any language. %TRUE if @iter is at the start of a word a `GtkTextIter` Gets whether a range with @tag applied to it begins or ends at @iter. This is equivalent to (gtk_text_iter_starts_tag() || gtk_text_iter_ends_tag()) whether @tag is toggled on or off at @iter an iterator a `GtkTextTag` A `GtkTextMark` is a position in a `GtkTextbuffer` that is preserved across modifications. You may wish to begin by reading the [text widget conceptual overview](section-text-widget.html), which gives an overview of all the objects and data types related to the text widget and how they work together. A `GtkTextMark` is like a bookmark in a text buffer; it preserves a position in the text. You can convert the mark to an iterator using [method@Gtk.TextBuffer.get_iter_at_mark]. Unlike iterators, marks remain valid across buffer mutations, because their behavior is defined when text is inserted or deleted. When text containing a mark is deleted, the mark remains in the position originally occupied by the deleted text. When text is inserted at a mark, a mark with “left gravity” will be moved to the beginning of the newly-inserted text, and a mark with “right gravity” will be moved to the end. Note that “left” and “right” here refer to logical direction (left is the toward the start of the buffer); in some languages such as Hebrew the logically-leftmost text is not actually on the left when displayed. Marks are reference counted, but the reference count only controls the validity of the memory; marks can be deleted from the buffer at any time with [method@Gtk.TextBuffer.delete_mark]. Once deleted from the buffer, a mark is essentially useless. Marks optionally have names; these can be convenient to avoid passing the `GtkTextMark` object around. Marks are typically created using the [method@Gtk.TextBuffer.create_mark] function. Creates a text mark. Add it to a buffer using [method@Gtk.TextBuffer.add_mark]. If @name is %NULL, the mark is anonymous; otherwise, the mark can be retrieved by name using [method@Gtk.TextBuffer.get_mark]. If a mark has left gravity, and text is inserted at the mark’s current location, the mark will be moved to the left of the newly-inserted text. If the mark has right gravity (@left_gravity = %FALSE), the mark will end up on the right of newly-inserted text. The standard left-to-right cursor is a mark with right gravity (when you type, the cursor stays on the right side of the text you’re typing). new `GtkTextMark` mark name whether the mark should have left gravity Gets the buffer this mark is located inside. Returns %NULL if the mark is deleted. the mark’s `GtkTextBuffer` a `GtkTextMark` Returns %TRUE if the mark has been removed from its buffer. See [method@Gtk.TextBuffer.add_mark] for a way to add it to a buffer again. whether the mark is deleted a `GtkTextMark` Determines whether the mark has left gravity. %TRUE if the mark has left gravity, %FALSE otherwise a `GtkTextMark` Returns the mark name. Returns %NULL for anonymous marks. mark name a `GtkTextMark` Returns %TRUE if the mark is visible. A cursor is displayed for visible marks. %TRUE if visible a `GtkTextMark` Sets the visibility of @mark. The insertion point is normally visible, i.e. you can see it as a vertical bar. Also, the text widget uses a visible mark to indicate where a drop will occur when dragging-and-dropping text. Most other marks are not visible. Marks are not visible by default. a GtkTextMark visibility of mark Whether the mark has left gravity. When text is inserted at the mark’s current location, if the mark has left gravity it will be moved to the left of the newly-inserted text, otherwise to the right. The name of the mark or %NULL if the mark is anonymous. Flags affecting how a search is done. If neither %GTK_TEXT_SEARCH_VISIBLE_ONLY nor %GTK_TEXT_SEARCH_TEXT_ONLY are enabled, the match must be exact; the special 0xFFFC character will match embedded paintables or child widgets. Search only visible data. A search match may have invisible text interspersed. Search only text. A match may have paintables or child widgets mixed inside the matched range. The text will be matched regardless of what case it is in. A tag that can be applied to text contained in a `GtkTextBuffer`. You may wish to begin by reading the [text widget conceptual overview](section-text-widget.html), which gives an overview of all the objects and data types related to the text widget and how they work together. Tags should be in the [class@Gtk.TextTagTable] for a given `GtkTextBuffer` before using them with that buffer. [method@Gtk.TextBuffer.create_tag] is the best way to create tags. See “gtk4-demo” for numerous examples. For each property of `GtkTextTag`, there is a “set” property, e.g. “font-set” corresponds to “font”. These “set” properties reflect whether a property has been set or not. They are maintained by GTK and you should not set them independently. Creates a `GtkTextTag`. a new `GtkTextTag` tag name Emits the [signal@Gtk.TextTagTable::tag-changed] signal on the `GtkTextTagTable` where the tag is included. The signal is already emitted when setting a `GtkTextTag` property. This function is useful for a `GtkTextTag` subclass. a `GtkTextTag` whether the change affects the `GtkTextView` layout Get the tag priority. The tag’s priority. a `GtkTextTag` Sets the priority of a `GtkTextTag`. Valid priorities start at 0 and go to one less than [method@Gtk.TextTagTable.get_size]. Each tag in a table has a unique priority; setting the priority of one tag shifts the priorities of all the other tags in the table to maintain a unique priority for each tag. Higher priority tags “win” if two tags both set the same text attribute. When adding a tag to a tag table, it will be assigned the highest priority in the table by default; so normally the precedence of a set of tags is the order in which they were added to the table, or created with [method@Gtk.TextBuffer.create_tag], which adds the tag to the buffer’s table automatically. a `GtkTextTag` the new priority Whether the margins accumulate or override each other. When set to %TRUE the margins of this tag are added to the margins of any other non-accumulative margins present. When set to %FALSE the margins override one another (the default). Whether breaks are allowed. Whether the `allow-breaks` property is set. Background color as a string. Whether the background color fills the entire line height or only the height of the tagged characters. Whether the `background-full-height` property is set. Background color as a `GdkRGBA`. Whether the `background` property is set. Text direction, e.g. right-to-left or left-to-right. Whether the text can be modified by the user. Whether the `editable` property is set. Whether font fallback is enabled. When set to %TRUE, other fonts will be substituted where the current font is missing glyphs. Whether the `fallback` property is set. Name of the font family, e.g. Sans, Helvetica, Times, Monospace. Whether the `family` property is set. Font description as string, e.g. \"Sans Italic 12\". Note that the initial value of this property depends on the internals of `PangoFontDescription`. Font description as a `PangoFontDescription`. OpenType font features, as a string. Whether the `font-features` property is set. Foreground color as a string. Foreground color as a `GdkRGBA`. Whether the `foreground` property is set. Amount to indent the paragraph, in pixels. A negative value of indent will produce a hanging indentation. That is, the first line will have the full width, and subsequent lines will be indented by the absolute value of indent. Whether the `indent` property is set. Whether to insert hyphens at breaks. Whether the `insert-hyphens` property is set. Whether this text is hidden. Note that there may still be problems with the support for invisible text, in particular when navigating programmatically inside a buffer containing invisible segments. Whether the `invisible` property is set. Left, right, or center justification. Whether the `justification` property is set. The language this text is in, as an ISO code. Pango can use this as a hint when rendering the text. If not set, an appropriate default will be used. Note that the initial value of this property depends on the current locale, see also [func@Gtk.get_default_language]. Whether the `language` property is set. Width of the left margin in pixels. Whether the `left-margin` property is set. Extra spacing between graphemes, in Pango units. Whether the `letter-spacing` property is set. Factor to scale line height by. Whether the `line-height` property is set. The name used to refer to the tag. %NULL for anonymous tags. Style of overline for this text. This property modifies the color of overlines. If not set, overlines will use the foreground color. Whether the `overline-rgba` property is set. Whether the `overline` property is set. The paragraph background color as a string. The paragraph background color as a `GdkRGBA`. Whether the `paragraph-background` property is set. Pixels of blank space above paragraphs. Whether the `pixels-above-lines` property is set. Pixels of blank space below paragraphs. Whether the `pixels-below-lines` property is set. Pixels of blank space between wrapped lines in a paragraph. Whether the `pixels-inside-wrap` property is set. Width of the right margin, in pixels. Whether the `right-margin` property is set. Offset of text above the baseline, in Pango units. Negative values go below the baseline. Whether the `rise` property is set. Font size as a scale factor relative to the default font size. This properly adapts to theme changes, etc. so is recommended. Pango predefines some scales such as %PANGO_SCALE_X_LARGE. Whether the `scale` property is set. Whether this tag represents a single sentence. This affects cursor movement. Whether the `sentence` property is set. How to render invisible characters. Whether the `show-spaces` property is set. Font size in Pango units. Font size in points. Whether the `size` property is set. Font stretch as a `PangoStretch`, e.g. %PANGO_STRETCH_CONDENSED. Whether the `stretch` property is set. Whether to strike through the text. This property modifies the color of strikeouts. If not set, strikeouts will use the foreground color. If the `strikethrough-rgba` property has been set. Whether the `strikethrough` property is set. Font style as a `PangoStyle`, e.g. %PANGO_STYLE_ITALIC. Whether the `style` property is set. Custom tabs for this text. Whether the `tabs` property is set. How to transform the text for display. Whether the `text-transform` property is set. Style of underline for this text. This property modifies the color of underlines. If not set, underlines will use the foreground color. If [property@Gtk.TextTag:underline] is set to %PANGO_UNDERLINE_ERROR, an alternate color may be applied instead of the foreground. Setting this property will always override those defaults. If the `underline-rgba` property has been set. Whether the `underline` property is set. Font variant as a `PangoVariant`, e.g. %PANGO_VARIANT_SMALL_CAPS. Whether the `variant` property is set. Font weight as an integer. Whether the `weight` property is set. Whether this tag represents a single word. This affects line breaks and cursor movement. Whether the `word` property is set. Whether to wrap lines never, at word boundaries, or at character boundaries. Whether the `wrap-mode` property is set. The collection of tags in a `GtkTextBuffer` You may wish to begin by reading the [text widget conceptual overview](section-text-widget.html), which gives an overview of all the objects and data types related to the text widget and how they work together. # GtkTextTagTables as GtkBuildable The `GtkTextTagTable` implementation of the `GtkBuildable` interface supports adding tags by specifying “tag” as the “type” attribute of a `<child>` element. An example of a UI definition fragment specifying tags: ```xml <object class="GtkTextTagTable"> <child type="tag"> <object class="GtkTextTag"/> </child> </object> ``` Creates a new `GtkTextTagTable`. The table contains no tags by default. a new `GtkTextTagTable` Add a tag to the table. The tag is assigned the highest priority in the table. @tag must not be in a tag table already, and may not have the same name as an already-added tag. %TRUE on success. a `GtkTextTagTable` a `GtkTextTag` Calls @func on each tag in @table, with user data @data. Note that the table may not be modified while iterating over it (you can’t add/remove tags). a `GtkTextTagTable` a function to call on each tag user data Returns the size of the table (number of tags) number of tags in @table a `GtkTextTagTable` Look up a named tag. The tag a `GtkTextTagTable` name of a tag Remove a tag from the table. If a `GtkTextBuffer` has @table as its tag table, the tag is removed from the buffer. The table’s reference to the tag is removed, so the tag will end up destroyed if you don’t have a reference to it. a `GtkTextTagTable` a `GtkTextTag` Emitted every time a new tag is added in the `GtkTextTagTable`. the added tag. Emitted every time a tag in the `GtkTextTagTable` changes. the changed tag. whether the change affects the `GtkTextView` layout. Emitted every time a tag is removed from the `GtkTextTagTable`. The @tag is still valid by the time the signal is emitted, but it is not associated with a tag table any more. the removed tag. A function used with gtk_text_tag_table_foreach(), to iterate over every `GtkTextTag` inside a `GtkTextTagTable`. the `GtkTextTag` data passed to gtk_text_tag_table_foreach() A widget that displays the contents of a [class@Gtk.TextBuffer].  You may wish to begin by reading the [conceptual overview](section-text-widget.html), which gives an overview of all the objects and data types related to the text widget and how they work together. ## Shortcuts and Gestures `GtkTextView` supports the following keyboard shortcuts: - <kbd>Shift</kbd>+<kbd>F10</kbd> or <kbd>Menu</kbd> opens the context menu. - <kbd>Ctrl</kbd>+<kbd>Z</kbd> undoes the last modification. - <kbd>Ctrl</kbd>+<kbd>Y</kbd> or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Z</kbd> redoes the last undone modification. Additionally, the following signals have default keybindings: - [signal@Gtk.TextView::backspace] - [signal@Gtk.TextView::copy-clipboard] - [signal@Gtk.TextView::cut-clipboard] - [signal@Gtk.TextView::delete-from-cursor] - [signal@Gtk.TextView::insert-emoji] - [signal@Gtk.TextView::move-cursor] - [signal@Gtk.TextView::paste-clipboard] - [signal@Gtk.TextView::select-all] - [signal@Gtk.TextView::toggle-cursor-visible] - [signal@Gtk.TextView::toggle-overwrite] ## Actions `GtkTextView` defines a set of built-in actions: - `clipboard.copy` copies the contents to the clipboard. - `clipboard.cut` copies the contents to the clipboard and deletes it from the widget. - `clipboard.paste` inserts the contents of the clipboard into the widget. - `menu.popup` opens the context menu. - `misc.insert-emoji` opens the Emoji chooser. - `selection.delete` deletes the current selection. - `selection.select-all` selects all of the widgets content. - `text.redo` redoes the last change to the contents. - `text.undo` undoes the last change to the contents. ## CSS nodes ``` textview.view ├── border.top ├── border.left ├── text │ ╰── [selection] ├── border.right ├── border.bottom ╰── [window.popup] ``` `GtkTextView` has a main css node with name textview and style class .view, and subnodes for each of the border windows, and the main text area, with names border and text, respectively. The border nodes each get one of the style classes .left, .right, .top or .bottom. A node representing the selection will appear below the text node. If a context menu is opened, the window node will appear as a subnode of the main node. ## Accessibility `GtkTextView` uses the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role. Creates a new `GtkTextView`. If you don’t call [method@Gtk.TextView.set_buffer] before using the text view, an empty default buffer will be created for you. Get the buffer with [method@Gtk.TextView.get_buffer]. If you want to specify your own buffer, consider [ctor@Gtk.TextView.new_with_buffer]. a new `GtkTextView` Creates a new `GtkTextView` widget displaying the buffer @buffer. One buffer can be shared among many widgets. @buffer may be %NULL to create a default buffer, in which case this function is equivalent to [ctor@Gtk.TextView.new]. The text view adds its own reference count to the buffer; it does not take over an existing reference. a new `GtkTextView`. a `GtkTextBuffer` The class handler for the `GtkTextView::backspace` keybinding signal. The class handler for the `GtkTextView::copy-clipboard` keybinding signal. The create_buffer vfunc is called to create a `GtkTextBuffer` for the text view. The default implementation is to just call gtk_text_buffer_new(). The class handler for the `GtkTextView::cut-clipboard` keybinding signal The class handler for the `GtkTextView::delete-from-cursor` keybinding signal. The class handler for the `GtkTextView::extend-selection` signal. The class handler for the `GtkTextView::insert-at-cursor` keybinding signal. The class handler for the `GtkTextView::insert-emoji` signal. The class handler for the `GtkTextView::move-cursor` keybinding signal. The class handler for the `GtkTextView::paste-clipboard` keybinding signal. The class handler for the `GtkTextView::set-anchor` keybinding signal. The snapshot_layer vfunc is called before and after the text view is drawing its own text. Applications can override this vfunc in a subclass to draw customized content underneath or above the text. In the %GTK_TEXT_VIEW_LAYER_BELOW_TEXT and %GTK_TEXT_VIEW_LAYER_ABOVE_TEXT layers the drawing is done in the buffer coordinate space. The class handler for the `GtkTextView::toggle-overwrite` keybinding signal. Adds a child widget in the text buffer, at the given @anchor. a `GtkTextView` a `GtkWidget` a `GtkTextChildAnchor` in the `GtkTextBuffer` for @text_view Adds @child at a fixed coordinate in the `GtkTextView`'s text window. The @xpos and @ypos must be in buffer coordinates (see [method@Gtk.TextView.get_iter_location] to convert to buffer coordinates). @child will scroll with the text view. If instead you want a widget that will not move with the `GtkTextView` contents see `GtkOverlay`. a `GtkTextView` a `GtkWidget` X position of child in window coordinates Y position of child in window coordinates Moves the given @iter backward by one display (wrapped) line. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the `GtkTextBuffer`. %TRUE if @iter was moved and is not on the end iterator a `GtkTextView` a `GtkTextIter` Moves the given @iter backward to the next display line start. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the `GtkTextBuffer`. %TRUE if @iter was moved and is not on the end iterator a `GtkTextView` a `GtkTextIter` Converts buffer coordinates to window coordinates. a `GtkTextView` a `GtkTextWindowType` buffer x coordinate buffer y coordinate window x coordinate return location window y coordinate return location Moves the given @iter forward by one display (wrapped) line. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the `GtkTextBuffer`. %TRUE if @iter was moved and is not on the end iterator a `GtkTextView` a `GtkTextIter` Moves the given @iter forward to the next display line end. A display line is different from a paragraph. Paragraphs are separated by newlines or other paragraph separator characters. Display lines are created by line-wrapping a paragraph. If wrapping is turned off, display lines and paragraphs will be the same. Display lines are divided differently for each view, since they depend on the view’s width; paragraphs are the same in all views, since they depend on the contents of the `GtkTextBuffer`. %TRUE if @iter was moved and is not on the end iterator a `GtkTextView` a `GtkTextIter` Returns whether pressing the <kbd>Tab</kbd> key inserts a tab characters. See [method@Gtk.TextView.set_accepts_tab]. %TRUE if pressing the Tab key inserts a tab character, %FALSE if pressing the Tab key moves the keyboard focus. A `GtkTextView` Gets the bottom margin for text in the @text_view. bottom margin in pixels a `GtkTextView` Returns the `GtkTextBuffer` being displayed by this text view. The reference count on the buffer is not incremented; the caller of this function won’t own a new reference. a `GtkTextBuffer` a `GtkTextView` Determine the positions of the strong and weak cursors if the insertion point is at @iter. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of the directionality equal to the base direction of the paragraph are inserted. The weak cursor location is the location where characters of the directionality opposite to the base direction of the paragraph are inserted. If @iter is %NULL, the actual cursor position is used. Note that if @iter happens to be the actual cursor position, and there is currently an IM preedit sequence being entered, the returned locations will be adjusted to account for the preedit cursor’s offset within the preedit sequence. The rectangle position is in buffer coordinates; use [method@Gtk.TextView.buffer_to_window_coords] to convert these coordinates to coordinates for one of the windows in the text view. a `GtkTextView` a `GtkTextIter` location to store the strong cursor position location to store the weak cursor position Find out whether the cursor should be displayed. whether the insertion mark is visible a `GtkTextView` Returns the default editability of the `GtkTextView`. Tags in the buffer may override this setting for some ranges of text. whether text is editable by default a `GtkTextView` Gets the menu model that gets added to the context menu or %NULL if none has been set. the menu model a `GtkTextView` Gets a `GtkWidget` that has previously been set as gutter. See [method@Gtk.TextView.set_gutter]. @win must be one of %GTK_TEXT_WINDOW_LEFT, %GTK_TEXT_WINDOW_RIGHT, %GTK_TEXT_WINDOW_TOP, or %GTK_TEXT_WINDOW_BOTTOM. a `GtkWidget` a `GtkTextView` a `GtkTextWindowType` Gets the default indentation of paragraphs in @text_view. Tags in the view’s buffer may override the default. The indentation may be negative. number of pixels of indentation a `GtkTextView` Gets the `input-hints` of the `GtkTextView`. the input hints a `GtkTextView` Gets the `input-purpose` of the `GtkTextView`. the input purpose a `GtkTextView` Retrieves the iterator at buffer coordinates @x and @y. Buffer coordinates are coordinates for the entire buffer, not just the currently-displayed portion. If you have coordinates from an event, you have to convert those to buffer coordinates with [method@Gtk.TextView.window_to_buffer_coords]. %TRUE if the position is over text a `GtkTextView` a `GtkTextIter` x position, in buffer coordinates y position, in buffer coordinates Retrieves the iterator pointing to the character at buffer coordinates @x and @y. Buffer coordinates are coordinates for the entire buffer, not just the currently-displayed portion. If you have coordinates from an event, you have to convert those to buffer coordinates with [method@Gtk.TextView.window_to_buffer_coords]. Note that this is different from [method@Gtk.TextView.get_iter_at_location], which returns cursor locations, i.e. positions between characters. %TRUE if the position is over text a `GtkTextView` a `GtkTextIter` if non-%NULL, location to store an integer indicating where in the grapheme the user clicked. It will either be zero, or the number of characters in the grapheme. 0 represents the trailing edge of the grapheme. x position, in buffer coordinates y position, in buffer coordinates Gets a rectangle which roughly contains the character at @iter. The rectangle position is in buffer coordinates; use [method@Gtk.TextView.buffer_to_window_coords] to convert these coordinates to coordinates for one of the windows in the text view. a `GtkTextView` a `GtkTextIter` bounds of the character at @iter Gets the default justification of paragraphs in @text_view. Tags in the buffer may override the default. default justification a `GtkTextView` Gets the default left margin size of paragraphs in the @text_view. Tags in the buffer may override the default. left margin in pixels a `GtkTextView` Gets the `GtkTextIter` at the start of the line containing the coordinate @y. @y is in buffer coordinates, convert from window coordinates with [method@Gtk.TextView.window_to_buffer_coords]. If non-%NULL, @line_top will be filled with the coordinate of the top edge of the line. a `GtkTextView` a `GtkTextIter` a y coordinate return location for top coordinate of the line Gets the y coordinate of the top of the line containing @iter, and the height of the line. The coordinate is a buffer coordinate; convert to window coordinates with [method@Gtk.TextView.buffer_to_window_coords]. a `GtkTextView` a `GtkTextIter` return location for a y coordinate return location for a height Gets the `PangoContext` that is used for rendering LTR directed text layouts. The context may be replaced when CSS changes occur. a `PangoContext` a `GtkTextView` Gets whether the `GtkTextView` uses monospace styling. %TRUE if monospace fonts are desired a `GtkTextView` Returns whether the `GtkTextView` is in overwrite mode or not. whether @text_view is in overwrite mode or not. a `GtkTextView` Gets the default number of pixels to put above paragraphs. Adding this function with [method@Gtk.TextView.get_pixels_below_lines] is equal to the line space between each paragraph. default number of pixels above paragraphs a `GtkTextView` Gets the default number of pixels to put below paragraphs. The line space is the sum of the value returned by this function and the value returned by [method@Gtk.TextView.get_pixels_above_lines]. default number of blank pixels below paragraphs a `GtkTextView` Gets the default number of pixels to put between wrapped lines inside a paragraph. default number of pixels of blank space between wrapped lines a `GtkTextView` Gets the default right margin for text in @text_view. Tags in the buffer may override the default. right margin in pixels a `GtkTextView` Gets the `PangoContext` that is used for rendering RTL directed text layouts. The context may be replaced when CSS changes occur. a `PangoContext` a `GtkTextView` Gets the default tabs for @text_view. Tags in the buffer may override the defaults. The returned array will be %NULL if “standard” (8-space) tabs are used. Free the return value with [method@Pango.TabArray.free]. copy of default tab array, or %NULL if standard tabs are used; must be freed with [method@Pango.TabArray.free]. a `GtkTextView` Gets the top margin for text in the @text_view. top margin in pixels a `GtkTextView` Fills @visible_rect with the currently-visible region of the buffer, in buffer coordinates. Convert to window coordinates with [method@Gtk.TextView.buffer_to_window_coords]. a `GtkTextView` rectangle to fill Gets the line wrapping for the view. the line wrap setting a `GtkTextView` Allow the `GtkTextView` input method to internally handle key press and release events. If this function returns %TRUE, then no further processing should be done for this key event. See [method@Gtk.IMContext.filter_keypress]. Note that you are expected to call this function from your handler when overriding key event handling. This is needed in the case when you need to insert your own key handling between the input method and the default key event handling of the `GtkTextView`. ```c static gboolean gtk_foo_bar_key_press_event (GtkWidget *widget, GdkEvent *event) { guint keyval; gdk_event_get_keyval ((GdkEvent*)event, &keyval); if (keyval == GDK_KEY_Return || keyval == GDK_KEY_KP_Enter) { if (gtk_text_view_im_context_filter_keypress (GTK_TEXT_VIEW (widget), event)) return TRUE; } // Do some stuff return GTK_WIDGET_CLASS (gtk_foo_bar_parent_class)->key_press_event (widget, event); } ``` %TRUE if the input method handled the key event. a `GtkTextView` the key event Moves a mark within the buffer so that it's located within the currently-visible text area. %TRUE if the mark moved (wasn’t already onscreen) a `GtkTextView` a `GtkTextMark` Updates the position of a child. See [method@Gtk.TextView.add_overlay]. a `GtkTextView` a widget already added with [method@Gtk.TextView.add_overlay] new X position in buffer coordinates new Y position in buffer coordinates Move the iterator a given number of characters visually, treating it as the strong cursor position. If @count is positive, then the new strong cursor position will be @count positions to the right of the old cursor position. If @count is negative then the new strong cursor position will be @count positions to the left of the old cursor position. In the presence of bi-directional text, the correspondence between logical and visual order will depend on the direction of the current run, and there may be jumps when the cursor is moved off of the end of a run. %TRUE if @iter moved and is not on the end iterator a `GtkTextView` a `GtkTextIter` number of characters to move (negative moves left, positive moves right) Moves the cursor to the currently visible region of the buffer. %TRUE if the cursor had to be moved. a `GtkTextView` Removes a child widget from @text_view. a `GtkTextView` the child to remove Ensures that the cursor is shown. This also resets the time that it will stay blinking (or visible, in case blinking is disabled). This function should be called in response to user input (e.g. from derived classes that override the textview's event handlers). a `GtkTextView` Reset the input method context of the text view if needed. This can be necessary in the case where modifying the buffer would confuse on-going input method behavior. a `GtkTextView` Scrolls @text_view the minimum distance such that @mark is contained within the visible area of the widget. a `GtkTextView` a mark in the buffer for @text_view Scrolls @text_view so that @iter is on the screen in the position indicated by @xalign and @yalign. An alignment of 0.0 indicates left or top, 1.0 indicates right or bottom, 0.5 means center. If @use_align is %FALSE, the text scrolls the minimal distance to get the mark onscreen, possibly not scrolling at all. The effective screen for purposes of this function is reduced by a margin of size @within_margin. Note that this function uses the currently-computed height of the lines in the text buffer. Line heights are computed in an idle handler; so this function may not have the desired effect if it’s called before the height computations. To avoid oddness, consider using [method@Gtk.TextView.scroll_to_mark] which saves a point to be scrolled to after line validation. %TRUE if scrolling occurred a `GtkTextView` a `GtkTextIter` margin as a [0.0,0.5) fraction of screen size whether to use alignment arguments (if %FALSE, just get the mark onscreen) horizontal alignment of mark within visible area vertical alignment of mark within visible area Scrolls @text_view so that @mark is on the screen in the position indicated by @xalign and @yalign. An alignment of 0.0 indicates left or top, 1.0 indicates right or bottom, 0.5 means center. If @use_align is %FALSE, the text scrolls the minimal distance to get the mark onscreen, possibly not scrolling at all. The effective screen for purposes of this function is reduced by a margin of size @within_margin. a `GtkTextView` a `GtkTextMark` margin as a [0.0,0.5) fraction of screen size whether to use alignment arguments (if %FALSE, just get the mark onscreen) horizontal alignment of mark within visible area vertical alignment of mark within visible area Sets the behavior of the text widget when the <kbd>Tab</kbd> key is pressed. If @accepts_tab is %TRUE, a tab character is inserted. If @accepts_tab is %FALSE the keyboard focus is moved to the next widget in the focus chain. Focus can always be moved using <kbd>Ctrl</kbd>+<kbd>Tab</kbd>. A `GtkTextView` %TRUE if pressing the Tab key should insert a tab character, %FALSE, if pressing the Tab key should move the keyboard focus. Sets the bottom margin for text in @text_view. Note that this function is confusingly named. In CSS terms, the value set here is padding. a `GtkTextView` bottom margin in pixels Sets @buffer as the buffer being displayed by @text_view. The previous buffer displayed by the text view is unreferenced, and a reference is added to @buffer. If you owned a reference to @buffer before passing it to this function, you must remove that reference yourself; `GtkTextView` will not “adopt” it. a `GtkTextView` a `GtkTextBuffer` Toggles whether the insertion point should be displayed. A buffer with no editable text probably shouldn’t have a visible cursor, so you may want to turn the cursor off. Note that this property may be overridden by the [property@Gtk.Settings:gtk-keynav-use-caret] setting. a `GtkTextView` whether to show the insertion cursor Sets the default editability of the `GtkTextView`. You can override this default setting with tags in the buffer, using the “editable” attribute of tags. a `GtkTextView` whether it’s editable Sets a menu model to add when constructing the context menu for @text_view. You can pass %NULL to remove a previously set extra menu. a `GtkTextView` a `GMenuModel` Places @widget into the gutter specified by @win. @win must be one of %GTK_TEXT_WINDOW_LEFT, %GTK_TEXT_WINDOW_RIGHT, %GTK_TEXT_WINDOW_TOP, or %GTK_TEXT_WINDOW_BOTTOM. a `GtkTextView` a `GtkTextWindowType` a `GtkWidget` Sets the default indentation for paragraphs in @text_view. Tags in the buffer may override the default. a `GtkTextView` indentation in pixels Sets the `input-hints` of the `GtkTextView`. The `input-hints` allow input methods to fine-tune their behaviour. a `GtkTextView` the hints Sets the `input-purpose` of the `GtkTextView`. The `input-purpose` can be used by on-screen keyboards and other input methods to adjust their behaviour. a `GtkTextView` the purpose Sets the default justification of text in @text_view. Tags in the view’s buffer may override the default. a `GtkTextView` justification Sets the default left margin for text in @text_view. Tags in the buffer may override the default. Note that this function is confusingly named. In CSS terms, the value set here is padding. a `GtkTextView` left margin in pixels Sets whether the `GtkTextView` should display text in monospace styling. a `GtkTextView` %TRUE to request monospace styling Changes the `GtkTextView` overwrite mode. a `GtkTextView` %TRUE to turn on overwrite mode, %FALSE to turn it off Sets the default number of blank pixels above paragraphs in @text_view. Tags in the buffer for @text_view may override the defaults. a `GtkTextView` pixels above paragraphs Sets the default number of pixels of blank space to put below paragraphs in @text_view. May be overridden by tags applied to @text_view’s buffer. a `GtkTextView` pixels below paragraphs Sets the default number of pixels of blank space to leave between display/wrapped lines within a paragraph. May be overridden by tags in @text_view’s buffer. a `GtkTextView` default number of pixels between wrapped lines Sets the default right margin for text in the text view. Tags in the buffer may override the default. Note that this function is confusingly named. In CSS terms, the value set here is padding. a `GtkTextView` right margin in pixels Sets the default tab stops for paragraphs in @text_view. Tags in the buffer may override the default. a `GtkTextView` tabs as a `PangoTabArray` Sets the top margin for text in @text_view. Note that this function is confusingly named. In CSS terms, the value set here is padding. a `GtkTextView` top margin in pixels Sets the line wrapping for the view. a `GtkTextView` a `GtkWrapMode` Determines whether @iter is at the start of a display line. See [method@Gtk.TextView.forward_display_line] for an explanation of display lines vs. paragraphs. %TRUE if @iter begins a wrapped line a `GtkTextView` a `GtkTextIter` Converts coordinates on the window identified by @win to buffer coordinates. a `GtkTextView` a `GtkTextWindowType` window x coordinate window y coordinate buffer x coordinate return location buffer y coordinate return location Whether Tab will result in a tab character being entered. The bottom margin for text in the text view. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Don't confuse this property with [property@Gtk.Widget:margin-bottom]. The buffer which is displayed. If the insertion cursor is shown. Whether the text can be modified by the user. A menu model whose contents will be appended to the context menu. Which IM (input method) module should be used for this text_view. See [class@Gtk.IMMulticontext]. Setting this to a non-%NULL value overrides the system-wide IM module setting. See the GtkSettings [property@Gtk.Settings:gtk-im-module] property. Amount to indent the paragraph, in pixels. A negative value of indent will produce a hanging indentation. That is, the first line will have the full width, and subsequent lines will be indented by the absolute value of indent. Additional hints (beyond [property@Gtk.TextView:input-purpose]) that allow input methods to fine-tune their behaviour. The purpose of this text field. This property can be used by on-screen keyboards and other input methods to adjust their behaviour. Left, right, or center justification. The default left margin for text in the text view. Tags in the buffer may override the default. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Whether text should be displayed in a monospace font. If %TRUE, set the .monospace style class on the text view to indicate that a monospace font is desired. Whether entered text overwrites existing contents. Pixels of blank space above paragraphs. Pixels of blank space below paragraphs. Pixels of blank space between wrapped lines in a paragraph. The default right margin for text in the text view. Tags in the buffer may override the default. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Custom tabs for this text. The top margin for text in the text view. Note that this property is confusingly named. In CSS terms, the value set here is padding, and it is applied in addition to the padding from the theme. Don't confuse this property with [property@Gtk.Widget:margin-top]. Whether to wrap lines never, at word boundaries, or at character boundaries. Gets emitted when the user asks for it. The ::backspace signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Backspace</kbd> and <kbd>Shift</kbd>+<kbd>Backspace</kbd>. Gets emitted to copy the selection to the clipboard. The ::copy-clipboard signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>c</kbd> and <kbd>Ctrl</kbd>+<kbd>Insert</kbd>. Gets emitted to cut the selection to the clipboard. The ::cut-clipboard signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>x</kbd> and <kbd>Shift</kbd>+<kbd>Delete</kbd>. Gets emitted when the user initiates a text deletion. The ::delete-from-cursor signal is a [keybinding signal](class.SignalAction.html). If the @type is %GTK_DELETE_CHARS, GTK deletes the selection if there is one, otherwise it deletes the requested number of characters. The default bindings for this signal are <kbd>Delete</kbd> for deleting a character, <kbd>Ctrl</kbd>+<kbd>Delete</kbd> for deleting a word and <kbd>Ctrl</kbd>+<kbd>Backspace</kbd> for deleting a word backwards. the granularity of the deletion, as a `GtkDeleteType` the number of @type units to delete Emitted when the selection needs to be extended at @location. %GDK_EVENT_STOP to stop other handlers from being invoked for the event. %GDK_EVENT_PROPAGATE to propagate the event further. the granularity type the location where to extend the selection where the selection should start where the selection should end Gets emitted when the user initiates the insertion of a fixed string at the cursor. The ::insert-at-cursor signal is a [keybinding signal](class.SignalAction.html). This signal has no default bindings. the string to insert Gets emitted to present the Emoji chooser for the @text_view. The ::insert-emoji signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>.</kbd> and <kbd>Ctrl</kbd>+<kbd>;</kbd> Gets emitted when the user initiates a cursor movement. The ::move-cursor signal is a [keybinding signal](class.SignalAction.html). If the cursor is not visible in @text_view, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. The default bindings for this signal come in two variants, the variant with the <kbd>Shift</kbd> modifier extends the selection, the variant without it does not. There are too many key combinations to list them all here. - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd> move by individual characters/lines - <kbd>Ctrl</kbd>+<kbd>←</kbd>, etc. move by words/paragraphs - <kbd>Home</kbd> and <kbd>End</kbd> move to the ends of the buffer - <kbd>PgUp</kbd> and <kbd>PgDn</kbd> move vertically by pages - <kbd>Ctrl</kbd>+<kbd>PgUp</kbd> and <kbd>Ctrl</kbd>+<kbd>PgDn</kbd> move horizontally by pages the granularity of the move, as a `GtkMovementStep` the number of @step units to move %TRUE if the move should extend the selection Gets emitted to move the viewport. The ::move-viewport signal is a [keybinding signal](class.SignalAction.html), which can be bound to key combinations to allow the user to move the viewport, i.e. change what part of the text view is visible in a containing scrolled window. There are no default bindings for this signal. the granularity of the movement, as a `GtkScrollStep` the number of @step units to move Gets emitted to paste the contents of the clipboard into the text view. The ::paste-clipboard signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>v</kbd> and <kbd>Shift</kbd>+<kbd>Insert</kbd>. Emitted when preedit text of the active IM changes. If an input method is used, the typed text will not immediately be committed to the buffer. So if you are interested in the text, connect to this signal. This signal is only emitted if the text at the given position is actually editable. the current preedit string Gets emitted to select or unselect the complete contents of the text view. The ::select-all signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>a</kbd> and <kbd>Ctrl</kbd>+<kbd>/</kbd> for selecting and <kbd>Shift</kbd>+<kbd>Ctrl</kbd>+<kbd>a</kbd> and <kbd>Ctrl</kbd>+<kbd>\</kbd> for unselecting. %TRUE to select, %FALSE to unselect Gets emitted when the user initiates settings the "anchor" mark. The ::set-anchor signal is a [keybinding signal](class.SignalAction.html) which gets emitted when the user initiates setting the "anchor" mark. The "anchor" mark gets placed at the same position as the "insert" mark. This signal has no default bindings. Gets emitted to toggle the `cursor-visible` property. The ::toggle-cursor-visible signal is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>F7</kbd>. Gets emitted to toggle the overwrite mode of the text view. The ::toggle-overwrite signal is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Insert</kbd>. The object class structure needs to be the first The class handler for the `GtkTextView::move-cursor` keybinding signal. The class handler for the `GtkTextView::set-anchor` keybinding signal. The class handler for the `GtkTextView::insert-at-cursor` keybinding signal. The class handler for the `GtkTextView::delete-from-cursor` keybinding signal. The class handler for the `GtkTextView::backspace` keybinding signal. The class handler for the `GtkTextView::cut-clipboard` keybinding signal The class handler for the `GtkTextView::copy-clipboard` keybinding signal. The class handler for the `GtkTextView::paste-clipboard` keybinding signal. The class handler for the `GtkTextView::toggle-overwrite` keybinding signal. The create_buffer vfunc is called to create a `GtkTextBuffer` for the text view. The default implementation is to just call gtk_text_buffer_new(). The snapshot_layer vfunc is called before and after the text view is drawing its own text. Applications can override this vfunc in a subclass to draw customized content underneath or above the text. In the %GTK_TEXT_VIEW_LAYER_BELOW_TEXT and %GTK_TEXT_VIEW_LAYER_ABOVE_TEXT layers the drawing is done in the buffer coordinate space. The class handler for the `GtkTextView::extend-selection` signal. The class handler for the `GtkTextView::insert-emoji` signal. Used to reference the layers of `GtkTextView` for the purpose of customized drawing with the ::snapshot_layer vfunc. The layer rendered below the text (but above the background). The layer rendered above the text. Used to reference the parts of `GtkTextView`. Window that floats over scrolling areas. Scrollable text window. Left side border window. Right side border window. Top border window. Bottom border window. Callback type for adding a function to update animations. See gtk_widget_add_tick_callback(). %G_SOURCE_CONTINUE if the tick callback should continue to be called, %G_SOURCE_REMOVE if the tick callback should be removed. the widget the frame clock for the widget (same as calling gtk_widget_get_frame_clock()) user data passed to gtk_widget_add_tick_callback(). A `GtkToggleButton` is a button which remains “pressed-in” when clicked. Clicking again will cause the toggle button to return to its normal state. A toggle button is created by calling either [ctor@Gtk.ToggleButton.new] or [ctor@Gtk.ToggleButton.new_with_label]. If using the former, it is advisable to pack a widget, (such as a `GtkLabel` and/or a `GtkImage`), into the toggle button’s container. (See [class@Gtk.Button] for more information). The state of a `GtkToggleButton` can be set specifically using [method@Gtk.ToggleButton.set_active], and retrieved using [method@Gtk.ToggleButton.get_active]. To simply switch the state of a toggle button, use [method@Gtk.ToggleButton.toggled]. ## Grouping Toggle buttons can be grouped together, to form mutually exclusive groups - only one of the buttons can be toggled at a time, and toggling another one will switch the currently toggled one off. To add a `GtkToggleButton` to a group, use [method@Gtk.ToggleButton.set_group]. ## CSS nodes `GtkToggleButton` has a single CSS node with name button. To differentiate it from a plain `GtkButton`, it gets the `.toggle` style class. ## Accessibility `GtkToggleButton` uses the %GTK_ACCESSIBLE_ROLE_TOGGLE_BUTTON role. ## Creating two `GtkToggleButton` widgets. ```c static void output_state (GtkToggleButton *source, gpointer user_data) { g_print ("Toggle button "%s" is active: %s", gtk_button_get_label (GTK_BUTTON (source)), gtk_toggle_button_get_active (source) ? "Yes" : "No"); } static void make_toggles (void) { GtkWidget *window, *toggle1, *toggle2; GtkWidget *box; const char *text; window = gtk_window_new (); box = gtk_box_new (GTK_ORIENTATION_VERTICAL, 12); text = "Hi, I’m toggle button one"; toggle1 = gtk_toggle_button_new_with_label (text); g_signal_connect (toggle1, "toggled", G_CALLBACK (output_state), NULL); gtk_box_append (GTK_BOX (box), toggle1); text = "Hi, I’m toggle button two"; toggle2 = gtk_toggle_button_new_with_label (text); g_signal_connect (toggle2, "toggled", G_CALLBACK (output_state), NULL); gtk_box_append (GTK_BOX (box), toggle2); gtk_window_set_child (GTK_WINDOW (window), box); gtk_window_present (GTK_WINDOW (window)); } ``` Creates a new toggle button. A widget should be packed into the button, as in [ctor@Gtk.Button.new]. a new toggle button. Creates a new toggle button with a text label. a new toggle button. a string containing the message to be placed in the toggle button. Creates a new `GtkToggleButton` containing a label. The label will be created using [ctor@Gtk.Label.new_with_mnemonic], so underscores in @label indicate the mnemonic for the button. a new `GtkToggleButton` the text of the button, with an underscore in front of the mnemonic character Emits the ::toggled signal on the `GtkToggleButton`. There is no good reason for an application ever to call this function. a `GtkToggleButton`. Queries a `GtkToggleButton` and returns its current state. Returns %TRUE if the toggle button is pressed in and %FALSE if it is raised. whether the button is pressed a `GtkToggleButton`. Sets the status of the toggle button. Set to %TRUE if you want the `GtkToggleButton` to be “pressed in”, and %FALSE to raise it. If the status of the button changes, this action causes the [signal@Gtk.ToggleButton::toggled] signal to be emitted. a `GtkToggleButton`. %TRUE or %FALSE. Adds @self to the group of @group. In a group of multiple toggle buttons, only one button can be active at a time. Setting up groups in a cycle leads to undefined behavior. Note that the same effect can be achieved via the [iface@Gtk.Actionable] API, by using the same action with parameter type and state type 's' for all buttons in the group, and giving each button its own target value. a `GtkToggleButton` another `GtkToggleButton` to form a group with Emits the ::toggled signal on the `GtkToggleButton`. There is no good reason for an application ever to call this function. a `GtkToggleButton`. If the toggle button should be pressed in. The toggle button whose group this widget belongs to. Emitted whenever the `GtkToggleButton`'s state is changed. a `GtkToggleButton`. `GtkTooltip` is an object representing a widget tooltip. Basic tooltips can be realized simply by using [method@Gtk.Widget.set_tooltip_text] or [method@Gtk.Widget.set_tooltip_markup] without any explicit tooltip object. When you need a tooltip with a little more fancy contents, like adding an image, or you want the tooltip to have different contents per `GtkTreeView` row or cell, you will have to do a little more work: - Set the [property@Gtk.Widget:has-tooltip] property to %TRUE. This will make GTK monitor the widget for motion and related events which are needed to determine when and where to show a tooltip. - Connect to the [signal@Gtk.Widget::query-tooltip] signal. This signal will be emitted when a tooltip is supposed to be shown. One of the arguments passed to the signal handler is a `GtkTooltip` object. This is the object that we are about to display as a tooltip, and can be manipulated in your callback using functions like [method@Gtk.Tooltip.set_icon]. There are functions for setting the tooltip’s markup, setting an image from a named icon, or even putting in a custom widget. - Return %TRUE from your ::query-tooltip handler. This causes the tooltip to be show. If you return %FALSE, it will not be shown. Replaces the widget packed into the tooltip with @custom_widget. @custom_widget does not get destroyed when the tooltip goes away. By default a box with a `GtkImage` and `GtkLabel` is embedded in the tooltip, which can be configured using gtk_tooltip_set_markup() and gtk_tooltip_set_icon(). a `GtkTooltip` a `GtkWidget`, or %NULL to unset the old custom widget. Sets the icon of the tooltip (which is in front of the text) to be @paintable. If @paintable is %NULL, the image will be hidden. a `GtkTooltip` a `GdkPaintable` Sets the icon of the tooltip (which is in front of the text) to be the icon indicated by @gicon with the size indicated by @size. If @gicon is %NULL, the image will be hidden. a `GtkTooltip` a `GIcon` representing the icon Sets the icon of the tooltip (which is in front of the text) to be the icon indicated by @icon_name with the size indicated by @size. If @icon_name is %NULL, the image will be hidden. a `GtkTooltip` an icon name Sets the text of the tooltip to be @markup. The string must be marked up with Pango markup. If @markup is %NULL, the label will be hidden. a `GtkTooltip` a string with Pango markup or %NLL Sets the text of the tooltip to be @text. If @text is %NULL, the label will be hidden. See also [method@Gtk.Tooltip.set_markup]. a `GtkTooltip` a text string Sets the area of the widget, where the contents of this tooltip apply, to be @rect (in widget coordinates). This is especially useful for properly setting tooltips on `GtkTreeView` rows and cells, `GtkIconViews`, etc. For setting tooltips on `GtkTreeView`, please refer to the convenience functions for this: gtk_tree_view_set_tooltip_row() and gtk_tree_view_set_tooltip_cell(). a `GtkTooltip` a `GdkRectangle` A function to set the properties of a cell instead of just using the straight mapping between the cell and the model. This function is useful for customizing the cell renderer. For example, a function might get an* integer from the @tree_model, and render it to the “text” attribute of “cell” by converting it to its written equivalent. See also: gtk_tree_view_column_set_cell_data_func() A `GtkTreeViewColumn` The `GtkCellRenderer` that is being rendered by @tree_column The `GtkTreeModel` being rendered A `GtkTreeIter` of the current row rendered user data Interface for Drag-and-Drop destinations in `GtkTreeView`. List views use widgets to display their contents. You can use [class@Gtk.DropTarget] to implement a drop destination Asks the `GtkTreeDragDest` to insert a row before the path @dest, deriving the contents of the row from @value. If @dest is outside the tree so that inserting before it is impossible, %FALSE will be returned. Also, %FALSE may be returned if the new row is not created for some model-specific reason. Should robustly handle a @dest no longer found in the model! Use list models instead whether a new row was created before position @dest a `GtkTreeDragDest` row to drop in front of data to drop Determines whether a drop is possible before the given @dest_path, at the same depth as @dest_path. i.e., can we drop the data in @value at that location. @dest_path does not have to exist; the return value will almost certainly be %FALSE if the parent of @dest_path doesn’t exist, though. Use list models instead %TRUE if a drop is possible before @dest_path a `GtkTreeDragDest` destination row the data being dropped Asks the `GtkTreeDragDest` to insert a row before the path @dest, deriving the contents of the row from @value. If @dest is outside the tree so that inserting before it is impossible, %FALSE will be returned. Also, %FALSE may be returned if the new row is not created for some model-specific reason. Should robustly handle a @dest no longer found in the model! Use list models instead whether a new row was created before position @dest a `GtkTreeDragDest` row to drop in front of data to drop Determines whether a drop is possible before the given @dest_path, at the same depth as @dest_path. i.e., can we drop the data in @value at that location. @dest_path does not have to exist; the return value will almost certainly be %FALSE if the parent of @dest_path doesn’t exist, though. Use list models instead %TRUE if a drop is possible before @dest_path a `GtkTreeDragDest` destination row the data being dropped Asks the `GtkTreeDragDest` to insert a row before the path dest, deriving the contents of the row from selection_data. whether a new row was created before position @dest a `GtkTreeDragDest` row to drop in front of data to drop Determines whether a drop is possible before the given dest_path, at the same depth as dest_path. %TRUE if a drop is possible before @dest_path a `GtkTreeDragDest` destination row the data being dropped Interface for Drag-and-Drop destinations in `GtkTreeView`. List views use widgets to display their contents. You can use [class@Gtk.DragSource] to implement a drag source Asks the `GtkTreeDragSource` to delete the row at @path, because it was moved somewhere else via drag-and-drop. Returns %FALSE if the deletion fails because @path no longer exists, or for some model-specific reason. Should robustly handle a @path no longer found in the model! Use list models instead %TRUE if the row was successfully deleted a `GtkTreeDragSource` row that was being dragged Asks the `GtkTreeDragSource` to return a `GdkContentProvider` representing the row at @path. Should robustly handle a @path no longer found in the model! Use list models instead a `GdkContentProvider` for the given @path a `GtkTreeDragSource` row that was dragged Asks the `GtkTreeDragSource` whether a particular row can be used as the source of a DND operation. If the source doesn’t implement this interface, the row is assumed draggable. Use list models instead %TRUE if the row can be dragged a `GtkTreeDragSource` row on which user is initiating a drag Asks the `GtkTreeDragSource` to delete the row at @path, because it was moved somewhere else via drag-and-drop. Returns %FALSE if the deletion fails because @path no longer exists, or for some model-specific reason. Should robustly handle a @path no longer found in the model! Use list models instead %TRUE if the row was successfully deleted a `GtkTreeDragSource` row that was being dragged Asks the `GtkTreeDragSource` to return a `GdkContentProvider` representing the row at @path. Should robustly handle a @path no longer found in the model! Use list models instead a `GdkContentProvider` for the given @path a `GtkTreeDragSource` row that was dragged Asks the `GtkTreeDragSource` whether a particular row can be used as the source of a DND operation. If the source doesn’t implement this interface, the row is assumed draggable. Use list models instead %TRUE if the row can be dragged a `GtkTreeDragSource` row on which user is initiating a drag Asks the `GtkTreeDragSource` whether a particular row can be used as the source of a DND operation. %TRUE if the row can be dragged a `GtkTreeDragSource` row on which user is initiating a drag Asks the `GtkTreeDragSource` to fill in selection_data with a representation of the row at path. a `GdkContentProvider` for the given @path a `GtkTreeDragSource` row that was dragged Asks the `GtkTreeDragSource` to delete the row at path, because it was moved somewhere else via drag-and-drop. %TRUE if the row was successfully deleted a `GtkTreeDragSource` row that was being dragged `GtkTreeExpander` is a widget that provides an expander for a list. It is typically placed as a bottommost child into a `GtkListView` to allow users to expand and collapse children in a list with a [class@Gtk.TreeListModel]. `GtkTreeExpander` provides the common UI elements, gestures and keybindings for this purpose. On top of this, the "listitem.expand", "listitem.collapse" and "listitem.toggle-expand" actions are provided to allow adding custom UI for managing expanded state. It is important to mention that you want to set the [property@Gtk.ListItem:focusable] property to FALSE when using this widget, as you want the keyboard focus to be in the treexpander, and not inside the list to make use of the keybindings. The `GtkTreeListModel` must be set to not be passthrough. Then it will provide [class@Gtk.TreeListRow] items which can be set via [method@Gtk.TreeExpander.set_list_row] on the expander. The expander will then watch that row item automatically. [method@Gtk.TreeExpander.set_child] sets the widget that displays the actual row contents. `GtkTreeExpander` can be modified with properties such as [property@Gtk.TreeExpander:indent-for-icon], [property@Gtk.TreeExpander:indent-for-depth], and [property@Gtk.TreeExpander:hide-expander] to achieve a different appearance. This can even be done to influence individual rows, for example by binding the [property@Gtk.TreeExpander:hide-expander] property to the item count of the model of the treelistrow, to hide the expander for rows without children, even if the row is expandable. ## Shortcuts and Gestures `GtkTreeExpander` supports the following keyboard shortcuts: - <kbd>+</kbd> or <kbd>*</kbd> expands the expander. - <kbd>-</kbd> or <kbd>/</kbd> collapses the expander. - Left and right arrow keys, when combined with <kbd>Shift</kbd> or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>, will expand or collapse, depending on the locale's text direction. - <kbd>Ctrl</kbd>+<kbd>␣</kbd> toggles the expander state. The row can also expand on drag gestures. ## Actions `GtkTreeExpander` defines a set of built-in actions: - `listitem.expand` expands the expander if it can be expanded. - `listitem.collapse` collapses the expander. - `listitem.toggle-expand` tries to expand the expander if it was collapsed or collapses it if it was expanded. ## CSS nodes ``` treeexpander ├── [indent]* ├── [expander] ╰── <child> ``` `GtkTreeExpander` has zero or one CSS nodes with the name "expander" that should display the expander icon. The node will be `:checked` when it is expanded. If the node is not expandable, an "indent" node will be displayed instead. For every level of depth, another "indent" node is prepended. ## Accessibility Until GTK 4.10, `GtkTreeExpander` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. Since GTK 4.12, `GtkTreeExpander` uses the `GTK_ACCESSIBLE_ROLE_BUTTON` role. Toggling it will change the `GTK_ACCESSIBLE_STATE_EXPANDED` state. Creates a new `GtkTreeExpander` a new `GtkTreeExpander` Gets the child widget displayed by @self. The child displayed by @self a `GtkTreeExpander` Gets whether the TreeExpander should be hidden in a GtkTreeListRow. TRUE if the expander icon should be hidden. Otherwise FALSE. a `GtkTreeExpander` TreeExpander indents each level of depth with an additional indent. TRUE if the child should be indented . Otherwise FALSE. a `GtkTreeExpander` TreeExpander indents the child by the width of an expander-icon if it is not expandable. TRUE if the child should be indented when not expandable. Otherwise FALSE. a `GtkTreeExpander` Forwards the item set on the `GtkTreeListRow` that @self is managing. This call is essentially equivalent to calling: ```c gtk_tree_list_row_get_item (gtk_tree_expander_get_list_row (@self)); ``` The item of the row a `GtkTreeExpander` Gets the list row managed by @self. The list row displayed by @self a `GtkTreeExpander` Sets the content widget to display. a `GtkTreeExpander` a `GtkWidget` Sets whether the expander icon should be visible in a GtkTreeListRow. a `GtkTreeExpander` widget TRUE if the expander should be hidden. Otherwise FALSE. Sets if the TreeExpander should indent the child according to its depth. a `GtkTreeExpander` widget TRUE if the child should be indented. Otherwise FALSE. Sets if the TreeExpander should indent the child by the width of an expander-icon when it is not expandable. a `GtkTreeExpander` widget TRUE if the child should be indented without expander. Otherwise FALSE. Sets the tree list row that this expander should manage. a `GtkTreeExpander` widget a `GtkTreeListRow` The child widget with the actual contents. Whether the expander icon should be hidden in a GtkTreeListRow. Note that this property simply hides the icon. The actions and keybinding (i.e. collapse and expand) are not affected by this property. A common use for this property would be to bind to the number of children in a GtkTreeListRow's model in order to hide the expander when a row has no children. TreeExpander indents the child according to its depth. TreeExpander indents the child by the width of an expander-icon if it is not expandable. The item held by this expander's row. The list row to track for expander state. The `GtkTreeIter` is the primary structure for accessing a `GtkTreeModel`. Models are expected to put a unique integer in the @stamp member, and put model-specific data in the three @user_data members. a unique stamp to catch invalid iterators model-specific data model-specific data model-specific data Creates a dynamically allocated tree iterator as a copy of @iter. This function is not intended for use in applications, because you can just copy the structs by value (`GtkTreeIter new_iter = iter;`). You must free this iter with gtk_tree_iter_free(). a newly-allocated copy of @iter a `GtkTreeIter` Frees an iterator that has been allocated by gtk_tree_iter_copy(). This function is mainly used for language bindings. a dynamically allocated tree iterator A GtkTreeIterCompareFunc should return a negative integer, zero, or a positive integer if @a sorts before @b, @a sorts with @b, or @a sorts after @b respectively. If two iters compare as equal, their order in the sorted model is undefined. In order to ensure that the `GtkTreeSortable` behaves as expected, the GtkTreeIterCompareFunc must define a partial order on the model, i.e. it must be reflexive, antisymmetric and transitive. For example, if @model is a product catalogue, then a compare function for the “price” column could be one which returns `price_of(@a) - price_of(@b)`. a negative integer, zero or a positive integer depending on whether @a sorts before, with or after @b The `GtkTreeModel` the comparison is within A `GtkTreeIter` in @model Another `GtkTreeIter` in @model Data passed when the compare func is assigned e.g. by gtk_tree_sortable_set_sort_func() `GtkTreeListModel` is a list model that can create child models on demand. Creates a new empty `GtkTreeListModel` displaying @root with all rows collapsed. a newly created `GtkTreeListModel`. The `GListModel` to use as root %TRUE to pass through items from the models %TRUE to set the autoexpand property and expand the @root model function to call to create the `GListModel` for the children of an item Data to pass to @create_func Function to call to free @user_data Gets whether the model is set to automatically expand new rows that get added. This can be either rows added by changes to the underlying models or via [method@Gtk.TreeListRow.set_expanded]. %TRUE if the model is set to autoexpand a `GtkTreeListModel` Gets the row item corresponding to the child at index @position for @self's root model. If @position is greater than the number of children in the root model, %NULL is returned. Do not confuse this function with [method@Gtk.TreeListModel.get_row]. the child in @position a `GtkTreeListModel` position of the child to get Gets the root model that @self was created with. the root model a `GtkTreeListModel` Gets whether the model is passing through original row items. If this function returns %FALSE, the `GListModel` functions for @self return custom `GtkTreeListRow` objects. You need to call [method@Gtk.TreeListRow.get_item] on these objects to get the original item. If %TRUE, the values of the child models are passed through in their original state. You then need to call [method@Gtk.TreeListModel.get_row] to get the custom `GtkTreeListRow`s. %TRUE if the model is passing through original row items a `GtkTreeListModel` Gets the row object for the given row. If @position is greater than the number of items in @self, %NULL is returned. The row object can be used to expand and collapse rows as well as to inspect its position in the tree. See its documentation for details. This row object is persistent and will refer to the current item as long as the row is present in @self, independent of other rows being added or removed. If @self is set to not be passthrough, this function is equivalent to calling g_list_model_get_item(). Do not confuse this function with [method@Gtk.TreeListModel.get_child_row]. The row item a `GtkTreeListModel` the position of the row to fetch Sets whether the model should autoexpand. If set to %TRUE, the model will recursively expand all rows that get added to the model. This can be either rows added by changes to the underlying models or via [method@Gtk.TreeListRow.set_expanded]. a `GtkTreeListModel` %TRUE to make the model autoexpand its rows If all rows should be expanded by default. The type of items. See [method@Gio.ListModel.get_item_type]. The root model displayed. The number of items. See [method@Gio.ListModel.get_n_items]. Gets whether the model is in passthrough mode. If %FALSE, the `GListModel` functions for this object return custom [class@Gtk.TreeListRow] objects. If %TRUE, the values of the child models are pass through unmodified. Prototype of the function called to create new child models when gtk_tree_list_row_set_expanded() is called. This function can return %NULL to indicate that @item is guaranteed to be a leaf node and will never have children. If it does not have children but may get children later, it should return an empty model that is filled once children arrive. The model tracking the children of @item or %NULL if @item can never have children The item that is being expanded User data passed when registering the function `GtkTreeListRow` is used by `GtkTreeListModel` to represent items. It allows navigating the model as a tree and modify the state of rows. `GtkTreeListRow` instances are created by a `GtkTreeListModel` only when the [property@Gtk.TreeListModel:passthrough] property is not set. There are various support objects that can make use of `GtkTreeListRow` objects, such as the [class@Gtk.TreeExpander] widget that allows displaying an icon to expand or collapse a row or [class@Gtk.TreeListRowSorter] that makes it possible to sort trees properly. If @self is not expanded or @position is greater than the number of children, %NULL is returned. the child in @position a `GtkTreeListRow` position of the child to get If the row is expanded, gets the model holding the children of @self. This model is the model created by the [callback@Gtk.TreeListModelCreateModelFunc] and contains the original items, no matter what value [property@Gtk.TreeListModel:passthrough] is set to. The model containing the children a `GtkTreeListRow` Gets the depth of this row. Rows that correspond to items in the root model have a depth of zero, rows corresponding to items of models of direct children of the root model have a depth of 1 and so on. The depth of a row never changes until the row is removed from its model at which point it will forever return 0. The depth of this row a `GtkTreeListRow` Gets if a row is currently expanded. %TRUE if the row is expanded a `GtkTreeListRow` Gets the item corresponding to this row, The item of this row. This function is only marked as nullable for backwards compatibility reasons. a `GtkTreeListRow` Gets the row representing the parent for @self. That is the row that would need to be collapsed to make this row disappear. If @self is a row corresponding to the root model, %NULL is returned. The value returned by this function never changes until the row is removed from its model at which point it will forever return %NULL. The parent of @self a `GtkTreeListRow` Returns the position in the `GtkTreeListModel` that @self occupies at the moment. The position in the model a `GtkTreeListRow` Checks if a row can be expanded. This does not mean that the row is actually expanded, this can be checked with [method@Gtk.TreeListRow.get_expanded]. If a row is expandable never changes until the row is removed from its model at which point it will forever return %FALSE. %TRUE if the row is expandable a `GtkTreeListRow` Expands or collapses a row. If a row is expanded, the model of calling the [callback@Gtk.TreeListModelCreateModelFunc] for the row's item will be inserted after this row. If a row is collapsed, those items will be removed from the model. If the row is not expandable, this function does nothing. a `GtkTreeListRow` %TRUE if the row should be expanded The model holding the row's children. The depth in the tree of this row. If this row can ever be expanded. If this row is currently expanded. The item held in this row. `GtkTreeListRowSorter` is a special-purpose sorter that will apply a given sorter to the levels in a tree. Here is an example for setting up a column view with a tree model and a `GtkTreeListSorter`: ```c column_sorter = gtk_column_view_get_sorter (view); sorter = gtk_tree_list_row_sorter_new (g_object_ref (column_sorter)); sort_model = gtk_sort_list_model_new (tree_model, sorter); selection = gtk_single_selection_new (sort_model); gtk_column_view_set_model (view, G_LIST_MODEL (selection)); ``` Create a special-purpose sorter that applies the sorting of @sorter to the levels of a `GtkTreeListModel`. Note that this sorter relies on [property@Gtk.TreeListModel:passthrough] being %FALSE as it can only sort [class@Gtk.TreeListRow]s. a new `GtkTreeListRowSorter` a `GtkSorter` Returns the sorter used by @self. the sorter used a `GtkTreeListRowSorter` Sets the sorter to use for items with the same parent. This sorter will be passed the [property@Gtk.TreeListRow:item] of the tree list rows passed to @self. a `GtkTreeListRowSorter` The sorter to use The underlying sorter The tree interface used by GtkTreeView The `GtkTreeModel` interface defines a generic tree interface for use by the `GtkTreeView` widget. It is an abstract interface, and is designed to be usable with any appropriate data structure. The programmer just has to implement this interface on their own data type for it to be viewable by a `GtkTreeView` widget. The model is represented as a hierarchical tree of strongly-typed, columned data. In other words, the model can be seen as a tree where every node has different values depending on which column is being queried. The type of data found in a column is determined by using the GType system (ie. %G_TYPE_INT, %GTK_TYPE_BUTTON, %G_TYPE_POINTER, etc). The types are homogeneous per column across all nodes. It is important to note that this interface only provides a way of examining a model and observing changes. The implementation of each individual model decides how and if changes are made. In order to make life simpler for programmers who do not need to write their own specialized model, two generic models are provided — the `GtkTreeStore` and the `GtkListStore`. To use these, the developer simply pushes data into these models as necessary. These models provide the data structure as well as all appropriate tree interfaces. As a result, implementing drag and drop, sorting, and storing data is trivial. For the vast majority of trees and lists, these two models are sufficient. Models are accessed on a node/column level of granularity. One can query for the value of a model at a certain node and a certain column on that node. There are two structures used to reference a particular node in a model. They are the [struct@Gtk.TreePath] and the [struct@Gtk.TreeIter] (“iter” is short for iterator). Most of the interface consists of operations on a [struct@Gtk.TreeIter]. A path is essentially a potential node. It is a location on a model that may or may not actually correspond to a node on a specific model. A [struct@Gtk.TreePath] can be converted into either an array of unsigned integers or a string. The string form is a list of numbers separated by a colon. Each number refers to the offset at that level. Thus, the path `0` refers to the root node and the path `2:4` refers to the fifth child of the third node. By contrast, a [struct@Gtk.TreeIter] is a reference to a specific node on a specific model. It is a generic struct with an integer and three generic pointers. These are filled in by the model in a model-specific way. One can convert a path to an iterator by calling gtk_tree_model_get_iter(). These iterators are the primary way of accessing a model and are similar to the iterators used by `GtkTextBuffer`. They are generally statically allocated on the stack and only used for a short time. The model interface defines a set of operations using them for navigating the model. It is expected that models fill in the iterator with private data. For example, the `GtkListStore` model, which is internally a simple linked list, stores a list node in one of the pointers. The `GtkTreeModel`Sort stores an array and an offset in two of the pointers. Additionally, there is an integer field. This field is generally filled with a unique stamp per model. This stamp is for catching errors resulting from using invalid iterators with a model. The lifecycle of an iterator can be a little confusing at first. Iterators are expected to always be valid for as long as the model is unchanged (and doesn’t emit a signal). The model is considered to own all outstanding iterators and nothing needs to be done to free them from the user’s point of view. Additionally, some models guarantee that an iterator is valid for as long as the node it refers to is valid (most notably the `GtkTreeStore` and `GtkListStore`). Although generally uninteresting, as one always has to allow for the case where iterators do not persist beyond a signal, some very important performance enhancements were made in the sort model. As a result, the %GTK_TREE_MODEL_ITERS_PERSIST flag was added to indicate this behavior. To help show some common operation of a model, some examples are provided. The first example shows three ways of getting the iter at the location `3:2:5`. While the first method shown is easier, the second is much more common, as you often get paths from callbacks. ## Acquiring a `GtkTreeIter` ```c // Three ways of getting the iter pointing to the location GtkTreePath *path; GtkTreeIter iter; GtkTreeIter parent_iter; // get the iterator from a string gtk_tree_model_get_iter_from_string (model, &iter, "3:2:5"); // get the iterator from a path path = gtk_tree_path_new_from_string ("3:2:5"); gtk_tree_model_get_iter (model, &iter, path); gtk_tree_path_free (path); // walk the tree to find the iterator gtk_tree_model_iter_nth_child (model, &iter, NULL, 3); parent_iter = iter; gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 2); parent_iter = iter; gtk_tree_model_iter_nth_child (model, &iter, &parent_iter, 5); ``` This second example shows a quick way of iterating through a list and getting a string and an integer from each row. The populate_model() function used below is not shown, as it is specific to the `GtkListStore`. For information on how to write such a function, see the `GtkListStore` documentation. ## Reading data from a `GtkTreeModel` ```c enum { STRING_COLUMN, INT_COLUMN, N_COLUMNS }; ... GtkTreeModel *list_store; GtkTreeIter iter; gboolean valid; int row_count = 0; // make a new list_store list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT); // Fill the list store with data populate_model (list_store); // Get the first iter in the list, check it is valid and walk // through the list, reading each row. valid = gtk_tree_model_get_iter_first (list_store, &iter); while (valid) { char *str_data; int int_data; // Make sure you terminate calls to gtk_tree_model_get() with a “-1” value gtk_tree_model_get (list_store, &iter, STRING_COLUMN, &str_data, INT_COLUMN, &int_data, -1); // Do something with the data g_print ("Row %d: (%s,%d)\n", row_count, str_data, int_data); g_free (str_data); valid = gtk_tree_model_iter_next (list_store, &iter); row_count++; } ``` The `GtkTreeModel` interface contains two methods for reference counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node(). These two methods are optional to implement. The reference counting is meant as a way for views to let models know when nodes are being displayed. `GtkTreeView` will take a reference on a node when it is visible, which means the node is either in the toplevel or expanded. Being displayed does not mean that the node is currently directly visible to the user in the viewport. Based on this reference counting scheme a caching model, for example, can decide whether or not to cache a node based on the reference count. A file-system based model would not want to keep the entire file hierarchy in memory, but just the folders that are currently expanded in every current view. When working with reference counting, the following rules must be taken into account: - Never take a reference on a node without owning a reference on its parent. This means that all parent nodes of a referenced node must be referenced as well. - Outstanding references on a deleted node are not released. This is not possible because the node has already been deleted by the time the row-deleted signal is received. - Models are not obligated to emit a signal on rows of which none of its siblings are referenced. To phrase this differently, signals are only required for levels in which nodes are referenced. For the root level however, signals must be emitted at all times (however the root level is always referenced when any view is attached). Use [iface@Gio.ListModel] instead Returns the type of the column. the type of the column a `GtkTreeModel` the column index Returns a set of flags supported by this interface. The flags are a bitwise combination of `GtkTreeModel`Flags. The flags supported should not change during the lifetime of the @tree_model. the flags supported by this interface a `GtkTreeModel` Sets @iter to a valid iterator pointing to @path. If @path does not exist, @iter is set to an invalid iterator and %FALSE is returned. %TRUE, if @iter was set a `GtkTreeModel` the uninitialized `GtkTreeIter` the `GtkTreePath` Returns the number of columns supported by @tree_model. the number of columns a `GtkTreeModel` Returns a newly-created `GtkTreePath` referenced by @iter. This path should be freed with gtk_tree_path_free(). a newly-created `GtkTreePath` a `GtkTreeModel` the `GtkTreeIter` Initializes and sets @value to that at @column. When done with @value, g_value_unset() needs to be called to free any allocated memory. a `GtkTreeModel` the `GtkTreeIter` the column to lookup the value at an empty `GValue` to set Sets @iter to point to the first child of @parent. If @parent has no children, %FALSE is returned and @iter is set to be invalid. @parent will remain a valid node after this function has been called. If @parent is %NULL returns the first node, equivalent to `gtk_tree_model_get_iter_first (tree_model, iter);` %TRUE, if @iter has been set to the first child a `GtkTreeModel` the new `GtkTreeIter` to be set to the child the `GtkTreeIter` Returns %TRUE if @iter has children, %FALSE otherwise. %TRUE if @iter has children a `GtkTreeModel` the `GtkTreeIter` to test for children Returns the number of children that @iter has. As a special case, if @iter is %NULL, then the number of toplevel nodes is returned. the number of children of @iter a `GtkTreeModel` the `GtkTreeIter` Sets @iter to point to the node following it at the current level. If there is no next @iter, %FALSE is returned and @iter is set to be invalid. %TRUE if @iter has been changed to the next node a `GtkTreeModel` the `GtkTreeIter` Sets @iter to be the child of @parent, using the given index. The first index is 0. If @n is too big, or @parent has no children, @iter is set to an invalid iterator and %FALSE is returned. @parent will remain a valid node after this function has been called. As a special case, if @parent is %NULL, then the @n-th root node is set. %TRUE, if @parent has an @n-th child a `GtkTreeModel` the `GtkTreeIter` to set to the nth child the `GtkTreeIter` to get the child from the index of the desired child Sets @iter to be the parent of @child. If @child is at the toplevel, and doesn’t have a parent, then @iter is set to an invalid iterator and %FALSE is returned. @child will remain a valid node after this function has been called. @iter will be initialized before the lookup is performed, so @child and @iter cannot point to the same memory location. %TRUE, if @iter is set to the parent of @child a `GtkTreeModel` the new `GtkTreeIter` to set to the parent the `GtkTreeIter` Sets @iter to point to the previous node at the current level. If there is no previous @iter, %FALSE is returned and @iter is set to be invalid. %TRUE if @iter has been changed to the previous node a `GtkTreeModel` the `GtkTreeIter` Lets the tree ref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. This function is primarily meant as a way for views to let caching models know when nodes are being displayed (and hence, whether or not to cache that node). Being displayed means a node is in an expanded branch, regardless of whether the node is currently visible in the viewport. For example, a file-system based model would not want to keep the entire file-hierarchy in memory, just the sections that are currently being displayed by every current view. A model should be expected to be able to get an iter independent of its reffed state. a `GtkTreeModel` the `GtkTreeIter` Emits the ::row-changed signal on @tree_model. See [signal@Gtk.TreeModel::row-changed]. a `GtkTreeModel` a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row Emits the ::row-deleted signal on @tree_model. See [signal@Gtk.TreeModel::row-deleted]. This should be called by models after a row has been removed. The location pointed to by @path should be the location that the row previously was at. It may not be a valid location anymore. Nodes that are deleted are not unreffed, this means that any outstanding references on the deleted node should not be released. a `GtkTreeModel` a `GtkTreePath` pointing to the previous location of the deleted row Emits the ::row-has-child-toggled signal on @tree_model. See [signal@Gtk.TreeModel::row-has-child-toggled]. This should be called by models after the child state of a node changes. a `GtkTreeModel` a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row Emits the ::row-inserted signal on @tree_model. See [signal@Gtk.TreeModel::row-inserted]. a `GtkTreeModel` a `GtkTreePath` pointing to the inserted row a valid `GtkTreeIter` pointing to the inserted row Emits the ::rows-reordered signal on @tree_model. See [signal@Gtk.TreeModel::rows-reordered]. This should be called by models when their rows have been reordered. a `GtkTreeModel` a `GtkTreePath` pointing to the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` Lets the tree unref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. For more information on what this means, see gtk_tree_model_ref_node(). Please note that nodes that are deleted are not unreffed. a `GtkTreeModel` the `GtkTreeIter` Creates a new `GtkTreeModel`, with @child_model as the child_model and @root as the virtual root. A new `GtkTreeModel`. A `GtkTreeModel`. A `GtkTreePath` Calls @func on each node in model in a depth-first fashion. If @func returns %TRUE, then the tree ceases to be walked, and gtk_tree_model_foreach() returns. a `GtkTreeModel` a function to be called on each row user data to passed to @func Gets the value of one or more cells in the row referenced by @iter. The variable argument list should contain integer column numbers, each column number followed by a place to store the value being retrieved. The list is terminated by a -1. For example, to get a value from column 0 with type %G_TYPE_STRING, you would write: `gtk_tree_model_get (model, iter, 0, &place_string_here, -1)`, where `place_string_here` is a #gchararray to be filled with the string. Returned values with type %G_TYPE_OBJECT have to be unreferenced, values with type %G_TYPE_STRING or %G_TYPE_BOXED have to be freed. Other values are passed by value. a `GtkTreeModel` a row in @tree_model pairs of column number and value return locations, terminated by -1 Returns the type of the column. the type of the column a `GtkTreeModel` the column index Returns a set of flags supported by this interface. The flags are a bitwise combination of `GtkTreeModel`Flags. The flags supported should not change during the lifetime of the @tree_model. the flags supported by this interface a `GtkTreeModel` Sets @iter to a valid iterator pointing to @path. If @path does not exist, @iter is set to an invalid iterator and %FALSE is returned. %TRUE, if @iter was set a `GtkTreeModel` the uninitialized `GtkTreeIter` the `GtkTreePath` Initializes @iter with the first iterator in the tree (the one at the path "0"). Returns %FALSE if the tree is empty, %TRUE otherwise. %TRUE, if @iter was set a `GtkTreeModel` the uninitialized `GtkTreeIter` Sets @iter to a valid iterator pointing to @path_string, if it exists. Otherwise, @iter is left invalid and %FALSE is returned. %TRUE, if @iter was set a `GtkTreeModel` an uninitialized `GtkTreeIter` a string representation of a `GtkTreePath` Returns the number of columns supported by @tree_model. the number of columns a `GtkTreeModel` Returns a newly-created `GtkTreePath` referenced by @iter. This path should be freed with gtk_tree_path_free(). a newly-created `GtkTreePath` a `GtkTreeModel` the `GtkTreeIter` Generates a string representation of the iter. This string is a “:” separated list of numbers. For example, “4:10:0:3” would be an acceptable return value for this string. a newly-allocated string a `GtkTreeModel` a `GtkTreeIter` Gets the value of one or more cells in the row referenced by @iter. See [method@Gtk.TreeModel.get], this version takes a va_list for language bindings to use. a `GtkTreeModel` a row in @tree_model va_list of column/return location pairs Initializes and sets @value to that at @column. When done with @value, g_value_unset() needs to be called to free any allocated memory. a `GtkTreeModel` the `GtkTreeIter` the column to lookup the value at an empty `GValue` to set Sets @iter to point to the first child of @parent. If @parent has no children, %FALSE is returned and @iter is set to be invalid. @parent will remain a valid node after this function has been called. If @parent is %NULL returns the first node, equivalent to `gtk_tree_model_get_iter_first (tree_model, iter);` %TRUE, if @iter has been set to the first child a `GtkTreeModel` the new `GtkTreeIter` to be set to the child the `GtkTreeIter` Returns %TRUE if @iter has children, %FALSE otherwise. %TRUE if @iter has children a `GtkTreeModel` the `GtkTreeIter` to test for children Returns the number of children that @iter has. As a special case, if @iter is %NULL, then the number of toplevel nodes is returned. the number of children of @iter a `GtkTreeModel` the `GtkTreeIter` Sets @iter to point to the node following it at the current level. If there is no next @iter, %FALSE is returned and @iter is set to be invalid. %TRUE if @iter has been changed to the next node a `GtkTreeModel` the `GtkTreeIter` Sets @iter to be the child of @parent, using the given index. The first index is 0. If @n is too big, or @parent has no children, @iter is set to an invalid iterator and %FALSE is returned. @parent will remain a valid node after this function has been called. As a special case, if @parent is %NULL, then the @n-th root node is set. %TRUE, if @parent has an @n-th child a `GtkTreeModel` the `GtkTreeIter` to set to the nth child the `GtkTreeIter` to get the child from the index of the desired child Sets @iter to be the parent of @child. If @child is at the toplevel, and doesn’t have a parent, then @iter is set to an invalid iterator and %FALSE is returned. @child will remain a valid node after this function has been called. @iter will be initialized before the lookup is performed, so @child and @iter cannot point to the same memory location. %TRUE, if @iter is set to the parent of @child a `GtkTreeModel` the new `GtkTreeIter` to set to the parent the `GtkTreeIter` Sets @iter to point to the previous node at the current level. If there is no previous @iter, %FALSE is returned and @iter is set to be invalid. %TRUE if @iter has been changed to the previous node a `GtkTreeModel` the `GtkTreeIter` Lets the tree ref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. This function is primarily meant as a way for views to let caching models know when nodes are being displayed (and hence, whether or not to cache that node). Being displayed means a node is in an expanded branch, regardless of whether the node is currently visible in the viewport. For example, a file-system based model would not want to keep the entire file-hierarchy in memory, just the sections that are currently being displayed by every current view. A model should be expected to be able to get an iter independent of its reffed state. a `GtkTreeModel` the `GtkTreeIter` Emits the ::row-changed signal on @tree_model. See [signal@Gtk.TreeModel::row-changed]. a `GtkTreeModel` a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row Emits the ::row-deleted signal on @tree_model. See [signal@Gtk.TreeModel::row-deleted]. This should be called by models after a row has been removed. The location pointed to by @path should be the location that the row previously was at. It may not be a valid location anymore. Nodes that are deleted are not unreffed, this means that any outstanding references on the deleted node should not be released. a `GtkTreeModel` a `GtkTreePath` pointing to the previous location of the deleted row Emits the ::row-has-child-toggled signal on @tree_model. See [signal@Gtk.TreeModel::row-has-child-toggled]. This should be called by models after the child state of a node changes. a `GtkTreeModel` a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row Emits the ::row-inserted signal on @tree_model. See [signal@Gtk.TreeModel::row-inserted]. a `GtkTreeModel` a `GtkTreePath` pointing to the inserted row a valid `GtkTreeIter` pointing to the inserted row Emits the ::rows-reordered signal on @tree_model. See [signal@Gtk.TreeModel::rows-reordered]. This should be called by models when their rows have been reordered. a `GtkTreeModel` a `GtkTreePath` pointing to the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` Emits the ::rows-reordered signal on @tree_model. See [signal@Gtk.TreeModel::rows-reordered]. This should be called by models when their rows have been reordered. a `GtkTreeModel` a `GtkTreePath` pointing to the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` length of @new_order array Lets the tree unref the node. This is an optional method for models to implement. To be more specific, models may ignore this call as it exists primarily for performance reasons. For more information on what this means, see gtk_tree_model_ref_node(). Please note that nodes that are deleted are not unreffed. a `GtkTreeModel` the `GtkTreeIter` This signal is emitted when a row in the model has changed. a `GtkTreePath` identifying the changed row a valid `GtkTreeIter` pointing to the changed row This signal is emitted when a row has been deleted. Note that no iterator is passed to the signal handler, since the row is already deleted. This should be called by models after a row has been removed. The location pointed to by @path should be the location that the row previously was at. It may not be a valid location anymore. a `GtkTreePath` identifying the row This signal is emitted when a row has gotten the first child row or lost its last child row. a `GtkTreePath` identifying the row a valid `GtkTreeIter` pointing to the row This signal is emitted when a new row has been inserted in the model. Note that the row may still be empty at this point, since it is a common pattern to first insert an empty row, and then fill it with the desired values. a `GtkTreePath` identifying the new row a valid `GtkTreeIter` pointing to the new row This signal is emitted when the children of a node in the `GtkTreeModel` have been reordered. Note that this signal is not emitted when rows are reordered by DND, since this is implemented by removing and then reinserting the row. a `GtkTreePath` identifying the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` A `GtkTreeModel` which hides parts of an underlying tree model A `GtkTreeModelFilter` is a tree model which wraps another tree model, and can do the following things: - Filter specific rows, based on data from a “visible column”, a column storing booleans indicating whether the row should be filtered or not, or based on the return value of a “visible function”, which gets a model, iter and user_data and returns a boolean indicating whether the row should be filtered or not. - Modify the “appearance” of the model, using a modify function. This is extremely powerful and allows for just changing some values and also for creating a completely different model based on the given child model. - Set a different root node, also known as a “virtual root”. You can pass in a `GtkTreePath` indicating the root node for the filter at construction time. The basic API is similar to `GtkTreeModelSort`. For an example on its usage, see the section on `GtkTreeModelSort`. When using `GtkTreeModelFilter`, it is important to realize that `GtkTreeModelFilter` maintains an internal cache of all nodes which are visible in its clients. The cache is likely to be a subtree of the tree exposed by the child model. `GtkTreeModelFilter` will not cache the entire child model when unnecessary to not compromise the caching mechanism that is exposed by the reference counting scheme. If the child model implements reference counting, unnecessary signals may not be emitted because of reference counting rule 3, see the `GtkTreeModel` documentation. (Note that e.g. `GtkTreeStore` does not implement reference counting and will always emit all signals, even when the receiving node is not visible). Because of this, limitations for possible visible functions do apply. In general, visible functions should only use data or properties from the node for which the visibility state must be determined, its siblings or its parents. Usually, having a dependency on the state of any child node is not possible, unless references are taken on these explicitly. When no such reference exists, no signals may be received for these child nodes (see reference counting rule number 3 in the `GtkTreeModel` section). Determining the visibility state of a given node based on the state of its child nodes is a frequently occurring use case. Therefore, `GtkTreeModelFilter` explicitly supports this. For example, when a node does not have any children, you might not want the node to be visible. As soon as the first row is added to the node’s child level (or the last row removed), the node’s visibility should be updated. This introduces a dependency from the node on its child nodes. In order to accommodate this, `GtkTreeModelFilter` must make sure the necessary signals are received from the child model. This is achieved by building, for all nodes which are exposed as visible nodes to `GtkTreeModelFilter`'s clients, the child level (if any) and take a reference on the first node in this level. Furthermore, for every row-inserted, row-changed or row-deleted signal (also these which were not handled because the node was not cached), `GtkTreeModelFilter` will check if the visibility state of any parent node has changed. Beware, however, that this explicit support is limited to these two cases. For example, if you want a node to be visible only if two nodes in a child’s child level (2 levels deeper) are visible, you are on your own. In this case, either rely on `GtkTreeStore` to emit all signals because it does not implement reference counting, or for models that do implement reference counting, obtain references on these child levels yourself. Use [class@Gtk.FilterListModel] instead. This function should almost never be called. It clears the @filter of any cached iterators that haven’t been reffed with gtk_tree_model_ref_node(). This might be useful if the child model being filtered is static (and doesn’t change often) and there has been a lot of unreffed access to nodes. As a side effect of this function, all unreffed iters will be invalid. A `GtkTreeModelFilter` Sets @filter_iter to point to the row in @filter that corresponds to the row pointed at by @child_iter. If @filter_iter was not set, %FALSE is returned. %TRUE, if @filter_iter was set, i.e. if @child_iter is a valid iterator pointing to a visible row in child model. A `GtkTreeModelFilter` An uninitialized `GtkTreeIter` A valid `GtkTreeIter` pointing to a row on the child model. Converts @child_path to a path relative to @filter. That is, @child_path points to a path in the child model. The rerturned path will point to the same row in the filtered model. If @child_path isn’t a valid path on the child model or points to a row which is not visible in @filter, then %NULL is returned. A newly allocated `GtkTreePath` A `GtkTreeModelFilter` A `GtkTreePath` to convert. Sets @child_iter to point to the row pointed to by @filter_iter. A `GtkTreeModelFilter` An uninitialized `GtkTreeIter` A valid `GtkTreeIter` pointing to a row on @filter. Converts @filter_path to a path on the child model of @filter. That is, @filter_path points to a location in @filter. The returned path will point to the same location in the model not being filtered. If @filter_path does not point to a location in the child model, %NULL is returned. A newly allocated `GtkTreePath` A `GtkTreeModelFilter` A `GtkTreePath` to convert. Returns a pointer to the child model of @filter. A pointer to a `GtkTreeModel` A `GtkTreeModelFilter` Emits ::row_changed for each row in the child model, which causes the filter to re-evaluate whether a row is visible or not. A `GtkTreeModelFilter` With the @n_columns and @types parameters, you give an array of column types for this model (which will be exposed to the parent model/view). The @func, @data and @destroy parameters are for specifying the modify function. The modify function will get called for each data access, the goal of the modify function is to return the data which should be displayed at the location specified using the parameters of the modify function. Note that gtk_tree_model_filter_set_modify_func() can only be called once for a given filter model. A `GtkTreeModelFilter` The number of columns in the filter model. The `GType`s of the columns. A `GtkTreeModelFilterModifyFunc` User data to pass to the modify function Destroy notifier of @data Sets @column of the child_model to be the column where @filter should look for visibility information. @columns should be a column of type %G_TYPE_BOOLEAN, where %TRUE means that a row is visible, and %FALSE if not. Note that gtk_tree_model_filter_set_visible_func() or gtk_tree_model_filter_set_visible_column() can only be called once for a given filter model. A `GtkTreeModelFilter` A `int` which is the column containing the visible information Sets the visible function used when filtering the @filter to be @func. The function should return %TRUE if the given row should be visible and %FALSE otherwise. If the condition calculated by the function changes over time (e.g. because it depends on some global parameters), you must call gtk_tree_model_filter_refilter() to keep the visibility information of the model up-to-date. Note that @func is called whenever a row is inserted, when it may still be empty. The visible function should therefore take special care of empty rows, like in the example below. |[<!-- language="C" --> static gboolean visible_func (GtkTreeModel *model, GtkTreeIter *iter, gpointer data) { // Visible if row is non-empty and first column is “HI” char *str; gboolean visible = FALSE; gtk_tree_model_get (model, iter, 0, &str, -1); if (str && strcmp (str, "HI") == 0) visible = TRUE; g_free (str); return visible; } ]| Note that gtk_tree_model_filter_set_visible_func() or gtk_tree_model_filter_set_visible_column() can only be called once for a given filter model. A `GtkTreeModelFilter` A `GtkTreeModelFilterVisibleFunc`, the visible function User data to pass to the visible function Destroy notifier of @data The child model of the tree model filter. The virtual root of the tree model filter. A function which calculates display values from raw values in the model. It must fill @value with the display value for the column @column in the row indicated by @iter. Since this function is called for each data access, it’s not a particularly efficient operation. the `GtkTreeModelFilter` a `GtkTreeIter` pointing to the row whose display values are determined A `GValue` which is already initialized for with the correct type for the column @column. the column whose display value is determined user data given to gtk_tree_model_filter_set_modify_func() A function which decides whether the row indicated by @iter is visible. Whether the row indicated by @iter is visible. the child model of the `GtkTreeModelFilter` a `GtkTreeIter` pointing to the row in @model whose visibility is determined user data given to gtk_tree_model_filter_set_visible_func() These flags indicate various properties of a `GtkTreeModel`. They are returned by [method@Gtk.TreeModel.get_flags], and must be static for the lifetime of the object. A more complete description of %GTK_TREE_MODEL_ITERS_PERSIST can be found in the overview of this section. iterators survive all signals emitted by the tree the model is a list only, and never has children Type of the callback passed to gtk_tree_model_foreach() to iterate over the rows in a tree model. %TRUE to stop iterating, %FALSE to continue the `GtkTreeModel` being iterated the current `GtkTreePath` the current `GtkTreeIter` The user data passed to gtk_tree_model_foreach() Signal emitted when a row in the model has changed. a `GtkTreeModel` a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row Signal emitted when a new row has been inserted in the model. a `GtkTreeModel` a `GtkTreePath` pointing to the inserted row a valid `GtkTreeIter` pointing to the inserted row Signal emitted when a row has gotten the first child row or lost its last child row. a `GtkTreeModel` a `GtkTreePath` pointing to the changed row a valid `GtkTreeIter` pointing to the changed row Signal emitted when a row has been deleted. a `GtkTreeModel` a `GtkTreePath` pointing to the previous location of the deleted row Signal emitted when the children of a node in the GtkTreeModel have been reordered. a `GtkTreeModel` a `GtkTreePath` pointing to the tree node whose children have been reordered a valid `GtkTreeIter` pointing to the node whose children have been reordered, or %NULL if the depth of @path is 0 an array of integers mapping the current position of each child to its old position before the re-ordering, i.e. @new_order`[newpos] = oldpos` Get `GtkTreeModelFlags` supported by this interface. the flags supported by this interface a `GtkTreeModel` Get the number of columns supported by the model. the number of columns a `GtkTreeModel` Get the type of the column. the type of the column a `GtkTreeModel` the column index Sets iter to a valid iterator pointing to path. %TRUE, if @iter was set a `GtkTreeModel` the uninitialized `GtkTreeIter` the `GtkTreePath` Gets a newly-created `GtkTreePath` referenced by iter. a newly-created `GtkTreePath` a `GtkTreeModel` the `GtkTreeIter` Initializes and sets value to that at column. a `GtkTreeModel` the `GtkTreeIter` the column to lookup the value at an empty `GValue` to set Sets iter to point to the node following it at the current level. %TRUE if @iter has been changed to the next node a `GtkTreeModel` the `GtkTreeIter` Sets iter to point to the previous node at the current level. %TRUE if @iter has been changed to the previous node a `GtkTreeModel` the `GtkTreeIter` Sets iter to point to the first child of parent. %TRUE, if @iter has been set to the first child a `GtkTreeModel` the new `GtkTreeIter` to be set to the child the `GtkTreeIter` %TRUE if iter has children, %FALSE otherwise. %TRUE if @iter has children a `GtkTreeModel` the `GtkTreeIter` to test for children Gets the number of children that iter has. the number of children of @iter a `GtkTreeModel` the `GtkTreeIter` Sets iter to be the child of parent, using the given index. %TRUE, if @parent has an @n-th child a `GtkTreeModel` the `GtkTreeIter` to set to the nth child the `GtkTreeIter` to get the child from the index of the desired child Sets iter to be the parent of child. %TRUE, if @iter is set to the parent of @child a `GtkTreeModel` the new `GtkTreeIter` to set to the parent the `GtkTreeIter` Lets the tree ref the node. a `GtkTreeModel` the `GtkTreeIter` Lets the tree unref the node. a `GtkTreeModel` the `GtkTreeIter` A GtkTreeModel which makes an underlying tree model sortable The `GtkTreeModelSort` is a model which implements the `GtkTreeSortable` interface. It does not hold any data itself, but rather is created with a child model and proxies its data. It has identical column types to this child model, and the changes in the child are propagated. The primary purpose of this model is to provide a way to sort a different model without modifying it. Note that the sort function used by `GtkTreeModelSort` is not guaranteed to be stable. The use of this is best demonstrated through an example. In the following sample code we create two `GtkTreeView` widgets each with a view of the same data. As the model is wrapped here by a `GtkTreeModelSort`, the two `GtkTreeView`s can each sort their view of the data without affecting the other. By contrast, if we simply put the same model in each widget, then sorting the first would sort the second. ## Using a `GtkTreeModelSort` |[<!-- language="C" --> { GtkTreeView *tree_view1; GtkTreeView *tree_view2; GtkTreeModel *sort_model1; GtkTreeModel *sort_model2; GtkTreeModel *child_model; // get the child model child_model = get_my_model (); // Create the first tree sort_model1 = gtk_tree_model_sort_new_with_model (child_model); tree_view1 = gtk_tree_view_new_with_model (sort_model1); // Create the second tree sort_model2 = gtk_tree_model_sort_new_with_model (child_model); tree_view2 = gtk_tree_view_new_with_model (sort_model2); // Now we can sort the two models independently gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1), COLUMN_1, GTK_SORT_ASCENDING); gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2), COLUMN_1, GTK_SORT_DESCENDING); } ]| To demonstrate how to access the underlying child model from the sort model, the next example will be a callback for the `GtkTreeSelection` `GtkTreeSelection::changed` signal. In this callback, we get a string from COLUMN_1 of the model. We then modify the string, find the same selected row on the child model, and change the row there. ## Accessing the child model of in a selection changed callback |[<!-- language="C" --> void selection_changed (GtkTreeSelection *selection, gpointer data) { GtkTreeModel *sort_model = NULL; GtkTreeModel *child_model; GtkTreeIter sort_iter; GtkTreeIter child_iter; char *some_data = NULL; char *modified_data; // Get the current selected row and the model. if (! gtk_tree_selection_get_selected (selection, &sort_model, &sort_iter)) return; // Look up the current value on the selected row and get // a new value to change it to. gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter, COLUMN_1, &some_data, -1); modified_data = change_the_data (some_data); g_free (some_data); // Get an iterator on the child model, instead of the sort model. gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model), &child_iter, &sort_iter); // Get the child model and change the value of the row. In this // example, the child model is a GtkListStore. It could be any other // type of model, though. child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model)); gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter, COLUMN_1, &modified_data, -1); g_free (modified_data); } ]| Use [class@Gtk.SortListModel] instead Creates a new `GtkTreeModelSort`, with @child_model as the child model. A new `GtkTreeModelSort`. A `GtkTreeModel` This function should almost never be called. It clears the @tree_model_sort of any cached iterators that haven’t been reffed with gtk_tree_model_ref_node(). This might be useful if the child model being sorted is static (and doesn’t change often) and there has been a lot of unreffed access to nodes. As a side effect of this function, all unreffed iters will be invalid. A `GtkTreeModelSort` Sets @sort_iter to point to the row in @tree_model_sort that corresponds to the row pointed at by @child_iter. If @sort_iter was not set, %FALSE is returned. Note: a boolean is only returned since 2.14. %TRUE, if @sort_iter was set, i.e. if @sort_iter is a valid iterator pointer to a visible row in the child model. A `GtkTreeModelSort` An uninitialized `GtkTreeIter` A valid `GtkTreeIter` pointing to a row on the child model Converts @child_path to a path relative to @tree_model_sort. That is, @child_path points to a path in the child model. The returned path will point to the same row in the sorted model. If @child_path isn’t a valid path on the child model, then %NULL is returned. A newly allocated `GtkTreePath` A `GtkTreeModelSort` A `GtkTreePath` to convert Sets @child_iter to point to the row pointed to by @sorted_iter. A `GtkTreeModelSort` An uninitialized `GtkTreeIter` A valid `GtkTreeIter` pointing to a row on @tree_model_sort. Converts @sorted_path to a path on the child model of @tree_model_sort. That is, @sorted_path points to a location in @tree_model_sort. The returned path will point to the same location in the model not being sorted. If @sorted_path does not point to a location in the child model, %NULL is returned. A newly allocated `GtkTreePath` A `GtkTreeModelSort` A `GtkTreePath` to convert Returns the model the `GtkTreeModelSort` is sorting. the "child model" being sorted a `GtkTreeModelSort` > This function is slow. Only use it for debugging and/or testing > purposes. Checks if the given iter is a valid iter for this `GtkTreeModelSort`. %TRUE if the iter is valid, %FALSE if the iter is invalid. A `GtkTreeModelSort`. A `GtkTreeIter` This resets the default sort function to be in the “unsorted” state. That is, it is in the same order as the child model. It will re-sort the model to be in the same order as the child model only if the `GtkTreeModelSort` is in “unsorted” state. A `GtkTreeModelSort` The model of the tree model sort. An opaque structure representing a path to a row in a model. Creates a new `GtkTreePath` This refers to a row. A newly created `GtkTreePath`. Creates a new `GtkTreePath`. The string representation of this path is “0”. A new `GtkTreePath` Creates a new path with @first_index and @varargs as indices. A newly created `GtkTreePath` first integer list of integers terminated by -1 Creates a new path with the given @indices array of @length. A newly created `GtkTreePath` array of indices length of @indices array Creates a new `GtkTreePath` initialized to @path. @path is expected to be a colon separated list of numbers. For example, the string “10:4:0” would create a path of depth 3 pointing to the 11th child of the root node, the 5th child of that 11th child, and the 1st child of that 5th child. If an invalid path string is passed in, %NULL is returned. A newly-created `GtkTreePath` The string representation of a path Appends a new index to a path. As a result, the depth of the path is increased. a `GtkTreePath` the index Compares two paths. If @a appears before @b in a tree, then -1 is returned. If @b appears before @a, then 1 is returned. If the two nodes are equal, then 0 is returned. the relative positions of @a and @b a `GtkTreePath` a `GtkTreePath` to compare with Creates a new `GtkTreePath` as a copy of @path. a new `GtkTreePath` a `GtkTreePath` Moves @path to point to the first child of the current path. a `GtkTreePath` Frees @path. If @path is %NULL, it simply returns. a `GtkTreePath` Returns the current depth of @path. The depth of @path a `GtkTreePath` Returns the current indices of @path. This is an array of integers, each representing a node in a tree. This value should not be freed. The length of the array can be obtained with gtk_tree_path_get_depth(). The current indices a `GtkTreePath` Returns the current indices of @path. This is an array of integers, each representing a node in a tree. It also returns the number of elements in the array. The array should not be freed. The current indices a `GtkTreePath` return location for number of elements returned in the integer array Returns %TRUE if @descendant is a descendant of @path. %TRUE if @descendant is contained inside @path a `GtkTreePath` another `GtkTreePath` Returns %TRUE if @path is a descendant of @ancestor. %TRUE if @ancestor contains @path somewhere below it a `GtkTreePath` another `GtkTreePath` Moves the @path to point to the next node at the current depth. a `GtkTreePath` Prepends a new index to a path. As a result, the depth of the path is increased. a `GtkTreePath` the index Moves the @path to point to the previous node at the current depth, if it exists. %TRUE if @path has a previous node, and the move was made a `GtkTreePath` Generates a string representation of the path. This string is a “:” separated list of numbers. For example, “4:10:0:3” would be an acceptable return value for this string. If the path has depth 0, %NULL is returned. A newly-allocated string a `GtkTreePath` Moves the @path to point to its parent node, if it has a parent. %TRUE if @path has a parent, and the move was made a `GtkTreePath` A GtkTreeRowReference tracks model changes so that it always refers to the same row (a `GtkTreePath` refers to a position, not a fixed row). Create a new GtkTreeRowReference with gtk_tree_row_reference_new(). Use [iface@Gio.ListModel] instead Creates a row reference based on @path. This reference will keep pointing to the node pointed to by @path, so long as it exists. Any changes that occur on @model are propagated, and the path is updated appropriately. If @path isn’t a valid path in @model, then %NULL is returned. a newly allocated `GtkTreeRowReference` a `GtkTreeModel` a valid `GtkTreePath` to monitor You do not need to use this function. Creates a row reference based on @path. This reference will keep pointing to the node pointed to by @path, so long as it exists. If @path isn’t a valid path in @model, then %NULL is returned. However, unlike references created with gtk_tree_row_reference_new(), it does not listen to the model for changes. The creator of the row reference must do this explicitly using gtk_tree_row_reference_inserted(), gtk_tree_row_reference_deleted(), gtk_tree_row_reference_reordered(). These functions must be called exactly once per proxy when the corresponding signal on the model is emitted. This single call updates all row references for that proxy. Since built-in GTK objects like `GtkTreeView` already use this mechanism internally, using them as the proxy object will produce unpredictable results. Further more, passing the same object as @model and @proxy doesn’t work for reasons of internal implementation. This type of row reference is primarily meant by structures that need to carefully monitor exactly when a row reference updates itself, and is not generally needed by most applications. a newly allocated `GtkTreeRowReference` a proxy `GObject` a `GtkTreeModel` a valid `GtkTreePath` to monitor Copies a `GtkTreeRowReference`. a copy of @reference a `GtkTreeRowReference` Free’s @reference. @reference may be %NULL a `GtkTreeRowReference` Returns the model that the row reference is monitoring. the model a `GtkTreeRowReference` Returns a path that the row reference currently points to, or %NULL if the path pointed to is no longer valid. a current path a `GtkTreeRowReference` Returns %TRUE if the @reference is non-%NULL and refers to a current valid path. %TRUE if @reference points to a valid path a `GtkTreeRowReference` Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::row-deleted signal. a `GObject` the path position that was deleted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::row-inserted signal. a `GObject` the row position that was inserted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::rows-reordered signal. a `GObject` the parent path of the reordered signal the iter pointing to the parent of the reordered the new order of rows The selection object for GtkTreeView The `GtkTreeSelection` object is a helper object to manage the selection for a `GtkTreeView` widget. The `GtkTreeSelection` object is automatically created when a new `GtkTreeView` widget is created, and cannot exist independently of this widget. The primary reason the `GtkTreeSelection` objects exists is for cleanliness of code and API. That is, there is no conceptual reason all these functions could not be methods on the `GtkTreeView` widget instead of a separate function. The `GtkTreeSelection` object is gotten from a `GtkTreeView` by calling gtk_tree_view_get_selection(). It can be manipulated to check the selection status of the tree, as well as select and deselect individual rows. Selection is done completely view side. As a result, multiple views of the same model can have completely different selections. Additionally, you cannot change the selection of a row on the model that is not currently displayed by the view without expanding its parents first. One of the important things to remember when monitoring the selection of a view is that the `GtkTreeSelection`::changed signal is mostly a hint. That is, it may only emit one signal when a range of rows is selected. Additionally, it may on occasion emit a `GtkTreeSelection`::changed signal when nothing has happened (mostly as a result of programmers calling select_row on an already selected row). Use [iface@Gtk.SelectionModel] instead Returns the number of rows that have been selected in @tree. Use GtkListView or GtkColumnView The number of rows selected. A `GtkTreeSelection`. Gets the selection mode for @selection. See gtk_tree_selection_set_mode(). Use GtkListView or GtkColumnView the current selection mode a `GtkTreeSelection` Returns the current selection function. Use GtkListView or GtkColumnView The function. A `GtkTreeSelection`. Sets @iter to the currently selected node if @selection is set to %GTK_SELECTION_SINGLE or %GTK_SELECTION_BROWSE. @iter may be NULL if you just want to test if @selection has any selected nodes. @model is filled with the current model as a convenience. This function will not work if you use @selection is %GTK_SELECTION_MULTIPLE. Use GtkListView or GtkColumnView TRUE, if there is a selected node. A `GtkTreeSelection`. A pointer to set to the `GtkTreeModel` The `GtkTreeIter` Creates a list of path of all selected rows. Additionally, if you are planning on modifying the model after calling this function, you may want to convert the returned list into a list of `GtkTreeRowReference`s. To do this, you can use gtk_tree_row_reference_new(). To free the return value, use: |[<!-- language="C" --> g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free); ]| Use GtkListView or GtkColumnView A `GList` containing a `GtkTreePath` for each selected row. A `GtkTreeSelection`. A pointer to set to the `GtkTreeModel` Returns the tree view associated with @selection. Use GtkListView or GtkColumnView A `GtkTreeView` A `GtkTreeSelection` Returns the user data for the selection function. Use GtkListView or GtkColumnView The user data. A `GtkTreeSelection`. Returns %TRUE if the row at @iter is currently selected. Use GtkListView or GtkColumnView %TRUE, if @iter is selected A `GtkTreeSelection` A valid `GtkTreeIter` Returns %TRUE if the row pointed to by @path is currently selected. If @path does not point to a valid location, %FALSE is returned Use GtkListView or GtkColumnView %TRUE if @path is selected. A `GtkTreeSelection`. A `GtkTreePath` to check selection on. Selects all the nodes. @selection must be set to %GTK_SELECTION_MULTIPLE mode. Use GtkListView or GtkColumnView A `GtkTreeSelection`. Selects the specified iterator. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The `GtkTreeIter` to be selected. Select the row at @path. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The `GtkTreePath` to be selected. Selects a range of nodes, determined by @start_path and @end_path inclusive. @selection must be set to %GTK_SELECTION_MULTIPLE mode. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The initial node of the range. The final node of the range. Calls a function for each selected node. Note that you cannot modify the tree or selection from within this function. As a result, gtk_tree_selection_get_selected_rows() might be more useful. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The function to call for each selected node. user data to pass to the function. Sets the selection mode of the @selection. If the previous type was %GTK_SELECTION_MULTIPLE, then the anchor is kept selected, if it was previously selected. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The selection mode Sets the selection function. If set, this function is called before any node is selected or unselected, giving some control over which nodes are selected. The select function should return %TRUE if the state of the node may be toggled, and %FALSE if the state of the node should be left unchanged. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The selection function. May be %NULL The selection function’s data. May be %NULL The destroy function for user data. May be %NULL Unselects all the nodes. Use GtkListView or GtkColumnView A `GtkTreeSelection`. Unselects the specified iterator. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The `GtkTreeIter` to be unselected. Unselects the row at @path. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The `GtkTreePath` to be unselected. Unselects a range of nodes, determined by @start_path and @end_path inclusive. Use GtkListView or GtkColumnView A `GtkTreeSelection`. The initial node of the range. The initial node of the range. Selection mode. See gtk_tree_selection_set_mode() for more information on this property. Emitted whenever the selection has (possibly) changed. Please note that this signal is mostly a hint. It may only be emitted once when a range of rows are selected, and it may occasionally be emitted when nothing has happened. A function used by gtk_tree_selection_selected_foreach() to map all selected rows. It will be called on every selected row in the view. The `GtkTreeModel` being viewed The `GtkTreePath` of a selected row A `GtkTreeIter` pointing to a selected row user data A function used by gtk_tree_selection_set_select_function() to filter whether or not a row may be selected. It is called whenever a row's state might change. A return value of %TRUE indicates to @selection that it is okay to change the selection. %TRUE, if the selection state of the row can be toggled A `GtkTreeSelection` A `GtkTreeModel` being viewed The `GtkTreePath` of the row in question %TRUE, if the path is currently selected user data The interface for sortable models used by GtkTreeView `GtkTreeSortable` is an interface to be implemented by tree models which support sorting. The `GtkTreeView` uses the methods provided by this interface to sort the model. There is no replacement for this interface. You should use [class@Gtk.SortListModel] to wrap your list model instead Fills in @sort_column_id and @order with the current sort column and the order. It returns %TRUE unless the @sort_column_id is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID or %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID. %TRUE if the sort column is not one of the special sort column ids. A `GtkTreeSortable` The sort column id to be filled in The `GtkSortType` to be filled in Returns %TRUE if the model has a default sort function. This is used primarily by GtkTreeViewColumns in order to determine if a model can go back to the default state, or not. %TRUE, if the model has a default sort function A `GtkTreeSortable` Sets the default comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the model will sort using this function. If @sort_func is %NULL, then there will be no default comparison function. This means that once the model has been sorted, it can’t go back to the default state. In this case, when the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted. A `GtkTreeSortable` The comparison function User data to pass to @sort_func Destroy notifier of @user_data Sets the current sort column to be @sort_column_id. The @sortable will resort itself to reflect this change, after emitting a `GtkTreeSortable::sort-column-changed` signal. @sort_column_id may either be a regular column id, or one of the following special values: - %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID: the default sort function will be used, if it is set - %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID: no sorting will occur A `GtkTreeSortable` the sort column id to set The sort order of the column Sets the comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is the same as @sort_column_id, then the model will sort using this function. A `GtkTreeSortable` the sort column id to set the function for The comparison function User data to pass to @sort_func Destroy notifier of @user_data Emits a `GtkTreeSortable::sort-column-changed` signal on @sortable. A `GtkTreeSortable` Fills in @sort_column_id and @order with the current sort column and the order. It returns %TRUE unless the @sort_column_id is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID or %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID. %TRUE if the sort column is not one of the special sort column ids. A `GtkTreeSortable` The sort column id to be filled in The `GtkSortType` to be filled in Returns %TRUE if the model has a default sort function. This is used primarily by GtkTreeViewColumns in order to determine if a model can go back to the default state, or not. %TRUE, if the model has a default sort function A `GtkTreeSortable` Sets the default comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, then the model will sort using this function. If @sort_func is %NULL, then there will be no default comparison function. This means that once the model has been sorted, it can’t go back to the default state. In this case, when the current sort column id of @sortable is %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID, the model will be unsorted. A `GtkTreeSortable` The comparison function User data to pass to @sort_func Destroy notifier of @user_data Sets the current sort column to be @sort_column_id. The @sortable will resort itself to reflect this change, after emitting a `GtkTreeSortable::sort-column-changed` signal. @sort_column_id may either be a regular column id, or one of the following special values: - %GTK_TREE_SORTABLE_DEFAULT_SORT_COLUMN_ID: the default sort function will be used, if it is set - %GTK_TREE_SORTABLE_UNSORTED_SORT_COLUMN_ID: no sorting will occur A `GtkTreeSortable` the sort column id to set The sort order of the column Sets the comparison function used when sorting to be @sort_func. If the current sort column id of @sortable is the same as @sort_column_id, then the model will sort using this function. A `GtkTreeSortable` the sort column id to set the function for The comparison function User data to pass to @sort_func Destroy notifier of @user_data Emits a `GtkTreeSortable::sort-column-changed` signal on @sortable. A `GtkTreeSortable` The ::sort-column-changed signal is emitted when the sort column or sort order of @sortable is changed. The signal is emitted before the contents of @sortable are resorted. Signal emitted when the sort column or sort order of sortable is changed. A `GtkTreeSortable` Fills in sort_column_id and order with the current sort column and the order. %TRUE if the sort column is not one of the special sort column ids. A `GtkTreeSortable` The sort column id to be filled in The `GtkSortType` to be filled in Sets the current sort column to be sort_column_id. A `GtkTreeSortable` the sort column id to set The sort order of the column Sets the comparison function used when sorting to be sort_func. A `GtkTreeSortable` the sort column id to set the function for The comparison function User data to pass to @sort_func Destroy notifier of @user_data Sets the default comparison function used when sorting to be sort_func. A `GtkTreeSortable` The comparison function User data to pass to @sort_func Destroy notifier of @user_data %TRUE if the model has a default sort function. %TRUE, if the model has a default sort function A `GtkTreeSortable` A tree-like data structure that can be used with the [class@Gtk.TreeView]. The `GtkTreeStore` object is a list model for use with a `GtkTreeView` widget. It implements the [iface@Gtk.TreeModel] interface, and consequently, can use all of the methods available there. It also implements the [iface@Gtk.TreeSortable] interface so it can be sorted by the view. Finally, it also implements the tree [drag][iface@Gtk.TreeDragSource] and [drop][iface@Gtk.TreeDragDest] interfaces. `GtkTreeStore` is deprecated since GTK 4.10, and should not be used in newly written code. You should use [class@Gtk.TreeListModel] for a tree-like model object. ## GtkTreeStore as GtkBuildable The GtkTreeStore implementation of the `GtkBuildable` interface allows to specify the model columns with a `<columns>` element that may contain multiple `<column>` elements, each specifying one model column. The “type” attribute specifies the data type for the column. An example of a UI Definition fragment for a tree store: ```xml <object class="GtkTreeStore"> <columns> <column type="gchararray"/> <column type="gchararray"/> <column type="gint"/> </columns> </object> ``` Use [class@Gtk.TreeListModel] instead Creates a new tree store. The tree store will have @n_columns, with each column using the corresponding type passed to this function. Note that only types derived from standard GObject fundamental types are supported. As an example: ```c gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING, GDK_TYPE_TEXTURE); ``` will create a new `GtkTreeStore` with three columns of type `int`, `gchararray`, and `GdkTexture` respectively. Use [class@Gtk.TreeListModel] instead a new `GtkTreeStore` number of columns in the tree store all `GType` types for the columns, from first to last Creates a new tree store. This constructor is meant for language bindings. Use [class@Gtk.TreeListModel] instead a new `GtkTreeStore` number of columns in the tree store an array of `GType` types for the columns, from first to last Appends a new row to @tree_store. If @parent is non-%NULL, then it will append the new row after the last child of @parent, otherwise it will append a row to the top level. The @iter parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set to the appended row A valid `GtkTreeIter` Removes all rows from @tree_store Use [class@Gtk.TreeListModel] instead a `GtkTreeStore` Creates a new row at @position. If parent is non-%NULL, then the row will be made a child of @parent. Otherwise, the row will be created at the toplevel. If @position is `-1` or is larger than the number of rows at that level, then the new row will be inserted to the end of the list. The @iter parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set to the new row A valid `GtkTreeIter` position to insert the new row, or -1 for last Inserts a new row after @sibling. If @sibling is %NULL, then the row will be prepended to @parent’s children. If @parent and @sibling are %NULL, then the row will be prepended to the toplevel. If both @sibling and @parent are set, then @parent must be the parent of @sibling. When @sibling is set, @parent is optional. The @iter parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set to the new row A valid `GtkTreeIter` A valid `GtkTreeIter` Inserts a new row before @sibling. If @sibling is %NULL, then the row will be appended to @parent’s children. If @parent and @sibling are %NULL, then the row will be appended to the toplevel. If both @sibling and @parent are set, then @parent must be the parent of @sibling. When @sibling is set, @parent is optional. The @iter parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set to the new row A valid `GtkTreeIter` A valid `GtkTreeIter` Creates a new row at the given @position. The @iter parameter will be changed to point to this new row. If @position is -1, or larger than the number of rows on the list, then the new row will be appended to the list. The row will be filled with the values given to this function. Calling gtk_tree_store_insert_with_values (tree_store, iter, position, ...) has the same effect as calling ```c gtk_tree_store_insert (tree_store, iter, position); gtk_tree_store_set (tree_store, iter, ...); ``` with the different that the former will only emit a row_inserted signal, while the latter will emit row_inserted, row_changed and if the tree store is sorted, rows_reordered. Since emitting the rows_reordered signal repeatedly can affect the performance of the program, gtk_tree_store_insert_with_values() should generally be preferred when inserting rows in a sorted tree store. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set the new row A valid `GtkTreeIter` position to insert the new row, or -1 to append after existing rows pairs of column number and value, terminated with -1 A variant of gtk_tree_store_insert_with_values() which takes the columns and values as two arrays, instead of varargs. This function is mainly intended for language bindings. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set the new row A valid `GtkTreeIter` position to insert the new row, or -1 for last an array of column numbers an array of GValues the length of the @columns and @values arrays Checks if @iter is an ancestor of @descendant. Use [class@Gtk.TreeListModel] instead true if @iter is an ancestor of @descendant, and false otherwise A `GtkTreeStore` A valid `GtkTreeIter` A valid `GtkTreeIter` Returns the depth of the position pointed by the iterator The depth will be 0 for anything on the root level, 1 for anything down a level, etc. Use [class@Gtk.TreeListModel] instead The depth of the position pointed by the iterator A `GtkTreeStore` A valid `GtkTreeIter` Checks if the given iter is a valid iter for this `GtkTreeStore`. This function is slow. Only use it for debugging and/or testing purposes. Use [class@Gtk.TreeListModel] instead true if the iter is valid, and false otherwise a tree store the iterator to check Moves @iter in @tree_store to the position after @position. @iter and @position should be in the same level. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the start of the level. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` A `GtkTreeIter`. A `GtkTreeIter`. Moves @iter in @tree_store to the position before @position. @iter and @position should be in the same level. Note that this function only works with unsorted stores. If @position is %NULL, @iter will be moved to the end of the level. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` A `GtkTreeIter` A `GtkTreeIter` Prepends a new row to @tree_store. If @parent is non-%NULL, then it will prepend the new row before the first child of @parent, otherwise it will prepend a row to the top level. The `iter` parameter will be changed to point to this new row. The row will be empty after this function is called. To fill in values, you need to call gtk_tree_store_set() or gtk_tree_store_set_value(). Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` An unset `GtkTreeIter` to set to the prepended row A valid `GtkTreeIter` Removes @iter from @tree_store. After being removed, @iter is set to the next valid row at that level, or invalidated if it previously pointed to the last one. Use [class@Gtk.TreeListModel] instead true if @iter is still valid, and false otherwise A `GtkTreeStore` A valid `GtkTreeIter` Reorders the children of @parent in @tree_store to follow the order indicated by @new_order. Note that this function only works with unsorted stores. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` the parent of the children to re-order an array of integers mapping the new position of each child to its old position before the re-ordering, i.e. `new_order[newpos] = oldpos` Sets the value of one or more cells in the row referenced by @iter. The variable argument list should contain integer column numbers, each column number followed by the value to be set. The list is terminated by a value of `-1`. For example, to set column 0 with type `G_TYPE_STRING` to “Foo”, you would write ```c gtk_tree_store_set (store, iter, 0, "Foo", -1); ``` The value will be referenced by the store if it is a `G_TYPE_OBJECT`, and it will be copied if it is a `G_TYPE_STRING` or `G_TYPE_BOXED`. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` A valid `GtkTreeIter` for the row being modified pairs of column number and value, terminated with -1 Sets the type of the columns in a tree store. This function is meant primarily for types that inherit from `GtkTreeStore`, and should only be used when constructing a new `GtkTreeStore`. This functions cannot be called after a row has been added, or a method on the `GtkTreeModel` interface is called on the tree store. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` Number of columns for the tree store An array of `GType` types, one for each column A version of gtk_tree_store_set() using `va_list`. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` A valid `GtkTreeIter` for the row being modified va_list of column/value pairs Sets the data in the cell specified by @iter and @column. The type of @value must be convertible to the type of the column. Use [class@Gtk.TreeListModel] instead a `GtkTreeStore` A valid `GtkTreeIter` for the row being modified column number to modify new value for the cell A variant of gtk_tree_store_set_valist() which takes the columns and values as two arrays, instead of using variadic arguments. This function is mainly intended for language bindings or in case the number of columns to change is not known until run-time. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore` A valid `GtkTreeIter` for the row being modified an array of column numbers an array of GValues the length of the @columns and @values arrays Swaps @a and @b in the same level of @tree_store. Note that this function only works with unsorted stores. Use [class@Gtk.TreeListModel] instead A `GtkTreeStore`. A `GtkTreeIter`. Another `GtkTreeIter`. A widget for displaying both trees and lists Widget that displays any object that implements the [iface@Gtk.TreeModel] interface. Please refer to the [tree widget conceptual overview](section-tree-widget.html) for an overview of all the objects and data types related to the tree widget and how they work together. ## Coordinate systems in GtkTreeView API Several different coordinate systems are exposed in the `GtkTreeView` API. These are:  - Widget coordinates: Coordinates relative to the widget (usually `widget->window`). - Bin window coordinates: Coordinates relative to the window that GtkTreeView renders to. - Tree coordinates: Coordinates relative to the entire scrollable area of GtkTreeView. These coordinates start at (0, 0) for row 0 of the tree. Several functions are available for converting between the different coordinate systems. The most common translations are between widget and bin window coordinates and between bin window and tree coordinates. For the former you can use [method@Gtk.TreeView.convert_widget_to_bin_window_coords] (and vice versa), for the latter [method@Gtk.TreeView.convert_bin_window_to_tree_coords] (and vice versa). ## `GtkTreeView` as `GtkBuildable` The `GtkTreeView` implementation of the `GtkBuildable` interface accepts [class@Gtk.TreeViewColumn] objects as `<child>` elements and exposes the internal [class@Gtk.TreeSelection] in UI definitions. An example of a UI definition fragment with `GtkTreeView`: ```xml <object class="GtkTreeView" id="treeview"> <property name="model">liststore1</property> <child> <object class="GtkTreeViewColumn" id="test-column"> <property name="title">Test</property> <child> <object class="GtkCellRendererText" id="test-renderer"/> <attributes> <attribute name="text">1</attribute> </attributes> </child> </object> </child> <child internal-child="selection"> <object class="GtkTreeSelection" id="selection"> <signal name="changed" handler="on_treeview_selection_changed"/> </object> </child> </object> ``` ## CSS nodes ``` treeview.view ├── header │ ├── button │ │ ╰── [sort-indicator] ┊ ┊ │ ╰── button │ ╰── [sort-indicator] │ ├── [rubberband] ╰── [dndtarget] ``` `GtkTreeView` has a main CSS node with name `treeview` and style class `.view`. It has a subnode with name `header`, which is the parent for all the column header widgets' CSS nodes. Each column header consists of a `button`, which among other content, has a child with name `sort-indicator`, which carries the `.ascending` or `.descending` style classes when the column header should show a sort indicator. The CSS is expected to provide a suitable image using the `-gtk-icon-source` property. For rubberband selection, a subnode with name `rubberband` is used. For the drop target location during DND, a subnode with name `dndtarget` is used. Use [class@Gtk.ListView] for lists, and [class@Gtk.ColumnView] for tabular lists Creates a new `GtkTreeView` widget. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A newly created `GtkTreeView` widget. Creates a new `GtkTreeView` widget with the model initialized to @model. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A newly created `GtkTreeView` widget. the model. Activates the cell determined by @path and @column. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` The `GtkTreePath` to be activated. The `GtkTreeViewColumn` to be activated. Appends @column to the list of columns. If @tree_view has “fixed_height” mode enabled, then @column must have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The number of columns in @tree_view after appending. A `GtkTreeView`. The `GtkTreeViewColumn` to add. Recursively collapses all visible, expanded nodes in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. Collapses a row (hides its child rows, if they exist). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if the row was collapsed. a `GtkTreeView` path to a row in the @tree_view Resizes all columns to their optimal width. Only works after the treeview has been realized. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. Converts bin_window coordinates to coordinates for the tree (the full scrollable area of the tree). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` X coordinate relative to bin_window Y coordinate relative to bin_window return location for tree X coordinate return location for tree Y coordinate Converts bin_window coordinates to widget relative coordinates. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` bin_window X coordinate bin_window Y coordinate return location for widget X coordinate return location for widget Y coordinate Converts tree coordinates (coordinates in full scrollable area of the tree) to bin_window coordinates. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` tree X coordinate tree Y coordinate return location for X coordinate relative to bin_window return location for Y coordinate relative to bin_window Converts tree coordinates (coordinates in full scrollable area of the tree) to widget coordinates. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` X coordinate relative to the tree Y coordinate relative to the tree return location for widget X coordinate return location for widget Y coordinate Converts widget coordinates to coordinates for the bin_window. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` X coordinate relative to the widget Y coordinate relative to the widget return location for bin_window X coordinate return location for bin_window Y coordinate Converts widget coordinates to coordinates for the tree (the full scrollable area of the tree). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` X coordinate relative to the widget Y coordinate relative to the widget return location for tree X coordinate return location for tree Y coordinate Creates a `cairo_surface_t` representation of the row at @path. This image is used for a drag icon. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a newly-allocated surface of the drag icon. a `GtkTreeView` a `GtkTreePath` in @tree_view Turns @tree_view into a drop destination for automatic DND. Calling this method sets `GtkTreeView`:reorderable to %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` the target formats that the drag will support the bitmask of possible actions for a drag from this widget Turns @tree_view into a drag source for automatic DND. Calling this method sets `GtkTreeView`:reorderable to %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` Mask of allowed buttons to start drag the target formats that the drag will support the bitmask of possible actions for a drag from this widget Recursively expands all nodes in the @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. Opens the row so its children are visible. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if the row existed and had children a `GtkTreeView` path to a row whether to recursively expand, or just expand immediate children Expands the row at @path. This will also expand all parent rows of @path as necessary. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. path to a row. Gets the setting set by gtk_tree_view_set_activate_on_single_click(). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if row-activated will be emitted on a single click a `GtkTreeView` Fills the bounding rectangle in bin_window coordinates for the cell at the row specified by @path and the column specified by @column. If @path is %NULL, or points to a node not found in the tree, the @y and @height fields of the rectangle will be filled with 0. If @column is %NULL, the @x and @width fields will be filled with 0. The returned rectangle is equivalent to the @background_area passed to gtk_cell_renderer_render(). These background areas tile to cover the entire bin window. Contrast with the @cell_area, returned by gtk_tree_view_get_cell_area(), which returns only the cell itself, excluding surrounding borders and the tree expander area. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` a `GtkTreePath` for the row, or %NULL to get only horizontal coordinates a `GtkTreeViewColumn` for the column, or %NULL to get only vertical coordinates rectangle to fill with cell background rect Fills the bounding rectangle in bin_window coordinates for the cell at the row specified by @path and the column specified by @column. If @path is %NULL, or points to a path not currently displayed, the @y and @height fields of the rectangle will be filled with 0. If @column is %NULL, the @x and @width fields will be filled with 0. The sum of all cell rects does not cover the entire tree; there are extra pixels in between rows, for example. The returned rectangle is equivalent to the @cell_area passed to gtk_cell_renderer_render(). This function is only valid if @tree_view is realized. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` a `GtkTreePath` for the row, or %NULL to get only horizontal coordinates a `GtkTreeViewColumn` for the column, or %NULL to get only vertical coordinates rectangle to fill with cell rect Gets the `GtkTreeViewColumn` at the given position in the #tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The `GtkTreeViewColumn`, or %NULL if the position is outside the range of columns. A `GtkTreeView`. The position of the column, counting from 0. Returns a `GList` of all the `GtkTreeViewColumn`s currently in @tree_view. The returned list must be freed with g_list_free (). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A list of `GtkTreeViewColumn`s A `GtkTreeView` Fills in @path and @focus_column with the current path and focus column. If the cursor isn’t currently set, then *@path will be %NULL. If no column currently has focus, then *@focus_column will be %NULL. The returned `GtkTreePath` must be freed with gtk_tree_path_free() when you are done with it. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` A pointer to be filled with the current cursor path A pointer to be filled with the current focus column Determines the destination row for a given position. @drag_x and @drag_y are expected to be in widget coordinates. This function is only meaningful if @tree_view is realized. Therefore this function will always return %FALSE if @tree_view is not realized or does not have a model. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead whether there is a row at the given position, %TRUE if this is indeed the case. a `GtkTreeView` the position to determine the destination row for the position to determine the destination row for Return location for the path of the highlighted row Return location for the drop position, or %NULL Gets information about the row that is highlighted for feedback. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` Return location for the path of the highlighted row Return location for the drop position Returns whether or not the tree allows to start interactive searching by typing in text. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead whether or not to let the user search interactively A `GtkTreeView` Returns whether or not tree lines are drawn in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if tree lines are drawn in @tree_view, %FALSE otherwise. a `GtkTreeView`. Returns the column that is the current expander column, or %NULL if none has been set. This column has the expander arrow drawn next to it. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The expander column. A `GtkTreeView` Returns whether fixed height mode is turned on for @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if @tree_view is in fixed height mode a `GtkTreeView` Returns which grid lines are enabled in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView`GridLines value indicating which grid lines are enabled. a `GtkTreeView` Returns whether all header columns are clickable. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if all header columns are clickable, otherwise %FALSE A `GtkTreeView`. Returns %TRUE if the headers on the @tree_view are visible. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead Whether the headers are visible or not. A `GtkTreeView`. Returns whether hover expansion mode is turned on for @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if @tree_view is in hover expansion mode a `GtkTreeView` Returns whether hover selection mode is turned on for @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if @tree_view is in hover selection mode a `GtkTreeView` Returns the amount, in pixels, of extra indentation for child levels in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the amount of extra indentation for child levels in @tree_view. A return value of 0 means that this feature is disabled. a `GtkTreeView`. Returns the model the `GtkTreeView` is based on. Returns %NULL if the model is unset. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeModel` a `GtkTreeView` Queries the number of columns in the given @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The number of columns in the @tree_view a `GtkTreeView` Finds the path at the point (@x, @y), relative to bin_window coordinates. That is, @x and @y are relative to an events coordinates. Widget-relative coordinates must be converted using gtk_tree_view_convert_widget_to_bin_window_coords(). It is primarily for things like popup menus. If @path is non-%NULL, then it will be filled with the `GtkTreePath` at that point. This path should be freed with gtk_tree_path_free(). If @column is non-%NULL, then it will be filled with the column at that point. @cell_x and @cell_y return the coordinates relative to the cell background (i.e. the @background_area passed to gtk_cell_renderer_render()). This function is only meaningful if @tree_view is realized. Therefore this function will always return %FALSE if @tree_view is not realized or does not have a model. For converting widget coordinates (eg. the ones you get from GtkWidget::query-tooltip), please see gtk_tree_view_convert_widget_to_bin_window_coords(). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if a row exists at that coordinate. A `GtkTreeView`. The x position to be identified (relative to bin_window). The y position to be identified (relative to bin_window). A pointer to a `GtkTreePath` pointer to be filled in A pointer to a `GtkTreeViewColumn` pointer to be filled in A pointer where the X coordinate relative to the cell can be placed A pointer where the Y coordinate relative to the cell can be placed Retrieves whether the user can reorder the tree via drag-and-drop. See gtk_tree_view_set_reorderable(). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if the tree can be reordered. a `GtkTreeView` Returns the current row separator function. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the current row separator function. a `GtkTreeView` Returns whether rubber banding is turned on for @tree_view. If the selection mode is %GTK_SELECTION_MULTIPLE, rubber banding will allow the user to select multiple rows by dragging the mouse. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if rubber banding in @tree_view is enabled. a `GtkTreeView` Gets the column searched on by the interactive search code. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the column the interactive search code searches in. A `GtkTreeView` Returns the `GtkEntry` which is currently in use as interactive search entry for @tree_view. In case the built-in entry is being used, %NULL will be returned. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the entry currently in use as search entry. A `GtkTreeView` Returns the compare function currently in use. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the currently used compare function for the search code. A `GtkTreeView` Gets the `GtkTreeSelection` associated with @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeSelection` object. A `GtkTreeView`. Returns whether or not expanders are drawn in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if expanders are drawn in @tree_view, %FALSE otherwise. a `GtkTreeView`. Returns the column of @tree_view’s model which is being used for displaying tooltips on @tree_view’s rows. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead the index of the tooltip column that is currently being used, or -1 if this is disabled. a `GtkTreeView` This function is supposed to be used in a ::query-tooltip signal handler for `GtkTreeView`. The @x, @y and @keyboard_tip values which are received in the signal handler, should be passed to this function without modification. The return value indicates whether there is a tree view row at the given coordinates (%TRUE) or not (%FALSE) for mouse tooltips. For keyboard tooltips the row returned will be the cursor row. When %TRUE, then any of @model, @path and @iter which have been provided will be set to point to that row and the corresponding model. @x and @y will always be converted to be relative to @tree_view’s bin_window if @keyboard_tooltip is %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead whether or not the given tooltip context points to a row a `GtkTreeView` the x coordinate (relative to widget coordinates) the y coordinate (relative to widget coordinates) whether this is a keyboard tooltip or not a pointer to receive a `GtkTreeModel` a pointer to receive a `GtkTreePath` a pointer to receive a `GtkTreeIter` Sets @start_path and @end_path to be the first and last visible path. Note that there may be invisible paths in between. The paths should be freed with gtk_tree_path_free() after use. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE, if valid paths were placed in @start_path and @end_path. A `GtkTreeView` Return location for start of region Return location for end of region Fills @visible_rect with the currently-visible region of the buffer, in tree coordinates. Convert to bin_window coordinates with gtk_tree_view_convert_tree_to_bin_window_coords(). Tree coordinates start at 0,0 for row 0 of the tree, and cover the entire scrollable area of the tree. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` rectangle to fill This inserts the @column into the @tree_view at @position. If @position is -1, then the column is inserted at the end. If @tree_view has “fixed_height” mode enabled, then @column must have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The number of columns in @tree_view after insertion. A `GtkTreeView`. The `GtkTreeViewColumn` to be inserted. The position to insert @column in. Creates a new `GtkTreeViewColumn` and inserts it into the @tree_view at @position. If @position is -1, then the newly created column is inserted at the end. The column is initialized with the attributes given. If @tree_view has “fixed_height” mode enabled, then the new column will have its sizing property set to be GTK_TREE_VIEW_COLUMN_FIXED. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The number of columns in @tree_view after insertion. A `GtkTreeView` The position to insert the new column in The title to set the header to The `GtkCellRenderer` A %NULL-terminated list of attributes Convenience function that inserts a new column into the `GtkTreeView` with the given cell renderer and a `GtkTreeCellDataFunc` to set cell renderer attributes (normally using data from the model). See also gtk_tree_view_column_set_cell_data_func(), gtk_tree_view_column_pack_start(). If @tree_view has “fixed_height” mode enabled, then the new column will have its “sizing” property set to be GTK_TREE_VIEW_COLUMN_FIXED. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead number of columns in the tree view post-insert a `GtkTreeView` Position to insert, -1 for append column title cell renderer for column function to set attributes of cell renderer data for @func destroy notifier for @data Determine whether the point (@x, @y) in @tree_view is blank, that is no cell content nor an expander arrow is drawn at the location. If so, the location can be considered as the background. You might wish to take special action on clicks on the background, such as clearing a current selection, having a custom context menu or starting rubber banding. The @x and @y coordinate that are provided must be relative to bin_window coordinates. Widget-relative coordinates must be converted using gtk_tree_view_convert_widget_to_bin_window_coords(). For converting widget coordinates (eg. the ones you get from GtkWidget::query-tooltip), please see gtk_tree_view_convert_widget_to_bin_window_coords(). The @path, @column, @cell_x and @cell_y arguments will be filled in likewise as for gtk_tree_view_get_path_at_pos(). Please see gtk_tree_view_get_path_at_pos() for more information. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if the area at the given coordinates is blank, %FALSE otherwise. A `GtkTreeView` The x position to be identified (relative to bin_window) The y position to be identified (relative to bin_window) A pointer to a `GtkTreePath` pointer to be filled in A pointer to a `GtkTreeViewColumn` pointer to be filled in A pointer where the X coordinate relative to the cell can be placed A pointer where the Y coordinate relative to the cell can be placed Returns whether a rubber banding operation is currently being done in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if a rubber banding operation is currently being done in @tree_view. a `GtkTreeView` Calls @func on all expanded rows. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` A function to be called User data to be passed to the function. Moves @column to be after to @base_column. If @base_column is %NULL, then @column is placed in the first position. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` The `GtkTreeViewColumn` to be moved. The `GtkTreeViewColumn` to be moved relative to Removes @column from @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead The number of columns in @tree_view after removing. A `GtkTreeView`. The `GtkTreeViewColumn` to remove. Activates the cell determined by @path and @column. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` The `GtkTreePath` to be activated. The `GtkTreeViewColumn` to be activated. Returns %TRUE if the node pointed to by @path is expanded in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead %TRUE if #path is expanded. A `GtkTreeView`. A `GtkTreePath` to test expansion state. Moves the alignments of @tree_view to the position specified by @column and @path. If @column is %NULL, then no horizontal scrolling occurs. Likewise, if @path is %NULL no vertical scrolling occurs. At a minimum, one of @column or @path need to be non-%NULL. @row_align determines where the row is placed, and @col_align determines where @column is placed. Both are expected to be between 0.0 and 1.0. 0.0 means left/top alignment, 1.0 means right/bottom alignment, 0.5 means center. If @use_align is %FALSE, then the alignment arguments are ignored, and the tree does the minimum amount of work to scroll the cell onto the screen. This means that the cell will be scrolled to the edge closest to its current position. If the cell is currently visible on the screen, nothing is done. This function only works if the model is set, and @path is a valid row on the model. If the model changes before the @tree_view is realized, the centered path will be modified to reflect this change. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. The path of the row to move to The `GtkTreeViewColumn` to move horizontally to whether to use alignment arguments, or %FALSE. The vertical alignment of the row specified by @path. The horizontal alignment of the column specified by @column. Scrolls the tree view such that the top-left corner of the visible area is @tree_x, @tree_y, where @tree_x and @tree_y are specified in tree coordinates. The @tree_view must be realized before this function is called. If it isn't, you probably want to be using gtk_tree_view_scroll_to_cell(). If either @tree_x or @tree_y are -1, then that direction isn’t scrolled. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` X coordinate of new top-left pixel of visible area, or -1 Y coordinate of new top-left pixel of visible area, or -1 Cause the `GtkTreeView`::row-activated signal to be emitted on a single click instead of a double click. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to emit row-activated on a single click Sets a user function for determining where a column may be dropped when dragged. This function is called on every column pair in turn at the beginning of a column drag to determine where a drop can take place. The arguments passed to @func are: the @tree_view, the `GtkTreeViewColumn` being dragged, the two `GtkTreeViewColumn`s determining the drop spot, and @user_data. If either of the `GtkTreeViewColumn` arguments for the drop spot are %NULL, then they indicate an edge. If @func is set to be %NULL, then @tree_view reverts to the default behavior of allowing all columns to be dropped everywhere. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. A function to determine which columns are reorderable User data to be passed to @func Destroy notifier for @user_data Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular row. If @focus_column is not %NULL, then focus is given to the column specified by it. Additionally, if @focus_column is specified, and @start_editing is %TRUE, then editing should be started in the specified cell. This function is often followed by @gtk_widget_grab_focus (@tree_view) in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized. If @path is invalid for @model, the current cursor (if any) will be unset and the function will return without failing. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` A `GtkTreePath` A `GtkTreeViewColumn` %TRUE if the specified cell should start being edited. Sets the current keyboard focus to be at @path, and selects it. This is useful when you want to focus the user’s attention on a particular row. If @focus_column is not %NULL, then focus is given to the column specified by it. If @focus_column and @focus_cell are not %NULL, and @focus_column contains 2 or more editable or activatable cells, then focus is given to the cell specified by @focus_cell. Additionally, if @focus_column is specified, and @start_editing is %TRUE, then editing should be started in the specified cell. This function is often followed by @gtk_widget_grab_focus (@tree_view) in order to give keyboard focus to the widget. Please note that editing can only happen when the widget is realized. If @path is invalid for @model, the current cursor (if any) will be unset and the function will return without failing. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` A `GtkTreePath` A `GtkTreeViewColumn` A `GtkCellRenderer` %TRUE if the specified cell should start being edited. Sets the row that is highlighted for feedback. If @path is %NULL, an existing highlight is removed. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` The path of the row to highlight Specifies whether to drop before, after or into the row If @enable_search is set, then the user can type in text to search through the tree interactively (this is sometimes called "typeahead find"). Note that even if this is %FALSE, the user can still initiate a search using the “start-interactive-search” key binding. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` %TRUE, if the user can search interactively Sets whether to draw lines interconnecting the expanders in @tree_view. This does not have any visible effects for lists. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to enable tree line drawing, %FALSE otherwise. Sets the column to draw the expander arrow at. It must be in @tree_view. If @column is %NULL, then the expander arrow is always at the first visible column. If you do not want expander arrow to appear in your tree, set the expander column to a hidden column. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` %NULL, or the column to draw the expander arrow at. Enables or disables the fixed height mode of @tree_view. Fixed height mode speeds up `GtkTreeView` by assuming that all rows have the same height. Only enable this option if all rows are the same height and all columns are of type %GTK_TREE_VIEW_COLUMN_FIXED. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to enable fixed height mode Sets which grid lines to draw in @tree_view. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` a `GtkTreeView`GridLines value indicating which grid lines to enable. Allow the column title buttons to be clicked. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. %TRUE if the columns are clickable. Sets the visibility state of the headers. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. %TRUE if the headers are visible Enables or disables the hover expansion mode of @tree_view. Hover expansion makes rows expand or collapse if the pointer moves over them. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to enable hover selection mode Enables or disables the hover selection mode of @tree_view. Hover selection makes the selected row follow the pointer. Currently, this works only for the selection modes %GTK_SELECTION_SINGLE and %GTK_SELECTION_BROWSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to enable hover selection mode Sets the amount of extra indentation for child levels to use in @tree_view in addition to the default indentation. The value should be specified in pixels, a value of 0 disables this feature and in this case only the default indentation will be used. This does not have any visible effects for lists. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` the amount, in pixels, of extra indentation in @tree_view. Sets the model for a `GtkTreeView`. If the @tree_view already has a model set, it will remove it before setting the new model. If @model is %NULL, then it will unset the old model. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. The model. This function is a convenience function to allow you to reorder models that support the `GtkTreeDragSourceIface` and the `GtkTreeDragDestIface`. Both `GtkTreeStore` and `GtkListStore` support these. If @reorderable is %TRUE, then the user can reorder the model by dragging and dropping rows. The developer can listen to these changes by connecting to the model’s `GtkTreeModel::row-inserted` and `GtkTreeModel::row-deleted` signals. The reordering is implemented by setting up the tree view as a drag source and destination. Therefore, drag and drop can not be used in a reorderable view for any other purpose. This function does not give you any degree of control over the order -- any reordering is allowed. If more control is needed, you should probably handle drag and drop manually. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView`. %TRUE, if the tree can be reordered. Sets the row separator function, which is used to determine whether a row should be drawn as a separator. If the row separator function is %NULL, no separators are drawn. This is the default value. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` a `GtkTreeView`RowSeparatorFunc user data to pass to @func destroy notifier for @data Enables or disables rubber banding in @tree_view. If the selection mode is %GTK_SELECTION_MULTIPLE, rubber banding will allow the user to select multiple rows by dragging the mouse. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to enable rubber banding Sets @column as the column where the interactive search code should search in for the current model. If the search column is set, users can use the “start-interactive-search” key binding to bring up search popup. The enable-search property controls whether simply typing text will also start an interactive search. Note that @column refers to a column of the current model. The search column is reset to -1 when the model is changed. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` the column of the model to search in, or -1 to disable searching Sets the entry which the interactive search code will use for this @tree_view. This is useful when you want to provide a search entry in our interface at all time at a fixed position. Passing %NULL for @entry will make the interactive search code use the built-in popup entry again. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` the entry the interactive search code of @tree_view should use Sets the compare function for the interactive search capabilities; note that somewhat like strcmp() returning 0 for equality `GtkTreeView`SearchEqualFunc returns %FALSE on matches. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead A `GtkTreeView` the compare function to use during the search user data to pass to @search_equal_func Destroy notifier for @search_user_data Sets whether to draw and enable expanders and indent child rows in @tree_view. When disabled there will be no expanders visible in trees and there will be no way to expand and collapse rows by default. Also note that hiding the expanders will disable the default indentation. You can set a custom indentation in this case using gtk_tree_view_set_level_indentation(). This does not have any visible effects for lists. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` %TRUE to enable expander drawing, %FALSE otherwise. Sets the tip area of @tooltip to the area @path, @column and @cell have in common. For example if @path is %NULL and @column is set, the tip area will be set to the full area covered by @column. See also gtk_tooltip_set_tip_area(). Note that if @path is not specified and @cell is set and part of a column containing the expander, the tooltip might not show and hide at the correct position. In such cases @path must be set to the current node under the mouse cursor for this function to operate correctly. See also gtk_tree_view_set_tooltip_column() for a simpler alternative. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` a `GtkTooltip` a `GtkTreePath` a `GtkTreeViewColumn` a `GtkCellRenderer` If you only plan to have simple (text-only) tooltips on full rows, you can use this function to have `GtkTreeView` handle these automatically for you. @column should be set to the column in @tree_view’s model containing the tooltip texts, or -1 to disable this feature. When enabled, `GtkWidget:has-tooltip` will be set to %TRUE and @tree_view will connect a `GtkWidget::query-tooltip` signal handler. Note that the signal handler sets the text with gtk_tooltip_set_markup(), so &, <, etc have to be escaped in the text. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` an integer, which is a valid column number for @tree_view’s model Sets the tip area of @tooltip to be the area covered by the row at @path. See also gtk_tree_view_set_tooltip_column() for a simpler alternative. See also gtk_tooltip_set_tip_area(). Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` a `GtkTooltip` a `GtkTreePath` Undoes the effect of gtk_tree_view_enable_model_drag_dest(). Calling this method sets `GtkTreeView`:reorderable to %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` Undoes the effect of gtk_tree_view_enable_model_drag_source(). Calling this method sets `GtkTreeView`:reorderable to %FALSE. Use [class@Gtk.ListView] or [class@Gtk.ColumnView] instead a `GtkTreeView` The activate-on-single-click property specifies whether the "row-activated" signal will be emitted after a single click. Setting the ::fixed-height-mode property to %TRUE speeds up `GtkTreeView` by assuming that all rows have the same height. Only enable this option if all rows are the same height. Please see gtk_tree_view_set_fixed_height_mode() for more information on this option. Enables or disables the hover expansion mode of @tree_view. Hover expansion makes rows expand or collapse if the pointer moves over them. This mode is primarily intended for treeviews in popups, e.g. in `GtkComboBox` or `GtkEntryCompletion`. Enables or disables the hover selection mode of @tree_view. Hover selection makes the selected row follow the pointer. Currently, this works only for the selection modes %GTK_SELECTION_SINGLE and %GTK_SELECTION_BROWSE. This mode is primarily intended for treeviews in popups, e.g. in `GtkComboBox` or `GtkEntryCompletion`. Extra indentation for each level. %TRUE if the view has expanders. The number of columns of the treeview has changed. The position of the cursor (focused cell) has changed. The `GtkTreeView`::move-cursor signal is a [keybinding signal][class@Gtk.SignalAction] which gets emitted when the user presses one of the cursor keys. Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically. In contrast to gtk_tree_view_set_cursor() and gtk_tree_view_set_cursor_on_cell() when moving horizontally `GtkTreeView`::move-cursor does not reset the current selection. %TRUE if @step is supported, %FALSE otherwise. the granularity of the move, as a `GtkMovementStep`. %GTK_MOVEMENT_LOGICAL_POSITIONS, %GTK_MOVEMENT_VISUAL_POSITIONS, %GTK_MOVEMENT_DISPLAY_LINES, %GTK_MOVEMENT_PAGES and %GTK_MOVEMENT_BUFFER_ENDS are supported. %GTK_MOVEMENT_LOGICAL_POSITIONS and %GTK_MOVEMENT_VISUAL_POSITIONS are treated identically. the direction to move: +1 to move forwards; -1 to move backwards. The resulting movement is undefined for all other values. whether to extend the selection whether to modify the selection The "row-activated" signal is emitted when the method [method@Gtk.TreeView.row_activated] is called. This signal is emitted when the user double-clicks a treeview row with the [property@Gtk.TreeView:activate-on-single-click] property set to %FALSE, or when the user single-clicks a row when that property set to %TRUE. This signal is also emitted when a non-editable row is selected and one of the keys: <kbd>Space</kbd>, <kbd>Shift</kbd>+<kbd>Space</kbd>, <kbd>Return</kbd> or <kbd>Enter</kbd> is pressed. For selection handling refer to the [tree widget conceptual overview](section-tree-widget.html) as well as `GtkTreeSelection`. the `GtkTreePath` for the activated row the `GtkTreeViewColumn` in which the activation occurred The given row has been collapsed (child nodes are hidden). the tree iter of the collapsed row a tree path that points to the row The given row has been expanded (child nodes are shown). the tree iter of the expanded row a tree path that points to the row The given row is about to be collapsed (hide its children nodes). Use this signal if you need to control the collapsibility of individual rows. %FALSE to allow collapsing, %TRUE to reject the tree iter of the row to collapse a tree path that points to the row The given row is about to be expanded (show its children nodes). Use this signal if you need to control the expandability of individual rows. %FALSE to allow expansion, %TRUE to reject the tree iter of the row to expand a tree path that points to the row A `GtkTreeView` The `GtkTreePath` to be activated. The `GtkTreeViewColumn` to be activated. A visible column in a [class@Gtk.TreeView] widget The `GtkTreeViewColumn` object represents a visible column in a `GtkTreeView` widget. It allows to set properties of the column header, and functions as a holding pen for the cell renderers which determine how the data in the column is displayed. Please refer to the [tree widget conceptual overview](section-tree-widget.html) for an overview of all the objects and data types related to the tree widget and how they work together, and to the [class@Gtk.TreeView] documentation for specifics about the CSS node structure for treeviews and their headers. Use [class@Gtk.ColumnView] and [class@Gtk.ColumnViewColumn] instead of [class@Gtk.TreeView] to show a tabular list Creates a new `GtkTreeViewColumn`. Use GtkColumnView instead A newly created `GtkTreeViewColumn`. Creates a new `GtkTreeViewColumn` using @area to render its cells. Use GtkColumnView instead A newly created `GtkTreeViewColumn`. the `GtkCellArea` that the newly created column should use to layout cells. Creates a new `GtkTreeViewColumn` with a number of default values. This is equivalent to calling gtk_tree_view_column_set_title(), gtk_tree_view_column_pack_start(), and gtk_tree_view_column_set_attributes() on the newly created `GtkTreeViewColumn`. Here’s a simple example: |[<!-- language="C" --> enum { TEXT_COLUMN, COLOR_COLUMN, N_COLUMNS }; // ... { GtkTreeViewColumn *column; GtkCellRenderer *renderer = gtk_cell_renderer_text_new (); column = gtk_tree_view_column_new_with_attributes ("Title", renderer, "text", TEXT_COLUMN, "foreground", COLOR_COLUMN, NULL); } ]| Use GtkColumnView instead A newly created `GtkTreeViewColumn`. The title to set the header to The `GtkCellRenderer` A %NULL-terminated list of attributes Adds an attribute mapping to the list in @tree_column. The @column is the column of the model to get a value from, and the @attribute is the parameter on @cell_renderer to be set from the value. So for example if column 2 of the model contains strings, you could have the “text” attribute of a `GtkCellRendererText` get its values from column 2. Use GtkColumnView instead A `GtkTreeViewColumn` the `GtkCellRenderer` to set attributes on An attribute on the renderer The column position on the model to get the attribute from. Obtains the horizontal position and size of a cell in a column. If the cell is not found in the column, @start_pos and @width are not changed and %FALSE is returned. Use GtkColumnView instead %TRUE if @cell belongs to @tree_column a `GtkTreeViewColumn` a `GtkCellRenderer` return location for the horizontal position of @cell within @tree_column return location for the width of @cell Obtains the width and height needed to render the column. This is used primarily by the `GtkTreeView`. Use GtkColumnView instead A `GtkTreeViewColumn`. location to return x offset of a cell relative to @cell_area location to return y offset of a cell relative to @cell_area location to return width needed to render a cell location to return height needed to render a cell Returns %TRUE if any of the cells packed into the @tree_column are visible. For this to be meaningful, you must first initialize the cells with gtk_tree_view_column_cell_set_cell_data() Use GtkColumnView instead %TRUE, if any of the cells packed into the @tree_column are currently visible A `GtkTreeViewColumn` Sets the cell renderer based on the @tree_model and @iter. That is, for every attribute mapping in @tree_column, it will get a value from the set column on the @iter, and use that value to set the attribute on the cell renderer. This is used primarily by the `GtkTreeView`. Use GtkColumnView instead A `GtkTreeViewColumn`. The `GtkTreeModel` to get the cell renderers attributes from. The `GtkTreeIter` to get the cell renderer’s attributes from. %TRUE, if the row has children %TRUE, if the row has visible children Unsets all the mappings on all renderers on the @tree_column. Use GtkColumnView instead A `GtkTreeViewColumn` Clears all existing attributes previously set with gtk_tree_view_column_set_attributes(). Use GtkColumnView instead a `GtkTreeViewColumn` a `GtkCellRenderer` to clear the attribute mapping on. Emits the “clicked” signal on the column. This function will only work if @tree_column is clickable. Use GtkColumnView instead a `GtkTreeViewColumn` Sets the current keyboard focus to be at @cell, if the column contains 2 or more editable and activatable cells. Use GtkColumnView instead A `GtkTreeViewColumn` A `GtkCellRenderer` Returns the current x alignment of @tree_column. This value can range between 0.0 and 1.0. Use GtkColumnView instead The current alignent of @tree_column. A `GtkTreeViewColumn`. Returns the button used in the treeview column header Use GtkColumnView instead The button for the column header. A `GtkTreeViewColumn` Returns %TRUE if the user can click on the header for the column. Use GtkColumnView instead %TRUE if user can click the column header. a `GtkTreeViewColumn` Returns %TRUE if the column expands to fill available space. Use GtkColumnView instead %TRUE if the column expands to fill available space. A `GtkTreeViewColumn`. Gets the fixed width of the column. This may not be the actual displayed width of the column; for that, use gtk_tree_view_column_get_width(). Use GtkColumnView instead The fixed width of the column. A `GtkTreeViewColumn`. Returns the maximum width in pixels of the @tree_column, or -1 if no maximum width is set. Use GtkColumnView instead The maximum width of the @tree_column. A `GtkTreeViewColumn`. Returns the minimum width in pixels of the @tree_column, or -1 if no minimum width is set. Use GtkColumnView instead The minimum width of the @tree_column. A `GtkTreeViewColumn`. Returns %TRUE if the @tree_column can be reordered by the user. Use GtkColumnView instead %TRUE if the @tree_column can be reordered by the user. A `GtkTreeViewColumn` Returns %TRUE if the @tree_column can be resized by the end user. Use GtkColumnView instead %TRUE, if the @tree_column can be resized. A `GtkTreeViewColumn` Returns the current type of @tree_column. Use GtkColumnView instead The type of @tree_column. A `GtkTreeViewColumn`. Gets the logical @sort_column_id that the model sorts on when this column is selected for sorting. See [method@Gtk.TreeViewColumn.set_sort_column_id]. Use GtkColumnView instead the current @sort_column_id for this column, or -1 if this column can’t be used for sorting a `GtkTreeViewColumn` Gets the value set by gtk_tree_view_column_set_sort_indicator(). Use GtkColumnView instead whether the sort indicator arrow is displayed a `GtkTreeViewColumn` Gets the value set by gtk_tree_view_column_set_sort_order(). Use GtkColumnView instead the sort order the sort indicator is indicating a `GtkTreeViewColumn` Returns the spacing of @tree_column. Use GtkColumnView instead the spacing of @tree_column. A `GtkTreeViewColumn`. Returns the title of the widget. Use GtkColumnView instead the title of the column. This string should not be modified or freed. A `GtkTreeViewColumn`. Returns the `GtkTreeView` wherein @tree_column has been inserted. If @column is currently not inserted in any tree view, %NULL is returned. Use GtkColumnView instead The tree view wherein @column has been inserted A `GtkTreeViewColumn` Returns %TRUE if @tree_column is visible. Use GtkColumnView instead whether the column is visible or not. If it is visible, then the tree will show the column. A `GtkTreeViewColumn`. Returns the `GtkWidget` in the button on the column header. If a custom widget has not been set then %NULL is returned. Use GtkColumnView instead The `GtkWidget` in the column header A `GtkTreeViewColumn` Returns the current size of @tree_column in pixels. Use GtkColumnView instead The current width of @tree_column. A `GtkTreeViewColumn`. Returns the current X offset of @tree_column in pixels. Use GtkColumnView instead The current X offset of @tree_column. A `GtkTreeViewColumn`. Adds the @cell to end of the column. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Use GtkColumnView instead A `GtkTreeViewColumn`. The `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @tree_column. Packs the @cell into the beginning of the column. If @expand is %FALSE, then the @cell is allocated no more space than it needs. Any unused space is divided evenly between cells for which @expand is %TRUE. Use GtkColumnView instead A `GtkTreeViewColumn`. The `GtkCellRenderer` %TRUE if @cell is to be given extra space allocated to @tree_column. Flags the column, and the cell renderers added to this column, to have their sizes renegotiated. Use GtkColumnView instead A `GtkTreeViewColumn` Sets the alignment of the title or custom widget inside the column header. The alignment determines its location inside the button -- 0.0 for left, 0.5 for center, 1.0 for right. Use GtkColumnView instead A `GtkTreeViewColumn`. The alignment, which is between [0.0 and 1.0] inclusive. Sets the attributes in the list as the attributes of @tree_column. The attributes should be in attribute/column order, as in gtk_tree_view_column_add_attribute(). All existing attributes are removed, and replaced with the new attributes. Use GtkColumnView instead A `GtkTreeViewColumn` the `GtkCellRenderer` we’re setting the attributes of A %NULL-terminated list of attributes Sets the `GtkTreeCellDataFunc` to use for the column. This function is used instead of the standard attributes mapping for setting the column value, and should set the value of @tree_column's cell renderer as appropriate. @func may be %NULL to remove an older one. Use GtkColumnView instead A `GtkTreeViewColumn` A `GtkCellRenderer` The `GtkTreeCellDataFunc` to use. The user data for @func. The destroy notification for @func_data Sets the header to be active if @clickable is %TRUE. When the header is active, then it can take keyboard focus, and can be clicked. Use GtkColumnView instead A `GtkTreeViewColumn`. %TRUE if the header is active. Sets the column to take available extra space. This space is shared equally amongst all columns that have the expand set to %TRUE. If no column has this option set, then the last column gets all extra space. By default, every column is created with this %FALSE. Along with “fixed-width”, the “expand” property changes when the column is resized by the user. Use GtkColumnView instead A `GtkTreeViewColumn`. %TRUE if the column should expand to fill available space. If @fixed_width is not -1, sets the fixed width of @tree_column; otherwise unsets it. The effective value of @fixed_width is clamped between the minimum and maximum width of the column; however, the value stored in the “fixed-width” property is not clamped. If the column sizing is %GTK_TREE_VIEW_COLUMN_GROW_ONLY or %GTK_TREE_VIEW_COLUMN_AUTOSIZE, setting a fixed width overrides the automatically calculated width. Note that @fixed_width is only a hint to GTK; the width actually allocated to the column may be greater or less than requested. Along with “expand”, the “fixed-width” property changes when the column is resized by the user. Use GtkColumnView instead A `GtkTreeViewColumn`. The new fixed width, in pixels, or -1. Sets the maximum width of the @tree_column. If @max_width is -1, then the maximum width is unset. Note, the column can actually be wider than max width if it’s the last column in a view. In this case, the column expands to fill any extra space. Use GtkColumnView instead A `GtkTreeViewColumn`. The maximum width of the column in pixels, or -1. Sets the minimum width of the @tree_column. If @min_width is -1, then the minimum width is unset. Use GtkColumnView instead A `GtkTreeViewColumn`. The minimum width of the column in pixels, or -1. If @reorderable is %TRUE, then the column can be reordered by the end user dragging the header. Use GtkColumnView instead A `GtkTreeViewColumn` %TRUE, if the column can be reordered. If @resizable is %TRUE, then the user can explicitly resize the column by grabbing the outer edge of the column button. If resizable is %TRUE and sizing mode of the column is %GTK_TREE_VIEW_COLUMN_AUTOSIZE, then the sizing mode is changed to %GTK_TREE_VIEW_COLUMN_GROW_ONLY. Use GtkColumnView instead A `GtkTreeViewColumn` %TRUE, if the column can be resized Sets the growth behavior of @tree_column to @type. Use GtkColumnView instead A `GtkTreeViewColumn`. The `GtkTreeViewColumn`Sizing. Sets the logical @sort_column_id that this column sorts on when this column is selected for sorting. Doing so makes the column header clickable. Use GtkColumnView instead a `GtkTreeViewColumn` The @sort_column_id of the model to sort on. Call this function with a @setting of %TRUE to display an arrow in the header button indicating the column is sorted. Call gtk_tree_view_column_set_sort_order() to change the direction of the arrow. Use GtkColumnView instead a `GtkTreeViewColumn` %TRUE to display an indicator that the column is sorted Changes the appearance of the sort indicator. This does not actually sort the model. Use gtk_tree_view_column_set_sort_column_id() if you want automatic sorting support. This function is primarily for custom sorting behavior, and should be used in conjunction with gtk_tree_sortable_set_sort_column_id() to do that. For custom models, the mechanism will vary. The sort indicator changes direction to indicate normal sort or reverse sort. Note that you must have the sort indicator enabled to see anything when calling this function; see gtk_tree_view_column_set_sort_indicator(). Use GtkColumnView instead a `GtkTreeViewColumn` sort order that the sort indicator should indicate Sets the spacing field of @tree_column, which is the number of pixels to place between cell renderers packed into it. Use GtkColumnView instead A `GtkTreeViewColumn`. distance between cell renderers in pixels. Sets the title of the @tree_column. If a custom widget has been set, then this value is ignored. Use GtkColumnView instead A `GtkTreeViewColumn`. The title of the @tree_column. Sets the visibility of @tree_column. Use GtkColumnView instead A `GtkTreeViewColumn`. %TRUE if the @tree_column is visible. Sets the widget in the header to be @widget. If widget is %NULL, then the header button is set with a `GtkLabel` set to the title of @tree_column. Use GtkColumnView instead A `GtkTreeViewColumn`. A child `GtkWidget` The `GtkCellArea` used to layout cell renderers for this column. If no area is specified when creating the tree view column with gtk_tree_view_column_new_with_area() a horizontally oriented `GtkCellAreaBox` will be used. Logical sort column ID this column sorts on when selected for sorting. Setting the sort column ID makes the column header clickable. Set to -1 to make the column unsortable. Emitted when the column's header has been clicked. Function type for determining whether @column can be dropped in a particular spot (as determined by @prev_column and @next_column). In left to right locales, @prev_column is on the left of the potential drop spot, and @next_column is on the right. In right to left mode, this is reversed. This function should return %TRUE if the spot is a valid drop spot. Please note that returning %TRUE does not actually indicate that the column drop was made, but is meant only to indicate a possible drop spot to the user. %TRUE, if @column can be dropped in this spot A `GtkTreeView` The `GtkTreeViewColumn` being dragged A `GtkTreeViewColumn` on one side of @column A `GtkTreeViewColumn` on the other side of @column user data The sizing method the column uses to determine its width. Please note that %GTK_TREE_VIEW_COLUMN_AUTOSIZE are inefficient for large views, and can make columns appear choppy. Columns only get bigger in reaction to changes in the model Columns resize to be the optimal size every time the model changes. Columns are a fixed numbers of pixels wide. An enum for determining where a dropped row goes. dropped row is inserted before dropped row is inserted after dropped row becomes a child or is inserted before dropped row becomes a child or is inserted after Used to indicate which grid lines to draw in a tree view. No grid lines. Horizontal grid lines. Vertical grid lines. Horizontal and vertical grid lines. Function used for gtk_tree_view_map_expanded_rows(). A `GtkTreeView` The path that’s expanded user data Function type for determining whether the row pointed to by @iter should be rendered as a separator. A common way to implement this is to have a boolean column in the model, whose values the `GtkTreeViewRowSeparatorFunc` returns. %TRUE if the row is a separator the `GtkTreeModel` a `GtkTreeIter` pointing at a row in @model user data A function used for checking whether a row in @model matches a search key string entered by the user. Note the return value is reversed from what you would normally expect, though it has some similarity to strcmp() returning 0 for equal strings. %FALSE if the row matches, %TRUE otherwise. the `GtkTreeModel` being searched the search column set by gtk_tree_view_set_search_column() the key string to compare with a `GtkTreeIter` pointing the row of @model that should be compared with @key. user data from gtk_tree_view_set_search_equal_func() See also gtk_print_settings_set_paper_width(). No units. Dimensions in points. Dimensions in inches. Dimensions in millimeters A `GtkUriLauncher` object collects the arguments that are needed to open a uri with an application. Depending on system configuration, user preferences and available APIs, this may or may not show an app chooser dialog or launch the default application right away. The operation is started with the [method@Gtk.UriLauncher.launch] function. To launch a file, use [class@Gtk.FileLauncher]. Creates a new `GtkUriLauncher` object. the new `GtkUriLauncher` the uri to open Gets the uri that will be opened. the uri a `GtkUriLauncher` Launch an application to open the uri. This may present an app chooser dialog to the user. a `GtkUriLauncher` the parent `GtkWindow` a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@Gtk.UriLauncher.launch] call and returns the result. `TRUE` if an application was launched, or `FALSE` and @error is set a `GtkUriLauncher` a `GAsyncResult` Sets the uri that will be opened. a `GtkUriLauncher` the uri The uri to launch. Evaluates to %TRUE if @value was initialized with %GTK_TYPE_EXPRESSION. a `GValue` `GtkVideo` is a widget to show a `GtkMediaStream` with media controls.  The controls are available separately as [class@Gtk.MediaControls]. If you just want to display a video without controls, you can treat it like any other paintable and for example put it into a [class@Gtk.Picture]. `GtkVideo` aims to cover use cases such as previews, embedded animations, etc. It supports autoplay, looping, and simple media controls. It does not have support for video overlays, multichannel audio, device selection, or input. If you are writing a full-fledged video player, you may want to use the [iface@Gdk.Paintable] API and a media framework such as Gstreamer directly. Creates a new empty `GtkVideo`. a new `GtkVideo` Creates a `GtkVideo` to play back the given @file. a new `GtkVideo` a `GFile` Creates a `GtkVideo` to play back the given @filename. This is a utility function that calls [ctor@Gtk.Video.new_for_file], See that function for details. a new `GtkVideo` filename to play back Creates a `GtkVideo` to play back the given @stream. a new `GtkVideo` a `GtkMediaStream` Creates a `GtkVideo` to play back the resource at the given @resource_path. This is a utility function that calls [ctor@Gtk.Video.new_for_file]. a new `GtkVideo` resource path to play back Returns %TRUE if videos have been set to loop. %TRUE if streams should autoplay a `GtkVideo` Gets the file played by @self or %NULL if not playing back a file. The file played by @self a `GtkVideo` Returns whether graphics offload is enabled. See [class@Gtk.GraphicsOffload] for more information on graphics offload. the graphics offload status a `GtkVideo` Returns %TRUE if videos have been set to loop. %TRUE if streams should loop a `GtkVideo` Gets the media stream managed by @self or %NULL if none. The media stream managed by @self a `GtkVideo` Sets whether @self automatically starts playback when it becomes visible or when a new file gets loaded. a `GtkVideo` whether media streams should autoplay Makes @self play the given @file. a `GtkVideo` the file to play Makes @self play the given @filename. This is a utility function that calls gtk_video_set_file(), a `GtkVideo` the filename to play Sets whether to enable graphics offload. See [class@Gtk.GraphicsOffload] for more information on graphics offload. a `GtkVideo` the new graphics offload status Sets whether new files loaded by @self should be set to loop. a `GtkVideo` whether media streams should loop Sets the media stream to be played back. @self will take full control of managing the media stream. If you want to manage a media stream yourself, consider using a [class@Gtk.Picture] for display. If you want to display a file, consider using [method@Gtk.Video.set_file] instead. a `GtkVideo` The media stream to play or %NULL to unset Makes @self play the resource at the given @resource_path. This is a utility function that calls [method@Gtk.Video.set_file]. a `GtkVideo` the resource to set If the video should automatically begin playing. The file played by this video if the video is playing a file. Whether to enable graphics offload. If new media files should be set to loop. The media-stream played `GtkViewport` implements scrollability for widgets that lack their own scrolling capabilities. Use `GtkViewport` to scroll child widgets such as `GtkGrid`, `GtkBox`, and so on. The `GtkViewport` will start scrolling content only if allocated less than the child widget’s minimum size in a given orientation. # CSS nodes `GtkViewport` has a single CSS node with name `viewport`. # Accessibility Until GTK 4.10, `GtkViewport` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. Starting from GTK 4.12, `GtkViewport` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. Creates a new `GtkViewport`. The new viewport uses the given adjustments, or default adjustments if none are given. a new `GtkViewport` horizontal adjustment vertical adjustment Gets the child widget of @viewport. the child widget of @viewport a `GtkViewport` Gets whether the viewport is scrolling to keep the focused child in view. %TRUE if the viewport keeps the focus child scrolled to view a `GtkViewport` Scrolls a descendant of the viewport into view. The viewport and the descendant must be visible and mapped for this function to work, otherwise no scrolling will be performed. a `GtkViewport` a descendant widget of the viewport details of how to perform the scroll operation or NULL to scroll into view Sets the child widget of @viewport. a `GtkViewport` the child widget Sets whether the viewport should automatically scroll to keep the focused child in view. a `GtkViewport` whether to keep the focus widget scrolled to view The child widget. Whether to scroll when the focus changes. Before 4.6.2, this property was mistakenly defaulting to FALSE, so if your code needs to work with older versions, consider setting it explicitly to TRUE. `GtkVolumeButton` is a `GtkScaleButton` subclass tailored for volume control.  This widget will be removed in GTK 5 Creates a `GtkVolumeButton`. The button has a range between 0.0 and 1.0, with a stepping of 0.02. Volume values can be obtained and modified using the functions from [class@Gtk.ScaleButton]. This widget will be removed in GTK 5 a new `GtkVolumeButton` Whether to use symbolic icons as the icons. Note that if the symbolic icons are not available in your installed theme, then the normal (potentially colorful) icons will be used. This widget will be removed in GTK 5 The base class for all widgets. `GtkWidget` is the base class all widgets in GTK derive from. It manages the widget lifecycle, layout, states and style. ### Height-for-width Geometry Management GTK uses a height-for-width (and width-for-height) geometry management system. Height-for-width means that a widget can change how much vertical space it needs, depending on the amount of horizontal space that it is given (and similar for width-for-height). The most common example is a label that reflows to fill up the available width, wraps to fewer lines, and therefore needs less height. Height-for-width geometry management is implemented in GTK by way of two virtual methods: - [vfunc@Gtk.Widget.get_request_mode] - [vfunc@Gtk.Widget.measure] There are some important things to keep in mind when implementing height-for-width and when using it in widget implementations. If you implement a direct `GtkWidget` subclass that supports height-for-width or width-for-height geometry management for itself or its child widgets, the [vfunc@Gtk.Widget.get_request_mode] virtual function must be implemented as well and return the widget's preferred request mode. The default implementation of this virtual function returns %GTK_SIZE_REQUEST_CONSTANT_SIZE, which means that the widget will only ever get -1 passed as the for_size value to its [vfunc@Gtk.Widget.measure] implementation. The geometry management system will query a widget hierarchy in only one orientation at a time. When widgets are initially queried for their minimum sizes it is generally done in two initial passes in the [enum@Gtk.SizeRequestMode] chosen by the toplevel. For example, when queried in the normal %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH mode: First, the default minimum and natural width for each widget in the interface will be computed using [method@Gtk.Widget.measure] with an orientation of %GTK_ORIENTATION_HORIZONTAL and a for_size of -1. Because the preferred widths for each widget depend on the preferred widths of their children, this information propagates up the hierarchy, and finally a minimum and natural width is determined for the entire toplevel. Next, the toplevel will use the minimum width to query for the minimum height contextual to that width using [method@Gtk.Widget.measure] with an orientation of %GTK_ORIENTATION_VERTICAL and a for_size of the just computed width. This will also be a highly recursive operation. The minimum height for the minimum width is normally used to set the minimum size constraint on the toplevel. After the toplevel window has initially requested its size in both dimensions it can go on to allocate itself a reasonable size (or a size previously specified with [method@Gtk.Window.set_default_size]). During the recursive allocation process it’s important to note that request cycles will be recursively executed while widgets allocate their children. Each widget, once allocated a size, will go on to first share the space in one orientation among its children and then request each child's height for its target allocated width or its width for allocated height, depending. In this way a `GtkWidget` will typically be requested its size a number of times before actually being allocated a size. The size a widget is finally allocated can of course differ from the size it has requested. For this reason, `GtkWidget` caches a small number of results to avoid re-querying for the same sizes in one allocation cycle. If a widget does move content around to intelligently use up the allocated size then it must support the request in both `GtkSizeRequestMode`s even if the widget in question only trades sizes in a single orientation. For instance, a [class@Gtk.Label] that does height-for-width word wrapping will not expect to have [vfunc@Gtk.Widget.measure] with an orientation of %GTK_ORIENTATION_VERTICAL called because that call is specific to a width-for-height request. In this case the label must return the height required for its own minimum possible width. By following this rule any widget that handles height-for-width or width-for-height requests will always be allocated at least enough space to fit its own content. Here are some examples of how a %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH widget generally deals with width-for-height requests: ```c static void foo_widget_measure (GtkWidget *widget, GtkOrientation orientation, int for_size, int *minimum_size, int *natural_size, int *minimum_baseline, int *natural_baseline) { if (orientation == GTK_ORIENTATION_HORIZONTAL) { // Calculate minimum and natural width } else // VERTICAL { if (i_am_in_height_for_width_mode) { int min_width, dummy; // First, get the minimum width of our widget GTK_WIDGET_GET_CLASS (widget)->measure (widget, GTK_ORIENTATION_HORIZONTAL, -1, &min_width, &dummy, &dummy, &dummy); // Now use the minimum width to retrieve the minimum and natural height to display // that width. GTK_WIDGET_GET_CLASS (widget)->measure (widget, GTK_ORIENTATION_VERTICAL, min_width, minimum_size, natural_size, &dummy, &dummy); } else { // ... some widgets do both. } } } ``` Often a widget needs to get its own request during size request or allocation. For example, when computing height it may need to also compute width. Or when deciding how to use an allocation, the widget may need to know its natural size. In these cases, the widget should be careful to call its virtual methods directly, like in the code example above. It will not work to use the wrapper function [method@Gtk.Widget.measure] inside your own [vfunc@Gtk.Widget.size_allocate] implementation. These return a request adjusted by [class@Gtk.SizeGroup], the widget's align and expand flags, as well as its CSS style. If a widget used the wrappers inside its virtual method implementations, then the adjustments (such as widget margins) would be applied twice. GTK therefore does not allow this and will warn if you try to do it. Of course if you are getting the size request for another widget, such as a child widget, you must use [method@Gtk.Widget.measure]; otherwise, you would not properly consider widget margins, [class@Gtk.SizeGroup], and so forth. GTK also supports baseline vertical alignment of widgets. This means that widgets are positioned such that the typographical baseline of widgets in the same row are aligned. This happens if a widget supports baselines, has a vertical alignment using baselines, and is inside a widget that supports baselines and has a natural “row” that it aligns to the baseline, or a baseline assigned to it by the grandparent. Baseline alignment support for a widget is also done by the [vfunc@Gtk.Widget.measure] virtual function. It allows you to report both a minimum and natural size. If a widget ends up baseline aligned it will be allocated all the space in the parent as if it was %GTK_ALIGN_FILL, but the selected baseline can be found via [method@Gtk.Widget.get_baseline]. If the baseline has a value other than -1 you need to align the widget such that the baseline appears at the position. ### GtkWidget as GtkBuildable The `GtkWidget` implementation of the `GtkBuildable` interface supports various custom elements to specify additional aspects of widgets that are not directly expressed as properties. If the widget uses a [class@Gtk.LayoutManager], `GtkWidget` supports a custom `<layout>` element, used to define layout properties: ```xml <object class="GtkGrid" id="my_grid"> <child> <object class="GtkLabel" id="label1"> <property name="label">Description</property> <layout> <property name="column">0</property> <property name="row">0</property> <property name="row-span">1</property> <property name="column-span">1</property> </layout> </object> </child> <child> <object class="GtkEntry" id="description_entry"> <layout> <property name="column">1</property> <property name="row">0</property> <property name="row-span">1</property> <property name="column-span">1</property> </layout> </object> </child> </object> ``` `GtkWidget` allows style information such as style classes to be associated with widgets, using the custom `<style>` element: ```xml <object class="GtkButton" id="button1"> <style> <class name="my-special-button-class"/> <class name="dark-button"/> </style> </object> ``` `GtkWidget` allows defining accessibility information, such as properties, relations, and states, using the custom `<accessibility>` element: ```xml <object class="GtkButton" id="button1"> <accessibility> <property name="label">Download</property> <relation name="labelled-by">label1</relation> </accessibility> </object> ``` ### Building composite widgets from template XML `GtkWidget `exposes some facilities to automate the procedure of creating composite widgets using "templates". To create composite widgets with `GtkBuilder` XML, one must associate the interface description with the widget class at class initialization time using [method@Gtk.WidgetClass.set_template]. The interface description semantics expected in composite template descriptions is slightly different from regular [class@Gtk.Builder] XML. Unlike regular interface descriptions, [method@Gtk.WidgetClass.set_template] will expect a `<template>` tag as a direct child of the toplevel `<interface>` tag. The `<template>` tag must specify the “class” attribute which must be the type name of the widget. Optionally, the “parent” attribute may be specified to specify the direct parent type of the widget type; this is ignored by `GtkBuilder` but can be used by UI design tools to introspect what kind of properties and internal children exist for a given type when the actual type does not exist. The XML which is contained inside the `<template>` tag behaves as if it were added to the `<object>` tag defining the widget itself. You may set properties on a widget by inserting `<property>` tags into the `<template>` tag, and also add `<child>` tags to add children and extend a widget in the normal way you would with `<object>` tags. Additionally, `<object>` tags can also be added before and after the initial `<template>` tag in the normal way, allowing one to define auxiliary objects which might be referenced by other widgets declared as children of the `<template>` tag. Since, unlike the `<object>` tag, the `<template>` tag does not contain an “id” attribute, if you need to refer to the instance of the object itself that the template will create, simply refer to the template class name in an applicable element content. Here is an example of a template definition, which includes an example of this in the `<signal>` tag: ```xml <interface> <template class="FooWidget" parent="GtkBox"> <property name="orientation">horizontal</property> <property name="spacing">4</property> <child> <object class="GtkButton" id="hello_button"> <property name="label">Hello World</property> <signal name="clicked" handler="hello_button_clicked" object="FooWidget" swapped="yes"/> </object> </child> <child> <object class="GtkButton" id="goodbye_button"> <property name="label">Goodbye World</property> </object> </child> </template> </interface> ``` Typically, you'll place the template fragment into a file that is bundled with your project, using `GResource`. In order to load the template, you need to call [method@Gtk.WidgetClass.set_template_from_resource] from the class initialization of your `GtkWidget` type: ```c static void foo_widget_class_init (FooWidgetClass *klass) { // ... gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass), "/com/example/ui/foowidget.ui"); } ``` You will also need to call [method@Gtk.Widget.init_template] from the instance initialization function: ```c static void foo_widget_init (FooWidget *self) { gtk_widget_init_template (GTK_WIDGET (self)); // Initialize the rest of the widget... } ``` as well as calling [method@Gtk.Widget.dispose_template] from the dispose function: ```c static void foo_widget_dispose (GObject *gobject) { FooWidget *self = FOO_WIDGET (gobject); // Dispose objects for which you have a reference... // Clear the template children for this widget type gtk_widget_dispose_template (GTK_WIDGET (self), FOO_TYPE_WIDGET); G_OBJECT_CLASS (foo_widget_parent_class)->dispose (gobject); } ``` You can access widgets defined in the template using the [method@Gtk.Widget.get_template_child] function, but you will typically declare a pointer in the instance private data structure of your type using the same name as the widget in the template definition, and call [method@Gtk.WidgetClass.bind_template_child_full] (or one of its wrapper macros [func@Gtk.widget_class_bind_template_child] and [func@Gtk.widget_class_bind_template_child_private]) with that name, e.g. ```c typedef struct { GtkWidget *hello_button; GtkWidget *goodbye_button; } FooWidgetPrivate; G_DEFINE_TYPE_WITH_PRIVATE (FooWidget, foo_widget, GTK_TYPE_BOX) static void foo_widget_dispose (GObject *gobject) { gtk_widget_dispose_template (GTK_WIDGET (gobject), FOO_TYPE_WIDGET); G_OBJECT_CLASS (foo_widget_parent_class)->dispose (gobject); } static void foo_widget_class_init (FooWidgetClass *klass) { // ... G_OBJECT_CLASS (klass)->dispose = foo_widget_dispose; gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass), "/com/example/ui/foowidget.ui"); gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (klass), FooWidget, hello_button); gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (klass), FooWidget, goodbye_button); } static void foo_widget_init (FooWidget *widget) { gtk_widget_init_template (GTK_WIDGET (widget)); } ``` You can also use [method@Gtk.WidgetClass.bind_template_callback_full] (or is wrapper macro [func@Gtk.widget_class_bind_template_callback]) to connect a signal callback defined in the template with a function visible in the scope of the class, e.g. ```c // the signal handler has the instance and user data swapped // because of the swapped="yes" attribute in the template XML static void hello_button_clicked (FooWidget *self, GtkButton *button) { g_print ("Hello, world!\n"); } static void foo_widget_class_init (FooWidgetClass *klass) { // ... gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass), "/com/example/ui/foowidget.ui"); gtk_widget_class_bind_template_callback (GTK_WIDGET_CLASS (klass), hello_button_clicked); } ``` Obtains the current default reading direction. See [func@Gtk.Widget.set_default_direction]. the current default direction. Sets the default reading direction for widgets. See [method@Gtk.Widget.set_direction]. the new default direction. This cannot be %GTK_TEXT_DIR_NONE. Computes whether a container should give this widget extra space when possible. Tests if the point at (@x, @y) is contained in @widget. The coordinates for (@x, @y) must be in widget coordinates, so (0, 0) is assumed to be the top left of @widget's content area. %TRUE if @widget contains (@x, @y). the widget to query X coordinate to test, relative to @widget's origin Y coordinate to test, relative to @widget's origin Vfunc called when the CSS used by widget was changed. Widgets should then discard their caches that depend on CSS and queue resizes or redraws accordingly. The default implementation will take care of this for all the default CSS properties, so implementations must chain up. Signal emitted when the text direction of a widget changes. Vfunc for gtk_widget_child_focus() Gets whether the widget prefers a height-for-width layout or a width-for-height layout. Single-child widgets generally propagate the preference of their child, more complex widgets need to request something either in context of their children or in context of their allocation capabilities. The `GtkSizeRequestMode` preferred by @widget. a `GtkWidget` instance Causes @widget to have the keyboard focus for the `GtkWindow` it's inside. If @widget is not focusable, or its [vfunc@Gtk.Widget.grab_focus] implementation cannot transfer the focus to a descendant of @widget that is focusable, it will not take focus and %FALSE will be returned. Calling [method@Gtk.Widget.grab_focus] on an already focused widget is allowed, should not have an effect, and return %TRUE. %TRUE if focus is now inside @widget. a `GtkWidget` Reverses the effects of gtk_widget_show(). This is causing the widget to be hidden (invisible to the user). Use [method@Gtk.Widget.set_visible] instead a `GtkWidget` Emits the `::keynav-failed` signal on the widget. This function should be called whenever keyboard navigation within a single widget hits a boundary. The return value of this function should be interpreted in a way similar to the return value of [method@Gtk.Widget.child_focus]. When %TRUE is returned, stay in the widget, the failed keyboard navigation is OK and/or there is nowhere we can/should move the focus to. When %FALSE is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling [method@Gtk.Widget.child_focus] on the widget’s toplevel. The default [signal@Gtk.Widget::keynav-failed] handler returns %FALSE for %GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. For the other values of `GtkDirectionType` it returns %TRUE. Whenever the default handler returns %TRUE, it also calls [method@Gtk.Widget.error_bell] to notify the user of the failed keyboard navigation. A use case for providing an own implementation of ::keynav-failed (either by connecting to it or by overriding it) would be a row of [class@Gtk.Entry] widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys. %TRUE if stopping keyboard navigation is fine, %FALSE if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s). a `GtkWidget` direction of focus movement Causes a widget to be mapped if it isn’t already. This function is only for use in widget implementations. a `GtkWidget` Measures @widget in the orientation @orientation and for the given @for_size. As an example, if @orientation is %GTK_ORIENTATION_HORIZONTAL and @for_size is 300, this functions will compute the minimum and natural width of @widget if it is allocated at a height of 300 pixels. See [GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management) for a more details on implementing `GtkWidgetClass.measure()`. A `GtkWidget` instance the orientation to measure Size for the opposite of @orientation, i.e. if @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height the widget should be measured with. The %GTK_ORIENTATION_VERTICAL case is analogous. This way, both height-for-width and width-for-height requests can be implemented. If no size is known, -1 can be passed. location to store the minimum size location to store the natural size location to store the baseline position for the minimum size, or -1 to report no baseline location to store the baseline position for the natural size, or -1 to report no baseline Emits the ::mnemonic-activate signal. See [signal@Gtk.Widget::mnemonic-activate]. %TRUE if the signal has been handled a `GtkWidget` %TRUE if there are other widgets with the same mnemonic Signal emitted when a change of focus is requested Signal emitted when “has-tooltip” is %TRUE and the hover timeout has expired with the cursor hovering “above” widget; or emitted when widget got focus in keyboard mode. Creates the GDK resources associated with a widget. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped automatically. Realizing a widget requires all the widget’s parent widgets to be realized; calling this function realizes the widget’s parents in addition to @widget itself. If a widget is not yet inside a toplevel window when you realize it, bad things will happen. This function is primarily used in widget implementations, and isn’t very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as [signal@Gtk.Widget::realize]. a `GtkWidget` Called when the widget gets added to a `GtkRoot` widget. Must chain up Set @child as the current focus child of @widget. This function is only suitable for widget implementations. If you want a certain widget to get the input focus, call [method@Gtk.Widget.grab_focus] on it. a `GtkWidget` a direct child widget of @widget or %NULL to unset the focus child of @widget Flags a widget to be displayed. Any widget that isn’t shown will not appear on the screen. Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen. When a toplevel container is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their toplevel container is realized and mapped. Use [method@Gtk.Widget.set_visible] instead a `GtkWidget` Called to set the allocation, if the widget does not have a layout manager. Vfunc called when a new snapshot of the widget has to be taken. Signal emitted when the widget state changes, see gtk_widget_get_state_flags(). Emitted when a system setting was changed. Must chain up. Causes a widget to be unmapped if it’s currently mapped. This function is only for use in widget implementations. a `GtkWidget` Causes a widget to be unrealized (frees all GDK resources associated with the widget). This function is only useful in widget implementations. a `GtkWidget` Called when the widget is about to be removed from its `GtkRoot` widget. Must chain up Enable or disable an action installed with gtk_widget_class_install_action(). a `GtkWidget` action name, such as "clipboard.paste" whether the action is now enabled For widgets that can be “activated” (buttons, menu items, etc.), this function activates them. The activation will emit the signal set using [method@Gtk.WidgetClass.set_activate_signal] during class initialization. Activation is what happens when you press <kbd>Enter</kbd> on a widget during key navigation. If you wish to handle the activation keybinding yourself, it is recommended to use [method@Gtk.WidgetClass.add_shortcut] with an action created with [ctor@Gtk.SignalAction.new]. If @widget isn't activatable, the function returns %FALSE. %TRUE if the widget was activatable a `GtkWidget` that’s activatable Looks up the action in the action groups associated with @widget and its ancestors, and activates it. This is a wrapper around [method@Gtk.Widget.activate_action_variant] that constructs the @args variant according to @format_string. %TRUE if the action was activated, %FALSE if the action does not exist a `GtkWidget` the name of the action to activate GVariant format string for arguments arguments, as given by format string Looks up the action in the action groups associated with @widget and its ancestors, and activates it. If the action is in an action group added with [method@Gtk.Widget.insert_action_group], the @name is expected to be prefixed with the prefix that was used when the group was inserted. The arguments must match the actions expected parameter type, as returned by `g_action_get_parameter_type()`. %TRUE if the action was activated, %FALSE if the action does not exist. a `GtkWidget` the name of the action to activate parameters to use Activates the `default.activate` action from @widget. a `GtkWidget` Adds @controller to @widget so that it will receive events. You will usually want to call this function right after creating any kind of [class@Gtk.EventController]. a `GtkWidget` a `GtkEventController` that hasn't been added to a widget yet Adds a style class to @widget. After calling this function, the widget’s style will match for @css_class, according to CSS matching rules. Use [method@Gtk.Widget.remove_css_class] to remove the style again. a `GtkWidget` The style class to add to @widget, without the leading '.' used for notation of style classes Adds a widget to the list of mnemonic labels for this widget. See [method@Gtk.Widget.list_mnemonic_labels]. Note the list of mnemonic labels for the widget is cleared when the widget is destroyed, so the caller must make sure to update its internal state at this point as well. a `GtkWidget` a `GtkWidget` that acts as a mnemonic label for @widget Queues an animation frame update and adds a callback to be called before each frame. Until the tick callback is removed, it will be called frequently (usually at the frame rate of the output device or as quickly as the application can be repainted, whichever is slower). For this reason, is most suitable for handling graphics that change every frame or every few frames. The tick callback does not automatically imply a relayout or repaint. If you want a repaint or relayout, and aren’t changing widget properties that would trigger that (for example, changing the text of a `GtkLabel`), then you will have to call [method@Gtk.Widget.queue_resize] or [method@Gtk.Widget.queue_draw] yourself. [method@Gdk.FrameClock.get_frame_time] should generally be used for timing continuous animations and [method@Gdk.FrameTimings.get_predicted_presentation_time] if you are trying to display isolated frames at particular times. This is a more convenient alternative to connecting directly to the [signal@Gdk.FrameClock::update] signal of `GdkFrameClock`, since you don't have to worry about when a `GdkFrameClock` is assigned to a widget. an id for the connection of this callback. Remove the callback by passing the id returned from this function to [method@Gtk.Widget.remove_tick_callback] a `GtkWidget` function to call for updating animations data to pass to @callback function to call to free @user_data when the callback is removed. This function is only used by `GtkWidget` subclasses, to assign a size, position and (optionally) baseline to their child widgets. In this function, the allocation and baseline may be adjusted. The given allocation will be forced to be bigger than the widget's minimum size, as well as at least 0×0 in size. For a version that does not take a transform, see [method@Gtk.Widget.size_allocate]. A `GtkWidget` New width of @widget New height of @widget New baseline of @widget, or -1 Transformation to be applied to @widget Called by widgets as the user moves around the window using keyboard shortcuts. The @direction argument indicates what kind of motion is taking place (up, down, left, right, tab forward, tab backward). This function calls the [vfunc@Gtk.Widget.focus] virtual function; widgets can override the virtual function in order to implement appropriate focus behavior. The default `focus()` virtual function for a widget should return `TRUE` if moving in @direction left the focus on a focusable location inside that widget, and `FALSE` if moving in @direction moved the focus outside the widget. When returning `TRUE`, widgets normally call [method@Gtk.Widget.grab_focus] to place the focus accordingly; when returning `FALSE`, they don’t modify the current focus location. This function is used by custom widget implementations; if you're writing an app, you’d use [method@Gtk.Widget.grab_focus] to move the focus to a particular widget. %TRUE if focus ended up inside @widget a `GtkWidget` direction of focus movement Computes the bounds for @widget in the coordinate space of @target. The bounds of widget are (the bounding box of) the region that it is expected to draw in. See the [coordinate system](coordinates.html) overview to learn more. If the operation is successful, %TRUE is returned. If @widget has no bounds or the bounds cannot be expressed in @target's coordinate space (for example if both widgets are in different windows), %FALSE is returned and @bounds is set to the zero rectangle. It is valid for @widget and @target to be the same widget. %TRUE if the bounds could be computed the `GtkWidget` to query the `GtkWidget` the rectangle taking the bounds Computes whether a container should give this widget extra space when possible. Containers should check this, rather than looking at [method@Gtk.Widget.get_hexpand] or [method@Gtk.Widget.get_vexpand]. This function already checks whether the widget is visible, so visibility does not need to be checked separately. Non-visible widgets are not expanded. The computed expand value uses either the expand setting explicitly set on the widget itself, or, if none has been explicitly set, the widget may expand if some of its children do. whether widget tree rooted here should be expanded the widget expand direction Translates the given @point in @widget's coordinates to coordinates relative to @target’s coordinate system. In order to perform this operation, both widgets must share a common ancestor. %TRUE if the point could be determined, %FALSE on failure. In this case, 0 is stored in @out_point. the `GtkWidget` to query the `GtkWidget` to transform into a point in @widget's coordinate system Set to the corresponding coordinates in @target's coordinate system Computes a matrix suitable to describe a transformation from @widget's coordinate system into @target's coordinate system. The transform can not be computed in certain cases, for example when @widget and @target do not share a common ancestor. In that case @out_transform gets set to the identity matrix. To learn more about widget coordinate systems, see the coordinate system [overview](coordinates.html). %TRUE if the transform could be computed, %FALSE otherwise a `GtkWidget` the target widget that the matrix will transform to location to store the final transformation Tests if the point at (@x, @y) is contained in @widget. The coordinates for (@x, @y) must be in widget coordinates, so (0, 0) is assumed to be the top left of @widget's content area. %TRUE if @widget contains (@x, @y). the widget to query X coordinate to test, relative to @widget's origin Y coordinate to test, relative to @widget's origin Creates a new `PangoContext` with the appropriate font map, font options, font description, and base direction for drawing text for this widget. See also [method@Gtk.Widget.get_pango_context]. the new `PangoContext` a `GtkWidget` Creates a new `PangoLayout` with the appropriate font map, font description, and base direction for drawing text for this widget. If you keep a `PangoLayout` created in this way around, you need to re-create it when the widget `PangoContext` is replaced. This can be tracked by listening to changes of the [property@Gtk.Widget:root] property on the widget. the new `PangoLayout` a `GtkWidget` text to set on the layout Clears the template children for the given widget. This function is the opposite of [method@Gtk.Widget.init_template], and it is used to clear all the template children from a widget instance. If you bound a template child to a field in the instance structure, or in the instance private data structure, the field will be set to `NULL` after this function returns. You should call this function inside the `GObjectClass.dispose()` implementation of any widget that called `gtk_widget_init_template()`. Typically, you will want to call this function last, right before chaining up to the parent type's dispose implementation, e.g. ```c static void some_widget_dispose (GObject *gobject) { SomeWidget *self = SOME_WIDGET (gobject); // Clear the template data for SomeWidget gtk_widget_dispose_template (GTK_WIDGET (self), SOME_TYPE_WIDGET); G_OBJECT_CLASS (some_widget_parent_class)->dispose (gobject); } ``` the widget with a template the type of the widget to finalize the template for Checks to see if a drag movement has passed the GTK drag threshold. %TRUE if the drag threshold has been passed. a `GtkWidget` X coordinate of start of drag Y coordinate of start of drag current X coordinate current Y coordinate Notifies the user about an input-related error on this widget. If the [property@Gtk.Settings:gtk-error-bell] setting is %TRUE, it calls [method@Gdk.Surface.beep], otherwise it does nothing. Note that the effect of [method@Gdk.Surface.beep] can be configured in many ways, depending on the windowing backend and the desktop environment or window manager that is used. a `GtkWidget` Returns the baseline that has currently been allocated to @widget. This function is intended to be used when implementing handlers for the `GtkWidget`Class.snapshot() function, and when allocating child widgets in `GtkWidget`Class.size_allocate(). Use [method@Gtk.Widget.get_baseline] instead the baseline of the @widget, or -1 if none the widget to query Returns the height that has currently been allocated to @widget. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). Use [method@Gtk.Widget.get_height] instead the height of the @widget the widget to query Returns the width that has currently been allocated to @widget. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). Use [method@Gtk.Widget.get_width] instead the width of the @widget the widget to query Retrieves the widget’s allocation. Note, when implementing a layout container: a widget’s allocation will be its “adjusted” allocation, that is, the widget’s parent typically calls [method@Gtk.Widget.size_allocate] with an allocation, and that allocation is then adjusted (to handle margin and alignment for example) before assignment to the widget. [method@Gtk.Widget.get_allocation] returns the adjusted allocation that was actually assigned to the widget. The adjusted allocation is guaranteed to be completely contained within the [method@Gtk.Widget.size_allocate] allocation, however. So a layout container is guaranteed that its children stay inside the assigned bounds, but not that they have exactly the bounds the container assigned. Use [method@Gtk.Widget.compute_bounds], [method@Gtk.Widget.get_width] or [method@Gtk.Widget.get_height] instead. a `GtkWidget` a pointer to a `GtkAllocation` to copy to Gets the first ancestor of @widget with type @widget_type. For example, `gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)` gets the first `GtkBox` that’s an ancestor of @widget. No reference will be added to the returned widget; it should not be unreferenced. Note that unlike [method@Gtk.Widget.is_ancestor], this function considers @widget to be an ancestor of itself. the ancestor widget a `GtkWidget` ancestor type Returns the baseline that has currently been allocated to @widget. This function is intended to be used when implementing handlers for the `GtkWidget`Class.snapshot() function, and when allocating child widgets in `GtkWidget`Class.size_allocate(). the baseline of the @widget, or -1 if none the widget to query Determines whether the input focus can enter @widget or any of its children. See [method@Gtk.Widget.set_focusable]. %TRUE if the input focus can enter @widget, %FALSE otherwise a `GtkWidget` Queries whether @widget can be the target of pointer events. %TRUE if @widget can receive pointer events a `GtkWidget` Gets the value set with gtk_widget_set_child_visible(). If you feel a need to use this function, your code probably needs reorganization. This function is only useful for container implementations and should never be called by an application. %TRUE if the widget is mapped with the parent. a `GtkWidget` Gets the clipboard object for @widget. This is a utility function to get the clipboard object for the `GdkDisplay` that @widget is using. Note that this function always works, even when @widget is not realized yet. the appropriate clipboard object a `GtkWidget` Gets the current foreground color for the widget’s CSS style. This function should only be used in snapshot implementations that need to do custom drawing with the foreground color. a `GtkWidget` return location for the color Returns the list of style classes applied to @widget. a %NULL-terminated list of css classes currently applied to @widget. The returned list must freed using g_strfreev(). a `GtkWidget` Returns the CSS name that is used for @self. the CSS name a `GtkWidget` Queries the cursor set on @widget. See [method@Gtk.Widget.set_cursor] for details. the cursor currently in use or %NULL if the cursor is inherited a `GtkWidget` Gets the reading direction for a particular widget. See [method@Gtk.Widget.set_direction]. the reading direction for the widget. a `GtkWidget` Get the `GdkDisplay` for the toplevel window associated with this widget. This function can only be called after the widget has been added to a widget hierarchy with a `GtkWindow` at the top. In general, you should only create display specific resources when a widget has been realized, and you should free those resources when the widget is unrealized. the `GdkDisplay` for the toplevel for this widget. a `GtkWidget` Returns the widget’s first child. This API is primarily meant for widget implementations. The widget's first child a `GtkWidget` Returns the current focus child of @widget. The current focus child of @widget a `GtkWidget` Returns whether the widget should grab focus when it is clicked with the mouse. See [method@Gtk.Widget.set_focus_on_click]. %TRUE if the widget should grab focus when it is clicked with the mouse a `GtkWidget` Determines whether @widget can own the input focus. See [method@Gtk.Widget.set_focusable]. %TRUE if @widget can own the input focus, %FALSE otherwise a `GtkWidget` Gets the font map of @widget. See [method@Gtk.Widget.set_font_map]. A `PangoFontMap` a `GtkWidget` Returns the `cairo_font_options_t` of widget. Seee [method@Gtk.Widget.set_font_options]. the `cairo_font_options_t` of widget a `GtkWidget` Obtains the frame clock for a widget. The frame clock is a global “ticker” that can be used to drive animations and repaints. The most common reason to get the frame clock is to call [method@Gdk.FrameClock.get_frame_time], in order to get a time to use for animating. For example you might record the start of the animation with an initial value from [method@Gdk.FrameClock.get_frame_time], and then update the animation by calling [method@Gdk.FrameClock.get_frame_time] again during each repaint. [method@Gdk.FrameClock.request_phase] will result in a new frame on the clock, but won’t necessarily repaint any widgets. To repaint a widget, you have to use [method@Gtk.Widget.queue_draw] which invalidates the widget (thus scheduling it to receive a draw on the next frame). gtk_widget_queue_draw() will also end up requesting a frame on the appropriate frame clock. A widget’s frame clock will not change while the widget is mapped. Reparenting a widget (which implies a temporary unmap) can change the widget’s frame clock. Unrealized widgets do not have a frame clock. a `GdkFrameClock` a `GtkWidget` Gets the horizontal alignment of @widget. For backwards compatibility reasons this method will never return one of the baseline alignments, but instead it will convert it to `GTK_ALIGN_FILL` or `GTK_ALIGN_CENTER`. Baselines are not supported for horizontal alignment. the horizontal alignment of @widget a `GtkWidget` Returns the current value of the `has-tooltip` property. current value of `has-tooltip` on @widget. a `GtkWidget` Returns the content height of the widget. This function returns the height passed to its size-allocate implementation, which is the height you should be using in [vfunc@Gtk.Widget.snapshot]. For pointer events, see [method@Gtk.Widget.contains]. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). The height of @widget a `GtkWidget` Gets whether the widget would like any available extra horizontal space. When a user resizes a `GtkWindow`, widgets with expand=TRUE generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand. Containers should use [method@Gtk.Widget.compute_expand] rather than this function, to see whether a widget, or any of its children, has the expand flag set. If any child of a widget wants to expand, the parent may ask to expand also. This function only looks at the widget’s own hexpand flag, rather than computing whether the entire widget tree rooted at this widget wants to expand. whether hexpand flag is set the widget Gets whether gtk_widget_set_hexpand() has been used to explicitly set the expand flag on this widget. If [property@Gtk.Widget:hexpand] property is set, then it overrides any computed expand value based on child widgets. If `hexpand` is not set, then the expand value depends on whether any children of the widget would like to expand. There are few reasons to use this function, but it’s here for completeness and consistency. whether hexpand has been explicitly set the widget Returns the widget’s last child. This API is primarily meant for widget implementations. The widget's last child a `GtkWidget` Retrieves the layout manager used by @widget. See [method@Gtk.Widget.set_layout_manager]. a `GtkLayoutManager` a `GtkWidget` Whether the widget is mapped. %TRUE if the widget is mapped, %FALSE otherwise. a `GtkWidget` Gets the bottom margin of @widget. The bottom margin of @widget a `GtkWidget` Gets the end margin of @widget. The end margin of @widget a `GtkWidget` Gets the start margin of @widget. The start margin of @widget a `GtkWidget` Gets the top margin of @widget. The top margin of @widget a `GtkWidget` Retrieves the name of a widget. See [method@Gtk.Widget.set_name] for the significance of widget names. name of the widget. This string is owned by GTK and should not be modified or freed a `GtkWidget` Returns the nearest `GtkNative` ancestor of @widget. This function will return %NULL if the widget is not contained inside a widget tree with a native ancestor. `GtkNative` widgets will return themselves here. the `GtkNative` ancestor of @widget a `GtkWidget` Returns the widget’s next sibling. This API is primarily meant for widget implementations. The widget's next sibling a `GtkWidget` #Fetches the requested opacity for this widget. See [method@Gtk.Widget.set_opacity]. the requested opacity for this widget. a `GtkWidget` Returns the widget’s overflow value. The widget's overflow. a `GtkWidget` Gets a `PangoContext` with the appropriate font map, font description, and base direction for this widget. Unlike the context returned by [method@Gtk.Widget.create_pango_context], this context is owned by the widget (it can be used until the screen for the widget changes or the widget is removed from its toplevel), and will be updated to match any changes to the widget’s attributes. This can be tracked by listening to changes of the [property@Gtk.Widget:root] property on the widget. the `PangoContext` for the widget. a `GtkWidget` Returns the parent widget of @widget. the parent widget of @widget a `GtkWidget` Retrieves the minimum and natural size of a widget, taking into account the widget’s preference for height-for-width management. This is used to retrieve a suitable size by container widgets which do not impose any restrictions on the child placement. It can be used to deduce toplevel window and menu sizes as well as child widgets in free-form containers such as `GtkFixed`. Handle with care. Note that the natural height of a height-for-width widget will generally be a smaller size than the minimum height, since the required height for the natural width is generally smaller than the required height for the minimum width. Use [method@Gtk.Widget.measure] if you want to support baseline alignment. a `GtkWidget` instance location for storing the minimum size location for storing the natural size Returns the widget’s previous sibling. This API is primarily meant for widget implementations. The widget's previous sibling a `GtkWidget` Gets the primary clipboard of @widget. This is a utility function to get the primary clipboard object for the `GdkDisplay` that @widget is using. Note that this function always works, even when @widget is not realized yet. the appropriate clipboard object a `GtkWidget` Determines whether @widget is realized. %TRUE if @widget is realized, %FALSE otherwise a `GtkWidget` Determines whether @widget is always treated as the default widget within its toplevel when it has the focus, even if another widget is the default. See [method@Gtk.Widget.set_receives_default]. %TRUE if @widget acts as the default widget when focused, %FALSE otherwise a `GtkWidget` Gets whether the widget prefers a height-for-width layout or a width-for-height layout. Single-child widgets generally propagate the preference of their child, more complex widgets need to request something either in context of their children or in context of their allocation capabilities. The `GtkSizeRequestMode` preferred by @widget. a `GtkWidget` instance Returns the `GtkRoot` widget of @widget. This function will return %NULL if the widget is not contained inside a widget tree with a root widget. `GtkRoot` widgets will return themselves here. the root widget of @widget a `GtkWidget` Retrieves the internal scale factor that maps from window coordinates to the actual device pixels. On traditional systems this is 1, on high density outputs, it can be a higher value (typically 2). See [method@Gdk.Surface.get_scale_factor]. the scale factor for @widget a `GtkWidget` Returns the widget’s sensitivity. This function returns the value that has been set using [method@Gtk.Widget.set_sensitive]). The effective sensitivity of a widget is however determined by both its own and its parent widget’s sensitivity. See [method@Gtk.Widget.is_sensitive]. %TRUE if the widget is sensitive a `GtkWidget` Gets the settings object holding the settings used for this widget. Note that this function can only be called when the `GtkWidget` is attached to a toplevel, since the settings object is specific to a particular `GdkDisplay`. If you want to monitor the widget for changes in its settings, connect to the `notify::display` signal. the relevant `GtkSettings` object a `GtkWidget` Returns the content width or height of the widget. Which dimension is returned depends on @orientation. This is equivalent to calling [method@Gtk.Widget.get_width] for %GTK_ORIENTATION_HORIZONTAL or [method@Gtk.Widget.get_height] for %GTK_ORIENTATION_VERTICAL, but can be used when writing orientation-independent code, such as when implementing [iface@Gtk.Orientable] widgets. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). The size of @widget in @orientation. a `GtkWidget` the orientation to query Gets the size request that was explicitly set for the widget using gtk_widget_set_size_request(). A value of -1 stored in @width or @height indicates that that dimension has not been set explicitly and the natural requisition of the widget will be used instead. See [method@Gtk.Widget.set_size_request]. To get the size a widget will actually request, call [method@Gtk.Widget.measure] instead of this function. a `GtkWidget` return location for width return location for height Returns the widget state as a flag set. It is worth mentioning that the effective %GTK_STATE_FLAG_INSENSITIVE state will be returned, that is, also based on parent insensitivity, even if @widget itself is sensitive. Also note that if you are looking for a way to obtain the [flags@Gtk.StateFlags] to pass to a [class@Gtk.StyleContext] method, you should look at [method@Gtk.StyleContext.get_state]. The state flags for widget a `GtkWidget` Returns the style context associated to @widget. The returned object is guaranteed to be the same for the lifetime of @widget. Style contexts will be removed in GTK 5 the widget’s `GtkStyleContext` a `GtkWidget` Fetch an object build from the template XML for @widget_type in this @widget instance. This will only report children which were previously declared with [method@Gtk.WidgetClass.bind_template_child_full] or one of its variants. This function is only meant to be called for code which is private to the @widget_type which declared the child and is meant for language bindings which cannot easily make use of the GObject structure offsets. The object built in the template XML with the id @name A `GtkWidget` The `GType` to get a template child for The “id” of the child defined in the template XML Gets the contents of the tooltip for @widget. If the tooltip has not been set using [method@Gtk.Widget.set_tooltip_markup], this function returns %NULL. the tooltip text a `GtkWidget` Gets the contents of the tooltip for @widget. If the @widget's tooltip was set using [method@Gtk.Widget.set_tooltip_markup], this function will return the escaped text. the tooltip text a `GtkWidget` Gets the vertical alignment of @widget. the vertical alignment of @widget a `GtkWidget` Gets whether the widget would like any available extra vertical space. See [method@Gtk.Widget.get_hexpand] for more detail. whether vexpand flag is set the widget Gets whether gtk_widget_set_vexpand() has been used to explicitly set the expand flag on this widget. See [method@Gtk.Widget.get_hexpand_set] for more detail. whether vexpand has been explicitly set the widget Determines whether the widget is visible. If you want to take into account whether the widget’s parent is also marked as visible, use [method@Gtk.Widget.is_visible] instead. This function does not check if the widget is obscured in any way. See [method@Gtk.Widget.set_visible]. %TRUE if the widget is visible a `GtkWidget` Returns the content width of the widget. This function returns the width passed to its size-allocate implementation, which is the width you should be using in [vfunc@Gtk.Widget.snapshot]. For pointer events, see [method@Gtk.Widget.contains]. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). The width of @widget a `GtkWidget` Causes @widget to have the keyboard focus for the `GtkWindow` it's inside. If @widget is not focusable, or its [vfunc@Gtk.Widget.grab_focus] implementation cannot transfer the focus to a descendant of @widget that is focusable, it will not take focus and %FALSE will be returned. Calling [method@Gtk.Widget.grab_focus] on an already focused widget is allowed, should not have an effect, and return %TRUE. %TRUE if focus is now inside @widget. a `GtkWidget` Returns whether @css_class is currently applied to @widget. %TRUE if @css_class is currently applied to @widget, %FALSE otherwise. a `GtkWidget` A style class, without the leading '.' used for notation of style classes Determines whether @widget is the current default widget within its toplevel. %TRUE if @widget is the current default widget within its toplevel, %FALSE otherwise a `GtkWidget` Determines if the widget has the global input focus. See [method@Gtk.Widget.is_focus] for the difference between having the global input focus, and only having the focus within a toplevel. %TRUE if the widget has the global input focus. a `GtkWidget` Determines if the widget should show a visible indication that it has the global input focus. This is a convenience function that takes into account whether focus indication should currently be shown in the toplevel window of @widget. See [method@Gtk.Window.get_focus_visible] for more information about focus indication. To find out if the widget has the global input focus, use [method@Gtk.Widget.has_focus]. %TRUE if the widget should display a “focus rectangle” a `GtkWidget` Reverses the effects of gtk_widget_show(). This is causing the widget to be hidden (invisible to the user). Use [method@Gtk.Widget.set_visible] instead a `GtkWidget` Returns whether the widget is currently being destroyed. This information can sometimes be used to avoid doing unnecessary work. %TRUE if @widget is being destroyed a `GtkWidget` Creates and initializes child widgets defined in templates. This function must be called in the instance initializer for any class which assigned itself a template using [method@Gtk.WidgetClass.set_template]. It is important to call this function in the instance initializer of a `GtkWidget` subclass and not in `GObject.constructed()` or `GObject.constructor()` for two reasons: - derived widgets will assume that the composite widgets defined by its parent classes have been created in their relative instance initializers - when calling `g_object_new()` on a widget with composite templates, it’s important to build the composite widgets before the construct properties are set. Properties passed to `g_object_new()` should take precedence over properties set in the private template XML A good rule of thumb is to call this function as the first thing in an instance initialization function. a `GtkWidget` Inserts @group into @widget. Children of @widget that implement [iface@Gtk.Actionable] can then be associated with actions in @group by setting their “action-name” to @prefix.`action-name`. Note that inheritance is defined for individual actions. I.e. even if you insert a group with prefix @prefix, actions with the same prefix will still be inherited from the parent, unless the group contains an action with the same name. If @group is %NULL, a previously inserted group for @name is removed from @widget. a `GtkWidget` the prefix for actions in @group a `GActionGroup`, or %NULL to remove the previously inserted group for @name Inserts @widget into the child widget list of @parent. It will be placed after @previous_sibling, or at the beginning if @previous_sibling is %NULL. After calling this function, `gtk_widget_get_prev_sibling(widget)` will return @previous_sibling. If @parent is already set as the parent widget of @widget, this function can also be used to reorder @widget in the child widget list of @parent. This API is primarily meant for widget implementations; if you are just using a widget, you *must* use its own API for adding children. a `GtkWidget` the parent `GtkWidget` to insert @widget into the new previous sibling of @widget Inserts @widget into the child widget list of @parent. It will be placed before @next_sibling, or at the end if @next_sibling is %NULL. After calling this function, `gtk_widget_get_next_sibling(widget)` will return @next_sibling. If @parent is already set as the parent widget of @widget, this function can also be used to reorder @widget in the child widget list of @parent. This API is primarily meant for widget implementations; if you are just using a widget, you *must* use its own API for adding children. a `GtkWidget` the parent `GtkWidget` to insert @widget into the new next sibling of @widget Determines whether @widget is somewhere inside @ancestor, possibly with intermediate containers. %TRUE if @ancestor contains @widget as a child, grandchild, great grandchild, etc. a `GtkWidget` another `GtkWidget` Determines whether @widget can be drawn to. A widget can be drawn if it is mapped and visible. %TRUE if @widget is drawable, %FALSE otherwise a `GtkWidget` Determines if the widget is the focus widget within its toplevel. This does not mean that the [property@Gtk.Widget:has-focus] property is necessarily set; [property@Gtk.Widget:has-focus] will only be set if the toplevel widget additionally has the global input focus. %TRUE if the widget is the focus widget. a `GtkWidget` Returns the widget’s effective sensitivity. This means it is sensitive itself and also its parent widget is sensitive. %TRUE if the widget is effectively sensitive a `GtkWidget` Determines whether the widget and all its parents are marked as visible. This function does not check if the widget is obscured in any way. See also [method@Gtk.Widget.get_visible] and [method@Gtk.Widget.set_visible]. %TRUE if the widget and all its parents are visible a `GtkWidget` Emits the `::keynav-failed` signal on the widget. This function should be called whenever keyboard navigation within a single widget hits a boundary. The return value of this function should be interpreted in a way similar to the return value of [method@Gtk.Widget.child_focus]. When %TRUE is returned, stay in the widget, the failed keyboard navigation is OK and/or there is nowhere we can/should move the focus to. When %FALSE is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling [method@Gtk.Widget.child_focus] on the widget’s toplevel. The default [signal@Gtk.Widget::keynav-failed] handler returns %FALSE for %GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. For the other values of `GtkDirectionType` it returns %TRUE. Whenever the default handler returns %TRUE, it also calls [method@Gtk.Widget.error_bell] to notify the user of the failed keyboard navigation. A use case for providing an own implementation of ::keynav-failed (either by connecting to it or by overriding it) would be a row of [class@Gtk.Entry] widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys. %TRUE if stopping keyboard navigation is fine, %FALSE if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s). a `GtkWidget` direction of focus movement Returns the widgets for which this widget is the target of a mnemonic. Typically, these widgets will be labels. See, for example, [method@Gtk.Label.set_mnemonic_widget]. The widgets in the list are not individually referenced. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets, you must call `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first, and then unref all the widgets afterwards. the list of mnemonic labels; free this list with g_list_free() when you are done with it. a `GtkWidget` Causes a widget to be mapped if it isn’t already. This function is only for use in widget implementations. a `GtkWidget` Measures @widget in the orientation @orientation and for the given @for_size. As an example, if @orientation is %GTK_ORIENTATION_HORIZONTAL and @for_size is 300, this functions will compute the minimum and natural width of @widget if it is allocated at a height of 300 pixels. See [GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management) for a more details on implementing `GtkWidgetClass.measure()`. A `GtkWidget` instance the orientation to measure Size for the opposite of @orientation, i.e. if @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height the widget should be measured with. The %GTK_ORIENTATION_VERTICAL case is analogous. This way, both height-for-width and width-for-height requests can be implemented. If no size is known, -1 can be passed. location to store the minimum size location to store the natural size location to store the baseline position for the minimum size, or -1 to report no baseline location to store the baseline position for the natural size, or -1 to report no baseline Emits the ::mnemonic-activate signal. See [signal@Gtk.Widget::mnemonic-activate]. %TRUE if the signal has been handled a `GtkWidget` %TRUE if there are other widgets with the same mnemonic Returns a `GListModel` to track the children of @widget. Calling this function will enable extra internal bookkeeping to track children and emit signals on the returned listmodel. It may slow down operations a lot. Applications should try hard to avoid calling this function because of the slowdowns. a `GListModel` tracking @widget's children a `GtkWidget` Returns a `GListModel` to track the [class@Gtk.EventController]s of @widget. Calling this function will enable extra internal bookkeeping to track controllers and emit signals on the returned listmodel. It may slow down operations a lot. Applications should try hard to avoid calling this function because of the slowdowns. a `GListModel` tracking @widget's controllers a `GtkWidget` Finds the descendant of @widget closest to the point (@x, @y). The point must be given in widget coordinates, so (0, 0) is assumed to be the top left of @widget's content area. Usually widgets will return %NULL if the given coordinate is not contained in @widget checked via [method@Gtk.Widget.contains]. Otherwise they will recursively try to find a child that does not return %NULL. Widgets are however free to customize their picking algorithm. This function is used on the toplevel to determine the widget below the mouse cursor for purposes of hover highlighting and delivering events. The widget descendant at the given point the widget to query X coordinate to test, relative to @widget's origin Y coordinate to test, relative to @widget's origin Flags to influence what is picked Flags the widget for a rerun of the [vfunc@Gtk.Widget.size_allocate] function. Use this function instead of [method@Gtk.Widget.queue_resize] when the @widget's size request didn't change but it wants to reposition its contents. An example user of this function is [method@Gtk.Widget.set_halign]. This function is only for use in widget implementations. a `GtkWidget` Schedules this widget to be redrawn in the paint phase of the current or the next frame. This means @widget's [vfunc@Gtk.Widget.snapshot] implementation will be called. a `GtkWidget` Flags a widget to have its size renegotiated. This should be called when a widget for some reason has a new size request. For example, when you change the text in a [class@Gtk.Label], the label queues a resize to ensure there’s enough space for the new text. Note that you cannot call gtk_widget_queue_resize() on a widget from inside its implementation of the [vfunc@Gtk.Widget.size_allocate] virtual method. Calls to gtk_widget_queue_resize() from inside [vfunc@Gtk.Widget.size_allocate] will be silently ignored. This function is only for use in widget implementations. a `GtkWidget` Creates the GDK resources associated with a widget. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped automatically. Realizing a widget requires all the widget’s parent widgets to be realized; calling this function realizes the widget’s parents in addition to @widget itself. If a widget is not yet inside a toplevel window when you realize it, bad things will happen. This function is primarily used in widget implementations, and isn’t very useful otherwise. Many times when you think you might need it, a better approach is to connect to a signal that will be called after the widget is realized automatically, such as [signal@Gtk.Widget::realize]. a `GtkWidget` Removes @controller from @widget, so that it doesn't process events anymore. It should not be used again. Widgets will remove all event controllers automatically when they are destroyed, there is normally no need to call this function. a `GtkWidget` a `GtkEventController` Removes a style from @widget. After this, the style of @widget will stop matching for @css_class. a `GtkWidget` The style class to remove from @widget, without the leading '.' used for notation of style classes Removes a widget from the list of mnemonic labels for this widget. See [method@Gtk.Widget.list_mnemonic_labels]. The widget must have previously been added to the list with [method@Gtk.Widget.add_mnemonic_label]. a `GtkWidget` a `GtkWidget` that was previously set as a mnemonic label for @widget with [method@Gtk.Widget.add_mnemonic_label] Removes a tick callback previously registered with gtk_widget_add_tick_callback(). a `GtkWidget` an id returned by [method@Gtk.Widget.add_tick_callback] Specifies whether the input focus can enter the widget or any of its children. Applications should set @can_focus to %FALSE to mark a widget as for pointer/touch use only. Note that having @can_focus be %TRUE is only one of the necessary conditions for being focusable. A widget must also be sensitive and focusable and not have an ancestor that is marked as not can-focus in order to receive input focus. See [method@Gtk.Widget.grab_focus] for actually setting the input focus on a widget. a `GtkWidget` whether or not the input focus can enter the widget or any of its children Sets whether @widget can be the target of pointer events. a `GtkWidget` whether this widget should be able to receive pointer events Sets whether @widget should be mapped along with its parent. The child visibility can be set for widget before it is added to a container with [method@Gtk.Widget.set_parent], to avoid mapping children unnecessary before immediately unmapping them. However it will be reset to its default state of %TRUE when the widget is removed from a container. Note that changing the child visibility of a widget does not queue a resize on the widget. Most of the time, the size of a widget is computed from all visible children, whether or not they are mapped. If this is not the case, the container can queue a resize itself. This function is only useful for container implementations and should never be called by an application. a `GtkWidget` if %TRUE, @widget should be mapped along with its parent. Clear all style classes applied to @widget and replace them with @classes. a `GtkWidget` %NULL-terminated list of style classes to apply to @widget. Sets the cursor to be shown when pointer devices point towards @widget. If the @cursor is NULL, @widget will use the cursor inherited from the parent widget. a `GtkWidget` the new cursor Sets a named cursor to be shown when pointer devices point towards @widget. This is a utility function that creates a cursor via [ctor@Gdk.Cursor.new_from_name] and then sets it on @widget with [method@Gtk.Widget.set_cursor]. See those functions for details. On top of that, this function allows @name to be %NULL, which will do the same as calling [method@Gtk.Widget.set_cursor] with a %NULL cursor. a `GtkWidget` The name of the cursor Sets the reading direction on a particular widget. This direction controls the primary direction for widgets containing text, and also the direction in which the children of a container are packed. The ability to set the direction is present in order so that correct localization into languages with right-to-left reading directions can be done. Generally, applications will let the default reading direction present, except for containers where the containers are arranged in an order that is explicitly visual rather than logical (such as buttons for text justification). If the direction is set to %GTK_TEXT_DIR_NONE, then the value set by [func@Gtk.Widget.set_default_direction] will be used. a `GtkWidget` the new direction Set @child as the current focus child of @widget. This function is only suitable for widget implementations. If you want a certain widget to get the input focus, call [method@Gtk.Widget.grab_focus] on it. a `GtkWidget` a direct child widget of @widget or %NULL to unset the focus child of @widget Sets whether the widget should grab focus when it is clicked with the mouse. Making mouse clicks not grab focus is useful in places like toolbars where you don’t want the keyboard focus removed from the main area of the application. a `GtkWidget` whether the widget should grab focus when clicked with the mouse Specifies whether @widget can own the input focus. Widget implementations should set @focusable to %TRUE in their init() function if they want to receive keyboard input. Note that having @focusable be %TRUE is only one of the necessary conditions for being focusable. A widget must also be sensitive and can-focus and not have an ancestor that is marked as not can-focus in order to receive input focus. See [method@Gtk.Widget.grab_focus] for actually setting the input focus on a widget. a `GtkWidget` whether or not @widget can own the input focus Sets the font map to use for Pango rendering. The font map is the object that is used to look up fonts. Setting a custom font map can be useful in special situations, e.g. when you need to add application-specific fonts to the set of available fonts. When not set, the widget will inherit the font map from its parent. a `GtkWidget` a `PangoFontMap`, or %NULL to unset any previously set font map Sets the `cairo_font_options_t` used for Pango rendering in this widget. When not set, the default font options for the `GdkDisplay` will be used. a `GtkWidget` a `cairo_font_options_t` to unset any previously set default font options Sets the horizontal alignment of @widget. a `GtkWidget` the horizontal alignment Sets the `has-tooltip` property on @widget to @has_tooltip. a `GtkWidget` whether or not @widget has a tooltip. Sets whether the widget would like any available extra horizontal space. When a user resizes a `GtkWindow`, widgets with expand=TRUE generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand. Call this function to set the expand flag if you would like your widget to become larger horizontally when the window has extra room. By default, widgets automatically expand if any of their children want to expand. (To see if a widget will automatically expand given its current children and state, call [method@Gtk.Widget.compute_expand]. A container can decide how the expandability of children affects the expansion of the container by overriding the compute_expand virtual method on `GtkWidget`.). Setting hexpand explicitly with this function will override the automatic expand behavior. This function forces the widget to expand or not to expand, regardless of children. The override occurs because [method@Gtk.Widget.set_hexpand] sets the hexpand-set property (see [method@Gtk.Widget.set_hexpand_set]) which causes the widget’s hexpand value to be used, rather than looking at children and widget state. the widget whether to expand Sets whether the hexpand flag will be used. The [property@Gtk.Widget:hexpand-set] property will be set automatically when you call [method@Gtk.Widget.set_hexpand] to set hexpand, so the most likely reason to use this function would be to unset an explicit expand flag. If hexpand is set, then it overrides any computed expand value based on child widgets. If hexpand is not set, then the expand value depends on whether any children of the widget would like to expand. There are few reasons to use this function, but it’s here for completeness and consistency. the widget value for hexpand-set property Sets the layout manager delegate instance that provides an implementation for measuring and allocating the children of @widget. a `GtkWidget` a `GtkLayoutManager` Sets the bottom margin of @widget. a `GtkWidget` the bottom margin Sets the end margin of @widget. a `GtkWidget` the end margin Sets the start margin of @widget. a `GtkWidget` the start margin Sets the top margin of @widget. a `GtkWidget` the top margin Sets a widgets name. Setting a name allows you to refer to the widget from a CSS file. You can apply a style to widgets with a particular name in the CSS file. See the documentation for the CSS syntax (on the same page as the docs for [class@Gtk.StyleContext]. Note that the CSS syntax has certain special characters to delimit and represent elements in a selector (period, #, >, *...), so using these will make your widget impossible to match by name. Any combination of alphanumeric symbols, dashes and underscores will suffice. a `GtkWidget` name for the widget Request the @widget to be rendered partially transparent. An opacity of 0 is fully transparent and an opacity of 1 is fully opaque. Opacity works on both toplevel widgets and child widgets, although there are some limitations: For toplevel widgets, applying opacity depends on the capabilities of the windowing system. On X11, this has any effect only on X displays with a compositing manager, see gdk_display_is_composited(). On Windows and Wayland it should always work, although setting a window’s opacity after the window has been shown may cause some flicker. Note that the opacity is inherited through inclusion — if you set a toplevel to be partially translucent, all of its content will appear translucent, since it is ultimatively rendered on that toplevel. The opacity value itself is not inherited by child widgets (since that would make widgets deeper in the hierarchy progressively more translucent). As a consequence, [class@Gtk.Popover]s and other [iface@Gtk.Native] widgets with their own surface will use their own opacity value, and thus by default appear non-translucent, even if they are attached to a toplevel that is translucent. a `GtkWidget` desired opacity, between 0 and 1 Sets how @widget treats content that is drawn outside the widget's content area. See the definition of [enum@Gtk.Overflow] for details. This setting is provided for widget implementations and should not be used by application code. The default value is %GTK_OVERFLOW_VISIBLE. a `GtkWidget` desired overflow Sets @parent as the parent widget of @widget. This takes care of details such as updating the state and style of the child to reflect its new location and resizing the parent. The opposite function is [method@Gtk.Widget.unparent]. This function is useful only when implementing subclasses of `GtkWidget`. a `GtkWidget` parent widget Specifies whether @widget will be treated as the default widget within its toplevel when it has the focus, even if another widget is the default. a `GtkWidget` whether or not @widget can be a default widget. Sets the sensitivity of a widget. A widget is sensitive if the user can interact with it. Insensitive widgets are “grayed out” and the user can’t interact with them. Insensitive widgets are known as “inactive”, “disabled”, or “ghosted” in some other toolkits. a `GtkWidget` %TRUE to make the widget sensitive Sets the minimum size of a widget. That is, the widget’s size request will be at least @width by @height. You can use this function to force a widget to be larger than it normally would be. In most cases, [method@Gtk.Window.set_default_size] is a better choice for toplevel windows than this function; setting the default size will still allow users to shrink the window. Setting the size request will force them to leave the window at least as large as the size request. Note the inherent danger of setting any fixed size - themes, translations into other languages, different fonts, and user action can all change the appropriate size for a given widget. So, it's basically impossible to hardcode a size that will always be correct. The size request of a widget is the smallest size a widget can accept while still functioning well and drawing itself correctly. However in some strange cases a widget may be allocated less than its requested size, and in many cases a widget may be allocated more space than it requested. If the size request in a given direction is -1 (unset), then the “natural” size request of the widget will be used instead. The size request set here does not include any margin from the properties [property@Gtk.Widget:margin-start], [property@Gtk.Widget:margin-end], [property@Gtk.Widget:margin-top], and [property@Gtk.Widget:margin-bottom], but it does include pretty much all other padding or border properties set by any subclass of `GtkWidget`. a `GtkWidget` width @widget should request, or -1 to unset height @widget should request, or -1 to unset Turns on flag values in the current widget state. Typical widget states are insensitive, prelighted, etc. This function accepts the values %GTK_STATE_FLAG_DIR_LTR and %GTK_STATE_FLAG_DIR_RTL but ignores them. If you want to set the widget's direction, use [method@Gtk.Widget.set_direction]. This function is for use in widget implementations. a `GtkWidget` State flags to turn on Whether to clear state before turning on @flags Sets @markup as the contents of the tooltip, which is marked up with Pango markup. This function will take care of setting the [property@Gtk.Widget:has-tooltip] as a side effect, and of the default handler for the [signal@Gtk.Widget::query-tooltip] signal. See also [method@Gtk.Tooltip.set_markup]. a `GtkWidget` the contents of the tooltip for @widget Sets @text as the contents of the tooltip. If @text contains any markup, it will be escaped. This function will take care of setting [property@Gtk.Widget:has-tooltip] as a side effect, and of the default handler for the [signal@Gtk.Widget::query-tooltip] signal. See also [method@Gtk.Tooltip.set_text]. a `GtkWidget` the contents of the tooltip for @widget Sets the vertical alignment of @widget. a `GtkWidget` the vertical alignment Sets whether the widget would like any available extra vertical space. See [method@Gtk.Widget.set_hexpand] for more detail. the widget whether to expand Sets whether the vexpand flag will be used. See [method@Gtk.Widget.set_hexpand_set] for more detail. the widget value for vexpand-set property Sets the visibility state of @widget. Note that setting this to %TRUE doesn’t mean the widget is actually viewable, see [method@Gtk.Widget.get_visible]. a `GtkWidget` whether the widget should be shown or not Returns whether @widget should contribute to the measuring and allocation of its parent. This is %FALSE for invisible children, but also for children that have their own surface. %TRUE if child should be included in measuring and allocating a widget Flags a widget to be displayed. Any widget that isn’t shown will not appear on the screen. Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen. When a toplevel container is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their toplevel container is realized and mapped. Use [method@Gtk.Widget.set_visible] instead a `GtkWidget` Allocates widget with a transformation that translates the origin to the position in @allocation. This is a simple form of [method@Gtk.Widget.allocate]. a `GtkWidget` position and size to be allocated to @widget The baseline of the child, or -1 Snapshot the a child of @widget. When a widget receives a call to the snapshot function, it must send synthetic [vfunc@Gtk.Widget.snapshot] calls to all children. This function provides a convenient way of doing this. A widget, when it receives a call to its [vfunc@Gtk.Widget.snapshot] function, calls gtk_widget_snapshot_child() once for each child, passing in the @snapshot the widget received. gtk_widget_snapshot_child() takes care of translating the origin of @snapshot, and deciding whether the child needs to be snapshot. This function does nothing for children that implement `GtkNative`. a `GtkWidget` a child of @widget `GtkSnapshot` as passed to the widget. In particular, no calls to gtk_snapshot_translate() or other transform calls should have been made. Translate coordinates relative to @src_widget’s allocation to coordinates relative to @dest_widget’s allocations. In order to perform this operation, both widget must share a common ancestor. Use gtk_widget_compute_point() instead %FALSE if @src_widget and @dest_widget have no common ancestor. In this case, 0 is stored in *@dest_x and *@dest_y. Otherwise %TRUE. a `GtkWidget` a `GtkWidget` X position relative to @src_widget Y position relative to @src_widget location to store X position relative to @dest_widget location to store Y position relative to @dest_widget Triggers a tooltip query on the display where the toplevel of @widget is located. a `GtkWidget` Causes a widget to be unmapped if it’s currently mapped. This function is only for use in widget implementations. a `GtkWidget` Dissociate @widget from its parent. This function is only for use in widget implementations, typically in dispose. a `GtkWidget` Causes a widget to be unrealized (frees all GDK resources associated with the widget). This function is only useful in widget implementations. a `GtkWidget` Turns off flag values for the current widget state. See [method@Gtk.Widget.set_state_flags]. This function is for use in widget implementations. a `GtkWidget` State flags to turn off Whether the widget or any of its descendents can accept the input focus. This property is meant to be set by widget implementations, typically in their instance init function. Whether the widget can receive pointer events. A list of css classes applied to this widget. The name of this widget in the CSS tree. This property is meant to be set by widget implementations, typically in their instance init function. The cursor used by @widget. Whether the widget should grab focus when it is clicked with the mouse. This property is only relevant for widgets that can take focus. Whether this widget itself will accept the input focus. How to distribute horizontal space if widget gets extra space. Whether the widget is the default widget. Whether the widget has the input focus. Enables or disables the emission of the ::query-tooltip signal on @widget. A value of %TRUE indicates that @widget can have a tooltip, in this case the widget will be queried using [signal@Gtk.Widget::query-tooltip] to determine whether it will provide a tooltip or not. Override for height request of the widget. If this is -1, the natural request will be used. Whether to expand horizontally. Whether to use the `hexpand` property. The `GtkLayoutManager` instance to use to compute the preferred size of the widget, and allocate its children. This property is meant to be set by widget implementations, typically in their instance init function. Margin on bottom side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [method@Gtk.Widget.set_size_request] for example. Margin on end of widget, horizontally. This property supports left-to-right and right-to-left text directions. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [method@Gtk.Widget.set_size_request] for example. Margin on start of widget, horizontally. This property supports left-to-right and right-to-left text directions. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [method@Gtk.Widget.set_size_request] for example. Margin on top side of widget. This property adds margin outside of the widget's normal size request, the margin will be added in addition to the size from [method@Gtk.Widget.set_size_request] for example. The name of the widget. The requested opacity of the widget. How content outside the widget's content area is treated. This property is meant to be set by widget implementations, typically in their instance init function. The parent widget of this widget. Whether the widget will receive the default action when it is focused. The `GtkRoot` widget of the widget tree containing this widget. This will be %NULL if the widget is not contained in a root widget. The scale factor of the widget. Whether the widget responds to input. Sets the text of tooltip to be the given string, which is marked up with Pango markup. Also see [method@Gtk.Tooltip.set_markup]. This is a convenience property which will take care of getting the tooltip shown if the given string is not %NULL: [property@Gtk.Widget:has-tooltip] will automatically be set to %TRUE and there will be taken care of [signal@Gtk.Widget::query-tooltip] in the default signal handler. Note that if both [property@Gtk.Widget:tooltip-text] and [property@Gtk.Widget:tooltip-markup] are set, the last one wins. Sets the text of tooltip to be the given string. Also see [method@Gtk.Tooltip.set_text]. This is a convenience property which will take care of getting the tooltip shown if the given string is not %NULL: [property@Gtk.Widget:has-tooltip] will automatically be set to %TRUE and there will be taken care of [signal@Gtk.Widget::query-tooltip] in the default signal handler. Note that if both [property@Gtk.Widget:tooltip-text] and [property@Gtk.Widget:tooltip-markup] are set, the last one wins. How to distribute vertical space if widget gets extra space. Whether to expand vertically. Whether to use the `vexpand` property. Whether the widget is visible. Override for width request of the widget. If this is -1, the natural request will be used. Signals that all holders of a reference to the widget should release the reference that they hold. May result in finalization of the widget if all references are released. This signal is not suitable for saving widget state. Emitted when the text direction of a widget changes. the previous text direction of @widget Emitted when @widget is hidden. Emitted if keyboard navigation fails. See [method@Gtk.Widget.keynav_failed] for details. %TRUE if stopping keyboard navigation is fine, %FALSE if the emitting widget should try to handle the keyboard navigation attempt in its parent widget(s). the direction of movement Emitted when @widget is going to be mapped. A widget is mapped when the widget is visible (which is controlled with [property@Gtk.Widget:visible]) and all its parents up to the toplevel widget are also visible. The ::map signal can be used to determine whether a widget will be drawn, for instance it can resume an animation that was stopped during the emission of [signal@Gtk.Widget::unmap]. Emitted when a widget is activated via a mnemonic. The default handler for this signal activates @widget if @group_cycling is %FALSE, or just makes @widget grab focus if @group_cycling is %TRUE. %TRUE to stop other handlers from being invoked for the event. %FALSE to propagate the event further. %TRUE if there are other widgets with the same mnemonic Emitted when the focus is moved. The ::move-focus signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Tab</kbd> to move forward, and <kbd>Shift</kbd>+<kbd>Tab</kbd> to move backward. the direction of the focus move Emitted when the widget’s tooltip is about to be shown. This happens when the [property@Gtk.Widget:has-tooltip] property is %TRUE and the hover timeout has expired with the cursor hovering "above" @widget; or emitted when @widget got focus in keyboard mode. Using the given coordinates, the signal handler should determine whether a tooltip should be shown for @widget. If this is the case %TRUE should be returned, %FALSE otherwise. Note that if @keyboard_mode is %TRUE, the values of @x and @y are undefined and should not be used. The signal handler is free to manipulate @tooltip with the therefore destined function calls. %TRUE if @tooltip should be shown right now, %FALSE otherwise. the x coordinate of the cursor position where the request has been emitted, relative to @widget's left side the y coordinate of the cursor position where the request has been emitted, relative to @widget's top %TRUE if the tooltip was triggered using the keyboard a `GtkTooltip` Emitted when @widget is associated with a `GdkSurface`. This means that [method@Gtk.Widget.realize] has been called or the widget has been mapped (that is, it is going to be drawn). Emitted when @widget is shown. Emitted when the widget state changes. See [method@Gtk.Widget.get_state_flags]. The previous state flags. Emitted when @widget is going to be unmapped. A widget is unmapped when either it or any of its parents up to the toplevel widget have been set as hidden. As ::unmap indicates that a widget will not be shown any longer, it can be used to, for example, stop an animation on the widget. Emitted when the `GdkSurface` associated with @widget is destroyed. This means that [method@Gtk.Widget.unrealize] has been called or the widget has been unmapped (that is, it is going to be hidden). The type of the callback functions used for activating actions installed with gtk_widget_class_install_action(). The @parameter must match the @parameter_type of the action. the widget to which the action belongs the action name parameter for activation The object class structure needs to be the first element in the widget class structure in order for the class mechanism to work correctly. This allows a GtkWidgetClass pointer to be cast to a GObjectClass pointer. Signal emitted when widget is shown a `GtkWidget` Signal emitted when widget is hidden. a `GtkWidget` Signal emitted when widget is going to be mapped, that is when the widget is visible (which is controlled with gtk_widget_set_visible()) and all its parents up to the toplevel widget are also visible. a `GtkWidget` Signal emitted when widget is going to be unmapped, which means that either it or any of its parents up to the toplevel widget have been set as hidden. a `GtkWidget` Signal emitted when widget is associated with a `GdkSurface`, which means that gtk_widget_realize() has been called or the widget has been mapped (that is, it is going to be drawn). a `GtkWidget` Signal emitted when the GdkSurface associated with widget is destroyed, which means that gtk_widget_unrealize() has been called or the widget has been unmapped (that is, it is going to be hidden). a `GtkWidget` Called when the widget gets added to a `GtkRoot` widget. Must chain up Called when the widget is about to be removed from its `GtkRoot` widget. Must chain up Called to set the allocation, if the widget does not have a layout manager. Signal emitted when the widget state changes, see gtk_widget_get_state_flags(). Signal emitted when the text direction of a widget changes. Called to get the request mode, if the widget does not have a layout manager. This allows a widget to tell its parent container whether it prefers to be allocated in %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH or %GTK_SIZE_REQUEST_WIDTH_FOR_HEIGHT mode. %GTK_SIZE_REQUEST_HEIGHT_FOR_WIDTH means the widget prefers to have `GtkWidgetClass.measure()` called first to get the default width (passing a for_size of -1), then again to get the height for said default width. %GTK_SIZE_REQUEST_CONSTANT_SIZE disables any height-for-width or width-for-height geometry management for said widget and is the default return. It’s important to note that any widget which trades height-for-width or width-for-height must respond properly to a for_size value >= -1 passed to `GtkWidgetClass.measure`, for both possible orientations. The `GtkSizeRequestMode` preferred by @widget. a `GtkWidget` instance Called to obtain the minimum and natural size of the widget, if the widget does not have a layout manager. Depending on the orientation parameter, the passed for_size can be interpreted as width or height. A widget will never be allocated less than its minimum size. A `GtkWidget` instance the orientation to measure Size for the opposite of @orientation, i.e. if @orientation is %GTK_ORIENTATION_HORIZONTAL, this is the height the widget should be measured with. The %GTK_ORIENTATION_VERTICAL case is analogous. This way, both height-for-width and width-for-height requests can be implemented. If no size is known, -1 can be passed. location to store the minimum size location to store the natural size location to store the baseline position for the minimum size, or -1 to report no baseline location to store the baseline position for the natural size, or -1 to report no baseline Activates the @widget if @group_cycling is %FALSE, and just grabs the focus if @group_cycling is %TRUE. %TRUE if the signal has been handled a `GtkWidget` %TRUE if there are other widgets with the same mnemonic Causes @widget to have the keyboard focus for the `GtkWindow` it’s inside. %TRUE if focus is now inside @widget. a `GtkWidget` Vfunc for gtk_widget_child_focus() Sets the focused child of a widget. Must chain up a `GtkWidget` a direct child widget of @widget or %NULL to unset the focus child of @widget Signal emitted when a change of focus is requested Signal emitted if keyboard navigation fails. %TRUE if stopping keyboard navigation is fine, %FALSE if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s). a `GtkWidget` direction of focus movement Signal emitted when “has-tooltip” is %TRUE and the hover timeout has expired with the cursor hovering “above” widget; or emitted when widget got focus in keyboard mode. Computes whether a container should give this widget extra space when possible. Vfunc called when the CSS used by widget was changed. Widgets should then discard their caches that depend on CSS and queue resizes or redraws accordingly. The default implementation will take care of this for all the default CSS properties, so implementations must chain up. Emitted when a system setting was changed. Must chain up. Vfunc called when a new snapshot of the widget has to be taken. Vfunc for gtk_widget_contains(). %TRUE if @widget contains (@x, @y). the widget to query X coordinate to test, relative to @widget's origin Y coordinate to test, relative to @widget's origin Creates a new shortcut for @widget_class that calls the given @callback with arguments read according to @format_string. The arguments and format string must be provided in the same way as with g_variant_new(). This function is a convenience wrapper around [method@Gtk.WidgetClass.add_shortcut] and must be called during class initialization. It does not provide for user_data, if you need that, you will have to use [method@Gtk.WidgetClass.add_shortcut] with a custom shortcut. the class to add the binding to key value of binding to install key modifier of binding to install the callback to call upon activation GVariant format string for arguments or %NULL for no arguments arguments, as given by format string Creates a new shortcut for @widget_class that activates the given @action_name with arguments read according to @format_string. The arguments and format string must be provided in the same way as with g_variant_new(). This function is a convenience wrapper around [method@Gtk.WidgetClass.add_shortcut] and must be called during class initialization. the class to add the binding to key value of binding to install key modifier of binding to install the action to activate GVariant format string for arguments or %NULL for no arguments arguments, as given by format string Creates a new shortcut for @widget_class that emits the given action @signal with arguments read according to @format_string. The arguments and format string must be provided in the same way as with g_variant_new(). This function is a convenience wrapper around [method@Gtk.WidgetClass.add_shortcut] and must be called during class initialization. the class to add the binding to key value of binding to install key modifier of binding to install the signal to execute GVariant format string for arguments or %NULL for no arguments arguments, as given by format string Installs a shortcut in @widget_class. Every instance created for @widget_class or its subclasses will inherit this shortcut and trigger it. Shortcuts added this way will be triggered in the %GTK_PHASE_BUBBLE phase, which means they may also trigger if child widgets have focus. This function must only be used in class initialization functions otherwise it is not guaranteed that the shortcut will be installed. the class to add the shortcut to the `GtkShortcut` to add Declares a @callback_symbol to handle @callback_name from the template XML defined for @widget_type. This function is not supported after [method@Gtk.WidgetClass.set_template_scope] has been used on @widget_class. See [method@Gtk.BuilderCScope.add_callback_symbol]. Note that this must be called from a composite widget classes class initializer after calling [method@Gtk.WidgetClass.set_template]. A `GtkWidgetClass` The name of the callback as expected in the template XML The callback symbol Automatically assign an object declared in the class template XML to be set to a location on a freshly built instance’s private data, or alternatively accessible via [method@Gtk.Widget.get_template_child]. The struct can point either into the public instance, then you should use `G_STRUCT_OFFSET(WidgetType, member)` for @struct_offset, or in the private struct, then you should use `G_PRIVATE_OFFSET(WidgetType, member)`. An explicit strong reference will be held automatically for the duration of your instance’s life cycle, it will be released automatically when `GObjectClass.dispose()` runs on your instance and if a @struct_offset that is `!= 0` is specified, then the automatic location in your instance public or private data will be set to %NULL. You can however access an automated child pointer the first time your classes `GObjectClass.dispose()` runs, or alternatively in [signal@Gtk.Widget::destroy]. If @internal_child is specified, [vfunc@Gtk.Buildable.get_internal_child] will be automatically implemented by the `GtkWidget` class so there is no need to implement it manually. The wrapper macros [func@Gtk.widget_class_bind_template_child], [func@Gtk.widget_class_bind_template_child_internal], [func@Gtk.widget_class_bind_template_child_private] and [func@Gtk.widget_class_bind_template_child_internal_private] might be more convenient to use. Note that this must be called from a composite widget classes class initializer after calling [method@Gtk.WidgetClass.set_template]. A `GtkWidgetClass` The “id” of the child defined in the template XML Whether the child should be accessible as an “internal-child” when this class is used in GtkBuilder XML The structure offset into the composite widget’s instance public or private structure where the automated child pointer should be set, or 0 to not assign the pointer. Retrieves the accessible role used by the given `GtkWidget` class. Different accessible roles have different states, and are rendered differently by assistive technologies. See also: [method@Gtk.Accessible.get_accessible_role]. the accessible role for the widget class a `GtkWidgetClass` Retrieves the signal id for the activation signal. the activation signal is set using [method@Gtk.WidgetClass.set_activate_signal]. a signal id, or 0 if the widget class does not specify an activation signal a `GtkWidgetClass` Gets the name used by this class for matching in CSS code. See [method@Gtk.WidgetClass.set_css_name] for details. the CSS name of the given class class to set the name on Retrieves the type of the [class@Gtk.LayoutManager] used by widgets of class @widget_class. See also: [method@Gtk.WidgetClass.set_layout_manager_type]. type of a `GtkLayoutManager` subclass, or %G_TYPE_INVALID a `GtkWidgetClass` This should be called at class initialization time to specify actions to be added for all instances of this class. Actions installed by this function are stateless. The only state they have is whether they are enabled or not (which can be changed with [method@Gtk.Widget.action_set_enabled]). a `GtkWidgetClass` a prefixed action name, such as "clipboard.paste" the parameter type callback to use when the action is activated Installs an action called @action_name on @widget_class and binds its state to the value of the @property_name property. This function will perform a few sanity checks on the property selected via @property_name. Namely, the property must exist, must be readable, writable and must not be construct-only. There are also restrictions on the type of the given property, it must be boolean, int, unsigned int, double or string. If any of these conditions are not met, a critical warning will be printed and no action will be added. The state type of the action matches the property type. If the property is boolean, the action will have no parameter and toggle the property value. Otherwise, the action will have a parameter of the same type as the property. a `GtkWidgetClass` name of the action name of the property in instances of @widget_class or any parent class. Returns details about the @index_-th action that has been installed for @widget_class during class initialization. See [method@Gtk.WidgetClass.install_action] for details on how to install actions. Note that this function will also return actions defined by parent classes. You can identify those by looking at @owner. %TRUE if the action was found, %FALSE if @index_ is out of range a `GtkWidget` class position of the action to query return location for the type where the action was defined return location for the action name return location for the parameter type return location for the property name Sets the accessible role used by the given `GtkWidget` class. Different accessible roles have different states, and are rendered differently by assistive technologies. a `GtkWidgetClass` the `GtkAccessibleRole` used by the @widget_class Sets the `GtkWidgetClass.activate_signal` field with the given @signal_id. The signal will be emitted when calling [method@Gtk.Widget.activate]. The @signal_id must have been registered with `g_signal_new()` or g_signal_newv() before calling this function. a `GtkWidgetClass` the id for the activate signal Sets the `GtkWidgetClass.activate_signal` field with the signal id for the given @signal_name. The signal will be emitted when calling [method@Gtk.Widget.activate]. The @signal_name of @widget_type must have been registered with g_signal_new() or g_signal_newv() before calling this function. a `GtkWidgetClass` the name of the activate signal of @widget_type Sets the name to be used for CSS matching of widgets. If this function is not called for a given class, the name set on the parent class is used. By default, `GtkWidget` uses the name "widget". class to set the name on name to use Sets the type to be used for creating layout managers for widgets of @widget_class. The given @type must be a subtype of [class@Gtk.LayoutManager]. This function should only be called from class init functions of widgets. a `GtkWidgetClass` The object type that implements the `GtkLayoutManager` for @widget_class This should be called at class initialization time to specify the `GtkBuilder` XML to be used to extend a widget. For convenience, [method@Gtk.WidgetClass.set_template_from_resource] is also provided. Note that any class that installs templates must call [method@Gtk.Widget.init_template] in the widget’s instance initializer. A `GtkWidgetClass` A `GBytes` holding the `GtkBuilder` XML A convenience function that calls [method@Gtk.WidgetClass.set_template] with the contents of a `GResource`. Note that any class that installs templates must call [method@Gtk.Widget.init_template] in the widget’s instance initializer. A `GtkWidgetClass` The name of the resource to load the template from For use in language bindings, this will override the default `GtkBuilderScope` to be used when parsing GtkBuilder XML from this class’s template data. Note that this must be called from a composite widget classes class initializer after calling [method@Gtk.WidgetClass.set_template]. A `GtkWidgetClass` The `GtkBuilderScope` to use when loading the class template `GtkWidgetPaintable` is a `GdkPaintable` that displays the contents of a widget. `GtkWidgetPaintable` will also take care of the widget not being in a state where it can be drawn (like when it isn't shown) and just draw nothing or where it does not have a size (like when it is hidden) and report no size in that case. Of course, `GtkWidgetPaintable` allows you to monitor widgets for size changes by emitting the [signal@Gdk.Paintable::invalidate-size] signal whenever the size of the widget changes as well as for visual changes by emitting the [signal@Gdk.Paintable::invalidate-contents] signal whenever the widget changes. You can use a `GtkWidgetPaintable` everywhere a `GdkPaintable` is allowed, including using it on a `GtkPicture` (or one of its parents) that it was set on itself via gtk_picture_set_paintable(). The paintable will take care of recursion when this happens. If you do this however, ensure that the [property@Gtk.Picture:can-shrink] property is set to %TRUE or you might end up with an infinitely growing widget. Creates a new widget paintable observing the given widget. a new `GtkWidgetPaintable` a `GtkWidget` Returns the widget that is observed or %NULL if none. the observed widget. a `GtkWidgetPaintable` Sets the widget that should be observed. a `GtkWidgetPaintable` the widget to observe The observed widget or %NULL if none. A `GtkWindow` is a toplevel window which can contain other widgets.  Windows normally have decorations that are under the control of the windowing system and allow the user to manipulate the window (resize it, move it, close it,...). # GtkWindow as GtkBuildable The `GtkWindow` implementation of the [iface@Gtk.Buildable] interface supports setting a child as the titlebar by specifying “titlebar” as the “type” attribute of a `<child>` element. # Shortcuts and Gestures `GtkWindow` supports the following keyboard shortcuts: - <kbd>F10</kbd> activates the menubar, if present. - <kbd>Alt</kbd> makes the mnemonics visible while pressed. The following signals have default keybindings: - [signal@Gtk.Window::activate-default] - [signal@Gtk.Window::activate-focus] - [signal@Gtk.Window::enable-debugging] # Actions `GtkWindow` defines a set of built-in actions: - `default.activate` activates the default widget. - `window.minimize` minimizes the window. - `window.toggle-maximized` maximizes or restores the window. - `window.close` closes the window. # CSS nodes ``` window.background [.csd / .solid-csd / .ssd] [.maximized / .fullscreen / .tiled] ├── <child> ╰── <titlebar child>.titlebar [.default-decoration] ``` `GtkWindow` has a main CSS node with name window and style class .background. Style classes that are typically used with the main CSS node are .csd (when client-side decorations are in use), .solid-csd (for client-side decorations without invisible borders), .ssd (used by mutter when rendering server-side decorations). GtkWindow also represents window states with the following style classes on the main node: .maximized, .fullscreen, .tiled (when supported, also .tiled-top, .tiled-left, .tiled-right, .tiled-bottom). `GtkWindow` subclasses often add their own discriminating style classes, such as .dialog, .popup or .tooltip. Generally, some CSS properties don't make sense on the toplevel window node, such as margins or padding. When client-side decorations without invisible borders are in use (i.e. the .solid-csd style class is added to the main window node), the CSS border of the toplevel window is used for resize drags. In the .csd case, the shadow area outside of the window can be used to resize it. `GtkWindow` adds the .titlebar and .default-decoration style classes to the widget that is added as a titlebar child. # Accessibility Until GTK 4.10, `GtkWindow` used the `GTK_ACCESSIBLE_ROLE_WINDOW` role. Since GTK 4.12, `GtkWindow` uses the `GTK_ACCESSIBLE_ROLE_APPLICATION` role. Creates a new `GtkWindow`. To get an undecorated window (no window borders), use [method@Gtk.Window.set_decorated]. All top-level windows created by gtk_window_new() are stored in an internal top-level window list. This list can be obtained from [func@Gtk.Window.list_toplevels]. Due to GTK keeping a reference to the window internally, gtk_window_new() does not return a reference to the caller. To delete a `GtkWindow`, call [method@Gtk.Window.destroy]. a new `GtkWindow`. Returns the fallback icon name for windows. The returned string is owned by GTK and should not be modified. It is only valid until the next call to [func@Gtk.Window.set_default_icon_name]. the fallback icon name for windows Returns a list of all existing toplevel windows. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets or add new ones, be aware that the list of toplevels will change and emit the "items-changed" signal. the list of toplevel widgets Returns a list of all existing toplevel windows. The widgets in the list are not individually referenced. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets, you must call `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first, and then unref all the widgets afterwards. list of toplevel widgets Sets whether the window should request startup notification. By default, after showing the first `GtkWindow`, GTK calls [method@Gdk.Toplevel.set_startup_id]. Call this function to disable the automatic startup notification. You might do this if your first window is a splash screen, and you want to delay notification until after your real main window has been shown, for example. In that example, you would disable startup notification temporarily, show your splash screen, then re-enable it so that showing the main window would automatically result in notification. %TRUE to automatically do startup notification Sets an icon to be used as fallback. The fallback icon is used for windows that haven't had [method@Gtk.Window.set_icon_name] called on them. the name of the themed icon Opens or closes the [interactive debugger](running.html#interactive-debugging). The debugger offers access to the widget hierarchy of the application and to useful debugging tools. %TRUE to enable interactive debugging Activates the default widget for the window. Activates the current focused widget within the window. Class handler for the `GtkWindow::close-request` signal. Class handler for the `GtkWindow::enable-debugging` keybinding signal. Signal gets emitted when the set of accelerators or mnemonics that are associated with window changes. Requests that the window is closed. This is similar to what happens when a window manager close button is clicked. This function can be used with close buttons in custom titlebars. a `GtkWindow` Drop the internal reference GTK holds on toplevel windows. The window to destroy Asks to place @window in the fullscreen state. Note that you shouldn’t assume the window is definitely fullscreen afterward, because other entities (e.g. the user or window manager) unfullscreen it again, and not all window managers honor requests to fullscreen windows. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications of the [property@Gtk.Window:fullscreened] property. a `GtkWindow` Asks to place @window in the fullscreen state on the given @monitor. Note that you shouldn't assume the window is definitely fullscreen afterward, or that the windowing system allows fullscreen windows on any given monitor. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications of the [property@Gtk.Window:fullscreened] property. a `GtkWindow` which monitor to go fullscreen on Gets the `GtkApplication` associated with the window. a `GtkApplication` a `GtkWindow` Gets the child widget of @window. the child widget of @window a `GtkWindow` Returns whether the window has been set to have decorations. %TRUE if the window has been set to have decorations a `GtkWindow` Gets the default size of the window. A value of 0 for the width or height indicates that a default size has not been explicitly set for that dimension, so the “natural” size of the window will be used. This function is the recommended way for [saving window state across restarts of applications](https://developer.gnome.org/documentation/tutorials/save-state.html). a `GtkWindow` location to store the default width location to store the default height Returns the default widget for @window. the default widget a `GtkWindow` Returns whether the window has been set to have a close button. %TRUE if the window has been set to have a close button a `GtkWindow` Returns whether the window will be destroyed with its transient parent. %TRUE if the window will be destroyed with its transient parent. a `GtkWindow` Retrieves the current focused widget within the window. Note that this is the widget that would have the focus if the toplevel window focused; if the toplevel window is not focused then `gtk_widget_has_focus (widget)` will not be %TRUE for the widget. the currently focused widget a `GtkWindow` Gets whether “focus rectangles” are supposed to be visible. %TRUE if “focus rectangles” are supposed to be visible in this window. a `GtkWindow` Returns the group for @window. If the window has no group, then the default group is returned. the `GtkWindowGroup` for a window or the default group a `GtkWindow` Returns whether this window reacts to F10 key presses by activating a menubar it contains. %TRUE if the window handles F10 a `GtkWindow` Returns whether the window will be hidden when the close button is clicked. %TRUE if the window will be hidden a `GtkWindow` Returns the name of the themed icon for the window. the icon name a `GtkWindow` Gets whether mnemonics are supposed to be visible. %TRUE if mnemonics are supposed to be visible in this window. a `GtkWindow` Returns whether the window is modal. %TRUE if the window is set to be modal and establishes a grab when shown a `GtkWindow` Gets the value set by gtk_window_set_resizable(). %TRUE if the user can resize the window a `GtkWindow` Retrieves the title of the window. the title of the window a `GtkWindow` Returns the custom titlebar that has been set with gtk_window_set_titlebar(). the custom titlebar a `GtkWindow` Fetches the transient parent for this window. the transient parent for this window a `GtkWindow` Returns whether @window has an explicit window group. %TRUE if @window has an explicit window group. a `GtkWindow` Returns whether the window is part of the current active toplevel. The active toplevel is the window receiving keystrokes. The return value is %TRUE if the window is active toplevel itself. You might use this function if you wanted to draw a widget differently in an active window from a widget in an inactive window. %TRUE if the window part of the current active window. a `GtkWindow` Retrieves the current fullscreen state of @window. Note that since fullscreening is ultimately handled by the window manager and happens asynchronously to an application request, you shouldn’t assume the return value of this function changing immediately (or at all), as an effect of calling [method@Gtk.Window.fullscreen] or [method@Gtk.Window.unfullscreen]. If the window isn't yet mapped, the value returned will whether the initial requested state is fullscreen. whether the window has a fullscreen state. a `GtkWindow` Retrieves the current maximized state of @window. Note that since maximization is ultimately handled by the window manager and happens asynchronously to an application request, you shouldn’t assume the return value of this function changing immediately (or at all), as an effect of calling [method@Gtk.Window.maximize] or [method@Gtk.Window.unmaximize]. If the window isn't yet mapped, the value returned will whether the initial requested state is maximized. whether the window has a maximized state. a `GtkWindow` Retrieves the current suspended state of @window. A window being suspended means it's currently not visible to the user, for example by being on a inactive workspace, minimized, obstructed. whether the window is suspended. a `GtkWindow` Asks to maximize @window, so that it fills the screen. Note that you shouldn’t assume the window is definitely maximized afterward, because other entities (e.g. the user or window manager) could unmaximize it again, and not all window managers support maximization. It’s permitted to call this function before showing a window, in which case the window will be maximized when it appears onscreen initially. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications on the [property@Gtk.Window:maximized] property. a `GtkWindow` Asks to minimize the specified @window. Note that you shouldn’t assume the window is definitely minimized afterward, because the windowing system might not support this functionality; other entities (e.g. the user or the window manager) could unminimize it again, or there may not be a window manager in which case minimization isn’t possible, etc. It’s permitted to call this function before showing a window, in which case the window will be minimized before it ever appears onscreen. You can track result of this operation via the [property@Gdk.Toplevel:state] property. a `GtkWindow` Presents a window to the user. This may mean raising the window in the stacking order, unminimizing it, moving it to the current desktop and/or giving it the keyboard focus (possibly dependent on the user’s platform, window manager and preferences). If @window is hidden, this function also makes it visible. a `GtkWindow` Presents a window to the user in response to an user interaction. See [method@Gtk.Window.present] for more details. The timestamp should be gathered when the window was requested to be shown (when clicking a link for example), rather than once the window is ready to be shown. Use gtk_window_present() a `GtkWindow` the timestamp of the user interaction (typically a button or key press event) which triggered this call Sets or unsets the `GtkApplication` associated with the window. The application will be kept alive for at least as long as it has any windows associated with it (see g_application_hold() for a way to keep it alive without windows). Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it by setting the @application to %NULL. This is equivalent to calling [method@Gtk.Application.remove_window] and/or [method@Gtk.Application.add_window] on the old/new applications as relevant. a `GtkWindow` a `GtkApplication`, or %NULL to unset Sets the child widget of @window. a `GtkWindow` the child widget Sets whether the window should be decorated. By default, windows are decorated with a title bar, resize controls, etc. Some window managers allow GTK to disable these decorations, creating a borderless window. If you set the decorated property to %FALSE using this function, GTK will do its best to convince the window manager not to decorate the window. Depending on the system, this function may not have any effect when called on a window that is already visible, so you should call it before calling [method@Gtk.Widget.show]. On Windows, this function always works, since there’s no window manager policy involved. a `GtkWindow` %TRUE to decorate the window Sets the default size of a window. The default size of a window is the size that will be used if no other constraints apply. The default size will be updated whenever the window is resized to reflect the new size, unless the window is forced to a size, like when it is maximized or fullscreened. If the window’s minimum size request is larger than the default, the default will be ignored. Setting the default size to a value <= 0 will cause it to be ignored and the natural size request will be used instead. It is possible to do this while the window is showing to "reset" it to its initial size. Unlike [method@Gtk.Widget.set_size_request], which sets a size request for a widget and thus would keep users from shrinking the window, this function only sets the initial size, just as if the user had resized the window themselves. Users can still shrink the window again as they normally would. Setting a default size of -1 means to use the “natural” default size (the size request of the window). If you use this function to reestablish a previously saved window size, note that the appropriate size to save is the one returned by [method@Gtk.Window.get_default_size]. Using the window allocation directly will not work in all circumstances and can lead to growing or shrinking windows. a `GtkWindow` width in pixels, or -1 to unset the default width height in pixels, or -1 to unset the default height Sets the default widget. The default widget is the widget that is activated when the user presses Enter in a dialog (for example). a `GtkWindow` widget to be the default to unset the default widget for the toplevel Sets whether the window should be deletable. By default, windows have a close button in the window frame. Some window managers allow GTK to disable this button. If you set the deletable property to %FALSE using this function, GTK will do its best to convince the window manager not to show a close button. Depending on the system, this function may not have any effect when called on a window that is already visible, so you should call it before calling [method@Gtk.Widget.show]. On Windows, this function always works, since there’s no window manager policy involved. a `GtkWindow` %TRUE to decorate the window as deletable If @setting is %TRUE, then destroying the transient parent of @window will also destroy @window itself. This is useful for dialogs that shouldn’t persist beyond the lifetime of the main window they are associated with, for example. a `GtkWindow` whether to destroy @window with its transient parent Sets the `GdkDisplay` where the @window is displayed. If the window is already mapped, it will be unmapped, and then remapped on the new display. a `GtkWindow` a `GdkDisplay` Sets the focus widget. If @focus is not the current focus widget, and is focusable, sets it as the focus widget for the window. If @focus is %NULL, unsets the focus widget for this window. To set the focus to a particular widget in the toplevel, it is usually more convenient to use [method@Gtk.Widget.grab_focus] instead of this function. a `GtkWindow` widget to be the new focus widget, or %NULL to unset any focus widget for the toplevel window. Sets whether “focus rectangles” are supposed to be visible. This property is maintained by GTK based on user input, and should not be set by applications. a `GtkWindow` the new value Sets whether this window should react to F10 key presses by activating a menubar it contains. a `GtkWindow` %TRUE to make @window handle F10 If @setting is %TRUE, then clicking the close button on the window will not destroy it, but only hide it. a `GtkWindow` whether to hide the window when it is closed Sets the icon for the window from a named themed icon. See the docs for [class@Gtk.IconTheme] for more details. On some platforms, the window icon is not used at all. Note that this has nothing to do with the WM_ICON_NAME property which is mentioned in the ICCCM. a `GtkWindow` the name of the themed icon Sets whether mnemonics are supposed to be visible. This property is maintained by GTK based on user input, and should not be set by applications. a `GtkWindow` the new value Sets a window modal or non-modal. Modal windows prevent interaction with other windows in the same application. To keep modal dialogs on top of main application windows, use [method@Gtk.Window.set_transient_for] to make the dialog transient for the parent; most window managers will then disallow lowering the dialog below the parent. a `GtkWindow` whether the window is modal Sets whether the user can resize a window. Windows are user resizable by default. a `GtkWindow` %TRUE if the user can resize this window Sets the startup notification ID. Startup notification identifiers are used by desktop environment to track application startup, to provide user feedback and other features. This function changes the corresponding property on the underlying `GdkSurface`. Normally, startup identifier is managed automatically and you should only use this function in special cases like transferring focus from other processes. You should use this function before calling [method@Gtk.Window.present] or any equivalent function generating a window map event. This function is only useful on X11, not with other GTK targets. a `GtkWindow` a string with startup-notification identifier Sets the title of the `GtkWindow`. The title of a window will be displayed in its title bar; on the X Window System, the title bar is rendered by the window manager so exactly how the title appears to users may vary according to a user’s exact configuration. The title should help a user distinguish this window from other windows they may have open. A good title might include the application name and current document filename, for example. Passing %NULL does the same as setting the title to an empty string. a `GtkWindow` title of the window Sets a custom titlebar for @window. A typical widget used here is [class@Gtk.HeaderBar], as it provides various features expected of a titlebar while allowing the addition of child widgets to it. If you set a custom titlebar, GTK will do its best to convince the window manager not to put its own titlebar on the window. Depending on the system, this function may not work for a window that is already visible, so you set the titlebar before calling [method@Gtk.Widget.show]. a `GtkWindow` the widget to use as titlebar Dialog windows should be set transient for the main application window they were spawned from. This allows window managers to e.g. keep the dialog on top of the main window, or center the dialog over the main window. [ctor@Gtk.Dialog.new_with_buttons] and other convenience functions in GTK will sometimes call gtk_window_set_transient_for() on your behalf. Passing %NULL for @parent unsets the current transient window. On Windows, this function puts the child window on top of the parent, much as the window manager would have done on X. a `GtkWindow` parent window Asks to remove the fullscreen state for @window, and return to its previous state. Note that you shouldn’t assume the window is definitely not fullscreen afterward, because other entities (e.g. the user or window manager) could fullscreen it again, and not all window managers honor requests to unfullscreen windows; normally the window will end up restored to its normal state. Just don’t write code that crashes if not. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications of the [property@Gtk.Window:fullscreened] property. a `GtkWindow` Asks to unmaximize @window. Note that you shouldn’t assume the window is definitely unmaximized afterward, because other entities (e.g. the user or window manager) maximize it again, and not all window managers honor requests to unmaximize. You can track the result of this operation via the [property@Gdk.Toplevel:state] property, or by listening to notifications on the [property@Gtk.Window:maximized] property. a `GtkWindow` Asks to unminimize the specified @window. Note that you shouldn’t assume the window is definitely unminimized afterward, because the windowing system might not support this functionality; other entities (e.g. the user or the window manager) could minimize it again, or there may not be a window manager in which case minimization isn’t possible, etc. You can track result of this operation via the [property@Gdk.Toplevel:state] property. a `GtkWindow` The `GtkApplication` associated with the window. The application will be kept alive for at least as long as it has any windows associated with it (see g_application_hold() for a way to keep it alive without windows). Normally, the connection between the application and the window will remain until the window is destroyed, but you can explicitly remove it by setting the :application property to %NULL. The child widget. Whether the window should have a frame (also known as *decorations*). The default height of the window. The default widget. The default width of the window. Whether the window frame should have a close button. If this window should be destroyed when the parent is destroyed. The display that will display this window. Whether 'focus rectangles' are currently visible in this window. This property is maintained by GTK based on user input and should not be set by applications. The focus widget. Whether the window is fullscreen. Setting this property is the equivalent of calling [method@Gtk.Window.fullscreen] or [method@Gtk.Window.unfullscreen]; either operation is asynchronous, which means you will need to connect to the ::notify signal in order to know whether the operation was successful. Whether the window frame should handle F10 for activating menubars. If this window should be hidden when the users clicks the close button. Specifies the name of the themed icon to use as the window icon. See [class@Gtk.IconTheme] for more details. Whether the toplevel is the currently active window. Whether the window is maximized. Setting this property is the equivalent of calling [method@Gtk.Window.maximize] or [method@Gtk.Window.unmaximize]; either operation is asynchronous, which means you will need to connect to the ::notify signal in order to know whether the operation was successful. Whether mnemonics are currently visible in this window. This property is maintained by GTK based on user input, and should not be set by applications. If %TRUE, the window is modal. If %TRUE, users can resize the window. A write-only property for setting window's startup notification identifier. Whether the window is suspended. See [method@Gtk.Window.is_suspended] for details about what suspended means. The title of the window. The titlebar widget. The transient parent of the window. Emitted when the user activates the default widget of @window. This is a [keybinding signal](class.SignalAction.html). The keybindings for this signal are all forms of the <kbd>Enter</kbd> key. Emitted when the user activates the currently focused widget of @window. This is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>␣</kbd>. Emitted when the user clicks on the close button of the window. %TRUE to stop other handlers from being invoked for the signal Emitted when the user enables or disables interactive debugging. When @toggle is %TRUE, interactive debugging is toggled on or off, when it is %FALSE, the debugger will be pointed at the widget under the pointer. This is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>I</kbd> and <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>. %TRUE if the key binding was handled toggle the debugger emitted when the set of accelerators or mnemonics that are associated with @window changes. Use [class@Gtk.Shortcut] and [class@Gtk.EventController] to implement keyboard shortcuts The parent class. Activates the current focused widget within the window. Activates the default widget for the window. Signal gets emitted when the set of accelerators or mnemonics that are associated with window changes. Class handler for the `GtkWindow::enable-debugging` keybinding signal. Class handler for the `GtkWindow::close-request` signal. `GtkWindowControls` shows window frame controls. Typical window frame controls are minimize, maximize and close buttons, and the window icon.  `GtkWindowControls` only displays start or end side of the controls (see [property@Gtk.WindowControls:side]), so it's intended to be always used in pair with another `GtkWindowControls` for the opposite side, for example: ```xml <object class="GtkBox"> <child> <object class="GtkWindowControls"> <property name="side">start</property> </object> </child> ... <child> <object class="GtkWindowControls"> <property name="side">end</property> </object> </child> </object> ``` # CSS nodes ``` windowcontrols ├── [image.icon] ├── [button.minimize] ├── [button.maximize] ╰── [button.close] ``` A `GtkWindowControls`' CSS node is called windowcontrols. It contains subnodes corresponding to each title button. Which of the title buttons exist and where they are placed exactly depends on the desktop environment and [property@Gtk.WindowControls:decoration-layout] value. When [property@Gtk.WindowControls:empty] is %TRUE, it gets the .empty style class. # Accessibility `GtkWindowControls` uses the %GTK_ACCESSIBLE_ROLE_GROUP role. Creates a new `GtkWindowControls`. a new `GtkWindowControls`. the side Gets the decoration layout of this `GtkWindowControls`. the decoration layout or %NULL if it is unset a `GtkWindowControls` Gets whether the widget has any window buttons. %TRUE if the widget has window buttons, otherwise %FALSE a `GtkWindowControls` Gets the side to which this `GtkWindowControls` instance belongs. the side a `GtkWindowControls` Sets the decoration layout for the title buttons. This overrides the [property@Gtk.Settings:gtk-decoration-layout] setting. The format of the string is button names, separated by commas. A colon separates the buttons that should appear on the left from those on the right. Recognized button names are minimize, maximize, close and icon (the window icon). For example, “icon:minimize,maximize,close” specifies a icon on the left, and minimize, maximize and close buttons on the right. If [property@Gtk.WindowControls:side] value is @GTK_PACK_START, @self will display the part before the colon, otherwise after that. a `GtkWindowControls` a decoration layout, or %NULL to unset the layout Determines which part of decoration layout the `GtkWindowControls` uses. See [property@Gtk.WindowControls:decoration-layout]. a `GtkWindowControls` a side The decoration layout for window buttons. If this property is not set, the [property@Gtk.Settings:gtk-decoration-layout] setting is used. Whether the widget has any window buttons. Whether the widget shows start or end side of the decoration layout. See [property@Gtk.WindowControls:decoration_layout]. `GtkWindowGroup` makes group of windows behave like separate applications. It achieves this by limiting the effect of GTK grabs and modality to windows in the same group. A window can be a member in at most one window group at a time. Windows that have not been explicitly assigned to a group are implicitly treated like windows of the default window group. `GtkWindowGroup` objects are referenced by each window in the group, so once you have added all windows to a `GtkWindowGroup`, you can drop the initial reference to the window group with g_object_unref(). If the windows in the window group are subsequently destroyed, then they will be removed from the window group and drop their references on the window group; when all window have been removed, the window group will be freed. Creates a new `GtkWindowGroup` object. Modality of windows only affects windows within the same `GtkWindowGroup`. a new `GtkWindowGroup`. Adds a window to a `GtkWindowGroup`. a `GtkWindowGroup` the `GtkWindow` to add Returns a list of the `GtkWindows` that belong to @window_group. A newly-allocated list of windows inside the group. a `GtkWindowGroup` Removes a window from a `GtkWindowGroup`. a `GtkWindowGroup` the `GtkWindow` to remove `GtkWindowHandle` is a titlebar area widget. When added into a window, it can be dragged to move the window, and handles right click, double click and middle click as expected of a titlebar. # CSS nodes `GtkWindowHandle` has a single CSS node with the name `windowhandle`. # Accessibility Until GTK 4.10, `GtkWindowHandle` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. Starting from GTK 4.12, `GtkWindowHandle` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. Creates a new `GtkWindowHandle`. a new `GtkWindowHandle`. Gets the child widget of @self. the child widget of @self a `GtkWindowHandle` Sets the child widget of @self. a `GtkWindowHandle` the child widget The child widget. Describes a type of line wrapping. do not wrap lines; just make the text area wider wrap text, breaking lines anywhere the cursor can appear (between characters, usually - if you want to be technical, between graphemes, see pango_get_log_attrs()) wrap text, breaking lines in between words wrap text, breaking lines in between words, or if that is not enough, also between graphemes Gets the modifier mask. The modifier mask determines which modifiers are considered significant for keyboard accelerators. This includes all keyboard modifiers except for %GDK_LOCK_MASK. the modifier mask for accelerators Converts an accelerator keyval and modifier mask into a string which can be used to represent the accelerator to the user. a newly-allocated string representing the accelerator accelerator keyval accelerator modifier mask Converts an accelerator keyval and modifier mask into a string that can be displayed to the user. The string may be translated. This function is similar to [func@Gtk.accelerator_get_label], but handling keycodes. This is only useful for system-level components, applications should use [func@Gtk.accelerator_get_label] instead. a newly-allocated string representing the accelerator a `GdkDisplay` or %NULL to use the default display accelerator keyval accelerator keycode accelerator modifier mask Converts an accelerator keyval and modifier mask into a string parseable by gtk_accelerator_parse(). For example, if you pass in %GDK_KEY_q and %GDK_CONTROL_MASK, this function returns `<Control>q`. If you need to display accelerators in the user interface, see [func@Gtk.accelerator_get_label]. a newly-allocated accelerator name accelerator keyval accelerator modifier mask Converts an accelerator keyval and modifier mask into a string parseable by gtk_accelerator_parse_with_keycode(). This is similar to [func@Gtk.accelerator_name] but handling keycodes. This is only useful for system-level components, applications should use [func@Gtk.accelerator_name] instead. a newly allocated accelerator name. a `GdkDisplay` or %NULL to use the default display accelerator keyval accelerator keycode accelerator modifier mask Parses a string representing an accelerator. The format looks like “`<Control>a`” or “`<Shift><Alt>F1`”. The parser is fairly liberal and allows lower or upper case, and also abbreviations such as “`<Ctl>`” and “`<Ctrl>`”. Key names are parsed using [func@Gdk.keyval_from_name]. For character keys the name is not the symbol, but the lowercase name, e.g. one would use “`<Ctrl>minus`” instead of “`<Ctrl>-`”. Modifiers are enclosed in angular brackets `<>`, and match the [flags@Gdk.ModifierType] mask: - `<Shift>` for `GDK_SHIFT_MASK` - `<Ctrl>` for `GDK_CONTROL_MASK` - `<Alt>` for `GDK_ALT_MASK` - `<Meta>` for `GDK_META_MASK` - `<Super>` for `GDK_SUPER_MASK` - `<Hyper>` for `GDK_HYPER_MASK` If the parse operation fails, @accelerator_key and @accelerator_mods will be set to 0 (zero). whether parsing succeeded string representing an accelerator return location for accelerator keyval return location for accelerator modifier mask Parses a string representing an accelerator. This is similar to [func@Gtk.accelerator_parse] but handles keycodes as well. This is only useful for system-level components, applications should use [func@Gtk.accelerator_parse] instead. If @accelerator_codes is given and the result stored in it is non-%NULL, the result must be freed with g_free(). If a keycode is present in the accelerator and no @accelerator_codes is given, the parse will fail. If the parse fails, @accelerator_key, @accelerator_mods and @accelerator_codes will be set to 0 (zero). %TRUE if parsing succeeded string representing an accelerator the `GdkDisplay` to look up @accelerator_codes in return location for accelerator keyval return location for accelerator keycodes return location for accelerator modifier mask Determines whether a given keyval and modifier mask constitute a valid keyboard accelerator. For example, the %GDK_KEY_a keyval plus %GDK_CONTROL_MASK mark is valid, and matches the “Ctrl+a” accelerator. But, you can't, for instance, use the %GDK_KEY_Control_L keyval as an accelerator. %TRUE if the accelerator is valid a GDK keyval modifier mask Initializes @value with the appropriate type for the @property. This function is mostly meant for language bindings, in conjunction with gtk_accessible_update_property_value(). a `GtkAccessibleProperty` an uninitialized `GValue` Initializes @value with the appropriate type for the @relation. This function is mostly meant for language bindings, in conjunction with gtk_accessible_update_relation_value(). a `GtkAccessibleRelation` an uninitialized `GValue` Initializes @value with the appropriate type for the @state. This function is mostly meant for language bindings, in conjunction with gtk_accessible_update_relation_state(). a `GtkAccessibleState` an uninitialized `GValue` Initializes @iter to point to @target. If @target is not found, finds the next value after it. If no value >= @target exists in @set, this function returns %FALSE. %TRUE if a value was found. a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` target value to start iterating at Set to the found value in @set Initializes an iterator for @set and points it to the first value in @set. If @set is empty, %FALSE is returned and @value is set to %G_MAXUINT. %TRUE if @set isn't empty. a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` Set to the first value in @set Initializes an iterator for @set and points it to the last value in @set. If @set is empty, %FALSE is returned. %TRUE if @set isn't empty. a pointer to an uninitialized `GtkBitsetIter` a `GtkBitset` Set to the last value in @set Adds the @callback to the scope of @builder under its own name. This is a convenience wrapper of [method@Gtk.BuilderCScope.add_callback_symbol]. a `GtkBuilderCScope` The callback pointer Registers an error quark for [class@Gtk.Builder] errors. the error quark Checks that the GTK library in use is compatible with the given version. Generally you would pass in the constants %GTK_MAJOR_VERSION, %GTK_MINOR_VERSION, %GTK_MICRO_VERSION as the three arguments to this function; that produces a check that the library in use is compatible with the version of GTK the application or module was compiled against. Compatibility is defined by two things: first the version of the running library is newer than the version @required_major.required_minor.@required_micro. Second the running library must be binary compatible with the version @required_major.required_minor.@required_micro (same major version.) This function is primarily for GTK modules; the module can call this function to check that it wasn’t loaded into an incompatible version of GTK. However, such a check isn’t completely reliable, since the module may be linked against an old version of GTK and calling the old version of gtk_check_version(), but still get loaded into an application using a newer version of GTK. %NULL if the GTK library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by GTK and should not be modified or freed. the required major version the required minor version the required micro version Registers an error quark for VFL error parsing. the error quark Registers an error quark for CSS parsing errors. the error quark Registers an error quark for CSS parsing warnings. the warning quark Registers an error quark for an operation that requires a dialog if necessary. the error quark Prevents [func@Gtk.init] and [func@Gtk.init_check] from automatically calling `setlocale (LC_ALL, "")`. You would want to use this function if you wanted to set the locale for your program to something other than the user’s locale, or if you wanted to set different values for different locale categories. Most programs should not need to call this function. Distributes @extra_space to child @sizes by bringing smaller children up to natural size first. The remaining space will be added to the @minimum_size member of the `GtkRequestedSize` struct. If all sizes reach their natural size then the remaining space is returned. The remainder of @extra_space after redistributing space to @sizes. Extra space to redistribute among children after subtracting minimum sizes and any child padding from the overall allocation Number of requests to fit into the allocation An array of structs with a client pointer and a minimum/natural size in the orientation of the allocation. Gets a property of the `GtkEditable` delegate for @object. This is helper function that should be called in the `get_property` function of your `GtkEditable` implementation, before handling your own properties. %TRUE if the property was found a `GObject` a property ID value to set the `GParamSpec` for the property Sets a property on the `GtkEditable` delegate for @object. This is a helper function that should be called in the `set_property` function of your `GtkEditable` implementation, before handling your own properties. %TRUE if the property was found a `GObject` a property ID value to set the `GParamSpec` for the property Overrides the `GtkEditable` properties for @class. This is a helper function that should be called in class_init, after installing your own properties. Note that your class must have "text", "cursor-position", "selection-bound", "editable", "width-chars", "max-width-chars", "xalign" and "enable-undo" properties for this function to work. To handle the properties in your set_property and get_property functions, you can either use [func@Gtk.Editable.delegate_set_property] and [func@Gtk.Editable.delegate_get_property] (if you are using a delegate), or remember the @first_prop offset and add it to the values in the [enum@Gtk.EditableProperties] enumeration to get the property IDs for these properties. the number of properties that were installed a `GObjectClass` property ID to use for the first property Calls a function for all `GtkPrinter`s. If @func returns %TRUE, the enumeration is stopped. a function to call for each printer user data to pass to @func function to call if @data is no longer needed if %TRUE, wait in a recursive mainloop until all printers are enumerated; otherwise return early Registers an error quark for `GtkFileChooser` errors. The error quark used for `GtkFileChooser` errors. Returns the binary age as passed to `libtool`. If `libtool` means nothing to you, don't worry about it. the binary age of the GTK library Returns the GTK debug flags that are currently active. This function is intended for GTK modules that want to adjust their debug output based on GTK debug flags. the GTK debug flags. Returns the `PangoLanguage` for the default language currently in effect. Note that this can change over the life of an application. The default language is derived from the current locale. It determines, for example, whether GTK uses the right-to-left or left-to-right text direction. This function is equivalent to [func@Pango.Language.get_default]. See that function for details. the default language Returns the interface age as passed to `libtool`. If `libtool` means nothing to you, don't worry about it. the interface age of the GTK library Get the direction of the current locale. This is the expected reading direction for text and UI. This function depends on the current locale being set with setlocale() and will default to setting the %GTK_TEXT_DIR_LTR direction otherwise. %GTK_TEXT_DIR_NONE will never be returned. GTK sets the default text direction according to the locale during gtk_init(), and you should normally use gtk_widget_get_direction() or gtk_widget_get_default_direction() to obtain the current direction. This function is only needed rare cases when the locale is changed after GTK has already been initialized. In this case, you can use it to update the default text direction as follows: |[<!-- language="C" --> #include <locale.h> static void update_locale (const char *new_locale) { setlocale (LC_ALL, new_locale); gtk_widget_set_default_direction (gtk_get_locale_direction ()); } ]| the direction of the current locale Returns the major version number of the GTK library. For example, in GTK version 3.1.5 this is 3. This function is in the library, so it represents the GTK library your code is running against. Contrast with the %GTK_MAJOR_VERSION macro, which represents the major version of the GTK headers you have included when compiling your code. the major version number of the GTK library Returns the micro version number of the GTK library. For example, in GTK version 3.1.5 this is 5. This function is in the library, so it represents the GTK library your code is are running against. Contrast with the %GTK_MICRO_VERSION macro, which represents the micro version of the GTK headers you have included when compiling your code. the micro version number of the GTK library Returns the minor version number of the GTK library. For example, in GTK version 3.1.5 this is 1. This function is in the library, so it represents the GTK library your code is are running against. Contrast with the %GTK_MINOR_VERSION macro, which represents the minor version of the GTK headers you have included when compiling your code. the minor version number of the GTK library GTK supports Drag-and-Drop in tree views with a high-level and a low-level API. The low-level API consists of the GTK DND API, augmented by some treeview utility functions: gtk_tree_view_set_drag_dest_row(), gtk_tree_view_get_drag_dest_row(), gtk_tree_view_get_dest_row_at_pos(), gtk_tree_view_create_row_drag_icon(), gtk_tree_set_row_drag_data() and gtk_tree_get_row_drag_data(). This API leaves a lot of flexibility, but nothing is done automatically, and implementing advanced features like hover-to-open-rows or autoscrolling on top of this API is a lot of work. On the other hand, if you write to the high-level API, then all the bookkeeping of rows is done for you, as well as things like hover-to-open and auto-scroll, but your models have to implement the `GtkTreeDragSource` and `GtkTreeDragDest` interfaces. Converts a color from HSV space to RGB. Input values must be in the [0.0, 1.0] range; output values will be in the same range. Hue Saturation Value Return value for the red component Return value for the green component Return value for the blue component Registers an error quark for [class@Gtk.IconTheme] errors. the error quark Call this function before using any other GTK functions in your GUI applications. It will initialize everything needed to operate the toolkit. If you are using `GtkApplication`, you usually don't have to call this function; the `GApplication::startup` handler does it for you. Though, if you are using GApplication methods that will be invoked before `startup`, such as `local_command_line`, you may need to initialize stuff explicitly. This function will terminate your program if it was unable to initialize the windowing system for some reason. If you want your program to fall back to a textual interface, call [func@Gtk.init_check] instead. GTK calls `signal (SIGPIPE, SIG_IGN)` during initialization, to ignore SIGPIPE signals, since these are almost never wanted in graphical applications. If you do need to handle SIGPIPE for some reason, reset the handler after gtk_init(), but notice that other libraries (e.g. libdbus or gvfs) might do similar things. This function does the same work as gtk_init() with only a single change: It does not terminate the program if the windowing system can’t be initialized. Instead it returns %FALSE on failure. This way the application can fall back to some other means of communication with the user - for example a curses or command line interface. %TRUE if the windowing system has been successfully initialized, %FALSE otherwise Use this function to check if GTK has been initialized. See [func@Gtk.init]. the initialization status Finds the `GtkNative` associated with the surface. the `GtkNative` that is associated with @surface a `GdkSurface` Converts the result of a `GCompareFunc` like strcmp() to a `GtkOrdering` value. the corresponding `GtkOrdering` Result of a comparison function Returns the name of the default paper size, which depends on the current locale. the name of the default paper size. The string is owned by GTK and should not be modified. Creates a list of known paper sizes. a newly allocated list of newly allocated `GtkPaperSize` objects whether to include custom paper sizes as defined in the page setup dialog Creates a new `GParamSpec` instance for a property holding a `GtkExpression`. See `g_param_spec_internal()` for details on the property strings. a newly created property specification canonical name of the property a user-readable name for the property a user-readable description of the property flags for the property Registers an error quark for `GtkPrintOperation` if necessary. The error quark used for `GtkPrintOperation` errors. Runs a page setup dialog, letting the user modify the values from @page_setup. If the user cancels the dialog, the returned `GtkPageSetup` is identical to the passed in @page_setup, otherwise it contains the modifications done in the dialog. Note that this function may use a recursive mainloop to show the page setup dialog. See gtk_print_run_page_setup_dialog_async() if this is a problem. a new `GtkPageSetup` transient parent an existing `GtkPageSetup` a `GtkPrintSettings` Runs a page setup dialog, letting the user modify the values from @page_setup. In contrast to gtk_print_run_page_setup_dialog(), this function returns after showing the page setup dialog on platforms that support this, and calls @done_cb from a signal handler for the ::response signal of the dialog. transient parent an existing `GtkPageSetup` a `GtkPrintSettings` a function to call when the user saves the modified page setup user data to pass to @done_cb Registers an error quark for [class@RecentManager] errors. the error quark Renders an activity indicator (such as in `GtkSpinner`). The state %GTK_STATE_FLAG_CHECKED determines whether there is activity going on. a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders an arrow pointing to @angle. Typical arrow rendering at 0, 1⁄2 π;, π; and 3⁄2 π:  a `GtkStyleContext` a `cairo_t` arrow angle from 0 to 2 * %G_PI, being 0 the arrow pointing to the north X origin of the render area Y origin of the render area square side for render area Renders the background of an element. Typical background rendering, showing the effect of `background-image`, `border-width` and `border-radius`:  a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a checkmark (as in a `GtkCheckButton`). The %GTK_STATE_FLAG_CHECKED state determines whether the check is on or off, and %GTK_STATE_FLAG_INCONSISTENT determines whether it should be marked as undefined. Typical checkmark rendering:  a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders an expander (as used in `GtkTreeView` and `GtkExpander`) in the area defined by @x, @y, @width, @height. The state %GTK_STATE_FLAG_CHECKED determines whether the expander is collapsed or expanded. Typical expander rendering:  a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a focus indicator on the rectangle determined by @x, @y, @width, @height. Typical focus rendering:  a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a frame around the rectangle defined by @x, @y, @width, @height. Examples of frame rendering, showing the effect of `border-image`, `border-color`, `border-width`, `border-radius` and junctions:  a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders a handle (as in `GtkPaned` and `GtkWindow`’s resize grip), in the rectangle determined by @x, @y, @width, @height. Handles rendered for the paned and grip classes:  a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Renders the icon in @texture at the specified @x and @y coordinates. This function will render the icon in @texture at exactly its size, regardless of scaling factors, which may not be appropriate when drawing on displays with high pixel densities. a `GtkStyleContext` a `cairo_t` a `GdkTexture` containing the icon to draw X position for the @texture Y position for the @texture Renders @layout on the coordinates @x, @y a `GtkStyleContext` a `cairo_t` X origin Y origin the `PangoLayout` to render Renders a line from (x0, y0) to (x1, y1). a `GtkStyleContext` a `cairo_t` X coordinate for the origin of the line Y coordinate for the origin of the line X coordinate for the end of the line Y coordinate for the end of the line Renders an option mark (as in a radio button), the %GTK_STATE_FLAG_CHECKED state will determine whether the option is on or off, and %GTK_STATE_FLAG_INCONSISTENT whether it should be marked as undefined. Typical option mark rendering:  a `GtkStyleContext` a `cairo_t` X origin of the rectangle Y origin of the rectangle rectangle width rectangle height Converts a color from RGB space to HSV. Input values must be in the [0.0, 1.0] range; output values will be in the same range. Red Green Blue Return value for the hue component Return value for the saturation component Return value for the value component Sets the GTK debug flags. the debug flags to set A convenience function for showing an application’s about dialog. The constructed dialog is associated with the parent window and reused for future invocations of this function. the parent top-level window the name of the first property value of first property, followed by more pairs of property name and value, `NULL`-terminated This function launches the default application for showing a given uri, or shows an error dialog if that fails. Use [method@Gtk.FileLauncher.launch] or [method@Gtk.UriLauncher.launch] instead parent window the uri to show timestamp from the event that triggered this call, or %GDK_CURRENT_TIME This function launches the default application for showing a given uri. The @callback will be called when the launch is completed. This is the recommended call to be used as it passes information necessary for sandbox helpers to parent their dialogs properly. Use [method@Gtk.FileLauncher.launch] or [method@Gtk.UriLauncher.launch] instead parent window the uri to show timestamp from the event that triggered this call, or %GDK_CURRENT_TIME a `GCancellable` to cancel the launch a callback to call when the action is complete data to pass to @callback Finishes the gtk_show_uri() call and returns the result of the operation. Use [method@Gtk.FileLauncher.launch] or [method@Gtk.UriLauncher.launch] instead %TRUE if the URI was shown successfully. Otherwise, %FALSE is returned and @error is set the `GtkWindow` passed to gtk_show_uri() `GAsyncResult` that was passed to @callback Checks whether a `GtkAccessible` implementation has its accessible property set to the expected value, and raises an assertion if the condition is not satisfied. a `GtkAccessible` a `GtkAccessibleProperty` the value of @property Checks whether a `GtkAccessible` implementation has its accessible relation set to the expected value, and raises an assertion if the condition is not satisfied. a `GtkAccessible` a `GtkAccessibleRelation` the expected value of @relation Checks whether a `GtkAccessible` implementation has the given @role, and raises an assertion if the condition is failed. a `GtkAccessible` a `GtkAccessibleRole` Checks whether a `GtkAccessible` implementation has its accessible state set to the expected value, and raises an assertion if the condition is not satisfied. a `GtkAccessible` a `GtkAccessibleRelation` the expected value of @state Prints an assertion message for gtk_test_accessible_assert_role(). a domain a file name the line in @file a function name in @file the expression being tested a `GtkAccessible` the expected `GtkAccessibleRole` the actual `GtkAccessibleRole` Checks whether the accessible @property of @accessible is set to a specific value. the value of the accessible property a `GtkAccessible` a `GtkAccessibleProperty` the expected value of @property Checks whether the accessible @relation of @accessible is set to a specific value. the value of the accessible relation a `GtkAccessible` a `GtkAccessibleRelation` the expected value of @relation Checks whether the accessible @state of @accessible is set to a specific value. the value of the accessible state a `GtkAccessible` a `GtkAccessibleState` the expected value of @state Checks whether the `GtkAccessible` has @property set. %TRUE if the @property is set in the @accessible a `GtkAccessible` a `GtkAccessibleProperty` Checks whether the `GtkAccessible` has @relation set. %TRUE if the @relation is set in the @accessible a `GtkAccessible` a `GtkAccessibleRelation` Checks whether the `GtkAccessible:accessible-role` of the accessible is @role. %TRUE if the role matches a `GtkAccessible` a `GtkAccessibleRole` Checks whether the `GtkAccessible` has @state set. %TRUE if the @state is set in the @accessible a `GtkAccessible` a `GtkAccessibleState` This function is used to initialize a GTK test program. It will in turn call g_test_init() and gtk_init() to properly initialize the testing framework and graphical toolkit. It’ll also set the program’s locale to “C”. This is done to make test program environments as deterministic as possible. Like gtk_init() and g_test_init(), any known arguments will be processed and stripped from @argc and @argv. Address of the `argc` parameter of the main() function. Changed if any arguments were handled. Address of the `argv` parameter of main(). Any parameters understood by g_test_init() or gtk_init() are stripped before return. currently unused Return the type ids that have been registered after calling gtk_test_register_all_types(). 0-terminated array of type ids location to store number of types Force registration of all core GTK object types. This allows to refer to any of those object types via g_type_from_name() after calling this function. Enters the main loop and waits for @widget to be “drawn”. In this context that means it waits for the frame clock of @widget to have run a full styling, layout and drawing cycle. This function is intended to be used for syncing with actions that depend on @widget relayouting or on interaction with the display server. the widget to wait for Creates a content provider for dragging @path from @tree_model. Use list models instead a new `GdkContentProvider` a `GtkTreeModel` a row in @tree_model Obtains a @tree_model and @path from value of target type %GTK_TYPE_TREE_ROW_DATA. The returned path must be freed with gtk_tree_path_free(). Use list models instead %TRUE if @selection_data had target type %GTK_TYPE_TREE_ROW_DATA is otherwise valid a `GValue` a `GtkTreeModel` row in @tree_model Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::row-deleted signal. a `GObject` the path position that was deleted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::row-inserted signal. a `GObject` the row position that was inserted Lets a set of row reference created by gtk_tree_row_reference_new_proxy() know that the model emitted the ::rows-reordered signal. a `GObject` the parent path of the reordered signal the iter pointing to the parent of the reordered the new order of rows Retrieves the `GtkExpression` stored inside the given `value`, and acquires a reference to it. a `GtkExpression` a `GValue` initialized with type `GTK_TYPE_EXPRESSION` Retrieves the `GtkExpression` stored inside the given `value`. a `GtkExpression` a `GValue` initialized with type `GTK_TYPE_EXPRESSION` Stores the given `GtkExpression` inside `value`. The `GValue` will acquire a reference to the `expression`. a `GValue` initialized with type `GTK_TYPE_EXPRESSION` a `GtkExpression` Stores the given `GtkExpression` inside `value`. This function transfers the ownership of the `expression` to the `GValue`. a `GValue` initialized with type `GTK_TYPE_EXPRESSION` a `GtkExpression` Binds a callback function defined in a template to the @widget_class. This macro is a convenience wrapper around the gtk_widget_class_bind_template_callback_full() function. It is not supported after gtk_widget_class_set_template_scope() has been used on @widget_class. a `GtkWidgetClass` the callback symbol Binds a child widget defined in a template to the @widget_class. This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function. This macro will use the offset of the @member_name inside the @TypeName instance structure. a `GtkWidgetClass` the type name of this widget name of the instance member in the instance struct for @data_type Binds a child widget defined in a template to the @widget_class, and also makes it available as an internal child in GtkBuilder, under the name @member_name. This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function. This macro will use the offset of the @member_name inside the @TypeName instance structure. a `GtkWidgetClass` the type name, in CamelCase name of the instance member in the instance struct for @data_type Binds a child widget defined in a template to the @widget_class, and also makes it available as an internal child in GtkBuilder, under the name @member_name. This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function. This macro will use the offset of the @member_name inside the @TypeName private data structure. a `GtkWidgetClass` the type name, in CamelCase name of the instance private member on the private struct for @data_type Binds a child widget defined in a template to the @widget_class. This macro is a convenience wrapper around the gtk_widget_class_bind_template_child_full() function. This macro will use the offset of the @member_name inside the @TypeName private data structure (it uses G_PRIVATE_OFFSET(), so the private struct must be added with G_ADD_PRIVATE()). a `GtkWidgetClass` the type name of this widget name of the instance private member in the private struct for @data_type