A dialog showing information about the application. <picture> <source srcset="about-dialog-dark.png" media="(prefers-color-scheme: dark)"> <img src="about-dialog.png" alt="about-dialog"> </picture> an about dialog is typically opened when the user activates the `About …` item in the application's primary menu. All parts of the dialog are optional. ## Main page `AdwAboutDialog` prominently displays the application's icon, name, developer name and version. They can be set with the [property@AboutDialog:application-icon], [property@AboutDialog:application-name], [property@AboutDialog:developer-name] and [property@AboutDialog:version] respectively. ## What's New `AdwAboutDialog` provides a way for applications to display their release notes, set with the [property@AboutDialog:release-notes] property. Release notes are formatted the same way as [AppStream descriptions](https://freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description). The supported formatting options are: * Paragraph (`<p>`) * Ordered list (`<ol>`), with list items (`<li>`) * Unordered list (`<ul>`), with list items (`<li>`) Within paragraphs and list items, emphasis (`<em>`) and inline code (`<code>`) text styles are supported. The emphasis is rendered in italic, while inline code is shown in a monospaced font. Any text outside paragraphs or list items is ignored. Nested lists are not supported. Only one version can be shown at a time. By default, the displayed version number matches [property@AboutDialog:version]. Use [property@AboutDialog:release-notes-version] to override it. ## Details The Details page displays the application comments and links. The comments can be set with the [property@AboutDialog:comments] property. Unlike [property@Gtk.AboutDialog:comments], this string can be long and detailed. It can also contain links and Pango markup. To set the application website, use [property@AboutDialog:website]. To add extra links below the website, use [method@AboutDialog.add_link]. If the Details page doesn't have any other content besides website, the website will be displayed on the main page instead. ## Troubleshooting `AdwAboutDialog` displays the following two links on the main page: * Support Questions, set with the [property@AboutDialog:support-url] property, * Report an Issue, set with the [property@AboutDialog:issue-url] property. Additionally, applications can provide debugging information. It will be shown separately on the Troubleshooting page. Use the [property@AboutDialog:debug-info] property to specify it. It's intended to be attached to issue reports when reporting issues against the application. As such, it cannot contain markup or links. `AdwAboutDialog` provides a quick way to save debug information to a file. When saving, [property@AboutDialog:debug-info-filename] would be used as the suggested filename. ## Credits and Acknowledgements The Credits page has the following default sections: * Developers, set with the [property@AboutDialog:developers] property, * Designers, set with the [property@AboutDialog:designers] property, * Artists, set with the [property@AboutDialog:artists] property, * Documenters, set with the [property@AboutDialog:documenters] property, * Translators, set with the [property@AboutDialog:translator-credits] property. When setting translator credits, use the strings `"translator-credits"` or `"translator_credits"` and mark them as translatable. The default sections that don't contain any names won't be displayed. The Credits page can also contain an arbitrary number of extra sections below the default ones. Use [method@AboutDialog.add_credit_section] to add them. The Acknowledgements page can be used to acknowledge additional people and organizations for their non-development contributions. Use [method@AboutDialog.add_acknowledgement_section] to add sections to it. For example, it can be used to list backers in a crowdfunded project or to give special thanks. Each of the people or organizations can have an email address or a website specified. To add a email address, use a string like `Edgar Allan Poe <edgar@poe.com>`. To specify a website with a title, use a string like `The GNOME Project https://www.gnome.org`: <picture> <source srcset="about-dialog-credits-dark.png" media="(prefers-color-scheme: dark)"> <img src="about-dialog-credits.png" alt="about-dialog-credits"> </picture> ## Legal The Legal page displays the copyright and licensing information for the application and other modules. The copyright string is set with the [property@AboutDialog:copyright] property and should be a short string of one or two lines, for example: `© 2022 Example`. Licensing information can be quickly set from a list of known licenses with the [property@AboutDialog:license-type] property. If the application's license is not in the list, [property@AboutDialog:license] can be used instead. To add information about other modules, such as application dependencies or data, use [method@AboutDialog.add_legal_section]. ## Constructing To make constructing an `AdwAboutDialog` as convenient as possible, you can use the function [func@show_about_dialog] which constructs and shows a dialog. ```c static void show_about (GtkApplication *app) { const char *developers[] = { "Angela Avery", NULL }; const char *designers[] = { "GNOME Design Team", NULL }; adw_show_about_dialog (GTK_WIDGET (gtk_application_get_active_window (app)), "application-name", _("Example"), "application-icon", "org.example.App", "version", "1.2.3", "copyright", "© 2022 Angela Avery", "issue-url", "https://gitlab.gnome.org/example/example/-/issues/", "license-type", GTK_LICENSE_GPL_3_0, "developers", developers, "designers", designers, "translator-credits", _("translator-credits"), NULL); } ``` ## CSS nodes `AdwAboutDialog` has a main CSS node with the name `dialog` and the style class `.about`. Creates a new `AdwAboutDialog`. the newly created `AdwAboutDialog` Creates a new `AdwAboutDialog` using AppStream metadata. This automatically sets the following properties with the following AppStream values: * [property@AboutDialog:application-icon] is set from the `<id>` * [property@AboutDialog:application-name] is set from the `<name>` * [property@AboutDialog:developer-name] is set from the `<name>` within `<developer>` * [property@AboutDialog:version] is set from the version of the latest release * [property@AboutDialog:website] is set from the `<url type="homepage">` * [property@AboutDialog:support-url] is set from the `<url type="help">` * [property@AboutDialog:issue-url] is set from the `<url type="bugtracker">` * [property@AboutDialog:license-type] is set from the `<project_license>`. If the license type retrieved from AppStream is not listed in [enum@Gtk.License], it will be set to `GTK_LICENCE_CUSTOM`. If @release_notes_version is not `NULL`, [property@AboutDialog:release-notes-version] is set to match it, while [property@AboutDialog:release-notes] is set from the AppStream release description for that version. the newly created `AdwAboutDialog` The resource to use The version to retrieve release notes for Adds a section to the Acknowledgements page. This can be used to acknowledge additional people and organizations for their non-development contributions - for example, backers in a crowdfunded project. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutDialog:developers] * [property@AboutDialog:designers] * [property@AboutDialog:artists] * [property@AboutDialog:documenters] * [property@AboutDialog:translator-credits] * [method@AboutDialog.add_credit_section] an about dialog the section name the list of names Adds an extra section to the Credits page. Extra sections are displayed below the standard categories. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutDialog:developers] * [property@AboutDialog:designers] * [property@AboutDialog:artists] * [property@AboutDialog:documenters] * [property@AboutDialog:translator-credits] * [method@AboutDialog.add_acknowledgement_section] an about dialog the section name the list of names Adds an extra section to the Legal page. Extra sections will be displayed below the application's own information. The parameters @copyright, @license_type and @license will be used to present the it the same way as [property@AboutDialog:copyright], [property@AboutDialog:license-type] and [property@AboutDialog:license] are for the application's own information. See those properties for more details. This can be useful to attribute the application dependencies or data. Examples: ```c adw_about_dialog_add_legal_section (ADW_ABOUT_DIALOG (about), _("Copyright and a known license"), "© 2022 Example", GTK_LICENSE_LGPL_2_1, NULL); adw_about_dialog_add_legal_section (ADW_ABOUT_DIALOG (about), _("Copyright and custom license"), "© 2022 Example", GTK_LICENSE_CUSTOM, "Custom license text"); adw_about_dialog_add_legal_section (ADW_ABOUT_DIALOG (about), _("Copyright only"), "© 2022 Example", GTK_LICENSE_UNKNOWN, NULL); adw_about_dialog_add_legal_section (ADW_ABOUT_DIALOG (about), _("Custom license only"), NULL, GTK_LICENSE_CUSTOM, "Something completely custom here."); ``` an about dialog the name of the section a copyright string the type of license custom license information Adds an extra link to the Details page. Extra links are displayed under the comment and website. Underlines in @title will be interpreted as indicating a mnemonic. See [property@AboutDialog:website]. an about dialog the link title the link URL Gets the name of the application icon for @self. the application icon name an about dialog Gets the application name for @self. the application name an about dialog Gets the list of artists of the application. The list of artists an about dialog Gets the comments about the application. the comments an about dialog Gets the copyright information for @self. the copyright information an about dialog Gets the debug information for @self. the debug information an about dialog Gets the debug information filename for @self. the debug information filename an about dialog Gets the list of designers of the application. The list of designers an about dialog Gets the developer name for @self. the developer_name an about dialog Gets the list of developers of the application. The list of developers an about dialog Gets the list of documenters of the application. The list of documenters an about dialog Gets the issue tracker URL for @self. the issue tracker URL an about dialog Gets the license for @self. the license an about dialog Gets the license type for @self. the license type an about dialog Gets the release notes for @self. the release notes an about dialog Gets the version described by the application's release notes. the release notes version an about dialog Gets the URL of the support page for @self. the support page URL an about dialog Gets the translator credits string. The translator credits string an about dialog Gets the version for @self. the version an about dialog Gets the application website URL for @self. the website URL an about dialog Sets the name of the application icon for @self. The icon is displayed at the top of the main page. an about dialog the application icon name Sets the application name for @self. The name is displayed at the top of the main page. an about dialog the application name Sets the list of artists of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutDialog:developers] * [property@AboutDialog:designers] * [property@AboutDialog:documenters] * [property@AboutDialog:translator-credits] * [method@AboutDialog.add_credit_section] * [method@AboutDialog.add_acknowledgement_section] an about dialog the list of artists Sets the comments about the application. Comments will be shown on the Details page, above links. Unlike [property@Gtk.AboutDialog:comments], this string can be long and detailed. It can also contain links and Pango markup. an about dialog the comments Sets the copyright information for @self. This should be a short string of one or two lines, for example: `© 2022 Example`. The copyright information will be displayed on the Legal page, before the application license. [method@AboutDialog.add_legal_section] can be used to add copyright information for the application dependencies or other components. an about dialog the copyright information Sets the debug information for @self. Debug information will be shown on the Troubleshooting page. It's intended to be attached to issue reports when reporting issues against the application. `AdwAboutDialog` provides a quick way to save debug information to a file. When saving, [property@AboutDialog:debug-info-filename] would be used as the suggested filename. Debug information cannot contain markup or links. an about dialog the debug information Sets the debug information filename for @self. It will be used as the suggested filename when saving debug information to a file. See [property@AboutDialog:debug-info]. an about dialog the debug info filename Sets the list of designers of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutDialog:developers] * [property@AboutDialog:artists] * [property@AboutDialog:documenters] * [property@AboutDialog:translator-credits] * [method@AboutDialog.add_credit_section] * [method@AboutDialog.add_acknowledgement_section] an about dialog the list of designers Sets the developer name for @self. The developer name is displayed on the main page, under the application name. If the application is developed by multiple people, the developer name can be set to values like "AppName team", "AppName developers" or "The AppName project", and the individual contributors can be listed on the Credits page, with [property@AboutDialog:developers] and related properties. an about dialog the developer name Sets the list of developers of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutDialog:designers] * [property@AboutDialog:artists] * [property@AboutDialog:documenters] * [property@AboutDialog:translator-credits] * [method@AboutDialog.add_credit_section] * [method@AboutDialog.add_acknowledgement_section] an about dialog the list of developers Sets the list of documenters of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutDialog:developers] * [property@AboutDialog:designers] * [property@AboutDialog:artists] * [property@AboutDialog:translator-credits] * [method@AboutDialog.add_credit_section] * [method@AboutDialog.add_acknowledgement_section] an about dialog the list of documenters Sets the issue tracker URL for @self. The issue tracker link is displayed on the main page. an about dialog the issue tracker URL Sets the license for @self. This can be used to set a custom text for the license if it can't be set via [property@AboutDialog:license-type]. When set, [property@AboutDialog:license-type] will be set to `GTK_LICENSE_CUSTOM`. The license text will be displayed on the Legal page, below the copyright information. License text can contain Pango markup and links. [method@AboutDialog.add_legal_section] can be used to add license information for the application dependencies or other components. an about dialog the license Sets the license for @self from a list of known licenses. If the application's license is not in the list, [property@AboutDialog:license] can be used instead. The license type will be automatically set to `GTK_LICENSE_CUSTOM` in that case. If @license_type is `GTK_LICENSE_UNKNOWN`, no information will be displayed. If @license_type is different from `GTK_LICENSE_CUSTOM`. [property@AboutDialog:license] will be cleared out. The license description will be displayed on the Legal page, below the copyright information. [method@AboutDialog.add_legal_section] can be used to add license information for the application dependencies or other components. an about dialog the license type Sets the release notes for @self. Release notes are displayed on the the What's New page. Release notes are formatted the same way as [AppStream descriptions](https://freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description). The supported formatting options are: * Paragraph (`<p>`) * Ordered list (`<ol>`), with list items (`<li>`) * Unordered list (`<ul>`), with list items (`<li>`) Within paragraphs and list items, emphasis (`<em>`) and inline code (`<code>`) text styles are supported. The emphasis is rendered in italic, while inline code is shown in a monospaced font. Any text outside paragraphs or list items is ignored. Nested lists are not supported. `AdwAboutDialog` displays the version above the release notes. If set, the [property@AboutDialog:release-notes-version] of the property will be used as the version; otherwise, [property@AboutDialog:version] is used. an about dialog the release notes Sets the version described by the application's release notes. The release notes version is displayed on the What's New page, above the release notes. If not set, [property@AboutDialog:version] will be used instead. For example, an application with the current version 2.0.2 might want to keep the release notes from 2.0.0, and set the release notes version accordingly. See [property@AboutDialog:release-notes]. an about dialog the release notes version Sets the URL of the support page for @self. The support page link is displayed on the main page. an about dialog the support page URL Sets the translator credits string. It will be displayed on the Credits page. This string should be `"translator-credits"` or `"translator_credits"` and should be marked as translatable. The string may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutDialog:developers] * [property@AboutDialog:designers] * [property@AboutDialog:artists] * [property@AboutDialog:documenters] * [method@AboutDialog.add_credit_section] * [method@AboutDialog.add_acknowledgement_section] an about dialog the translator credits Sets the version for @self. The version is displayed on the main page. If [property@AboutDialog:release-notes-version] is not set, the version will also be displayed above the release notes on the What's New page. an about dialog the version Sets the application website URL for @self. Website is displayed on the Details page, below comments, or on the main page if the Details page doesn't have any other content. Applications can add other links below, see [method@AboutDialog.add_link]. an about dialog the website URL The name of the application icon. The icon is displayed at the top of the main page. The name of the application. The name is displayed at the top of the main page. The list of artists of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutDialog:developers] * [property@AboutDialog:designers] * [property@AboutDialog:documenters] * [property@AboutDialog:translator-credits] * [method@AboutDialog.add_credit_section] * [method@AboutDialog.add_acknowledgement_section] The comments about the application. Comments will be shown on the Details page, above links. Unlike [property@Gtk.AboutDialog:comments], this string can be long and detailed. It can also contain links and Pango markup. The copyright information. This should be a short string of one or two lines, for example: `© 2022 Example`. The copyright information will be displayed on the Legal page, above the application license. [method@AboutDialog.add_legal_section] can be used to add copyright information for the application dependencies or other components. The debug information. Debug information will be shown on the Troubleshooting page. It's intended to be attached to issue reports when reporting issues against the application. `AdwAboutDialog` provides a quick way to save debug information to a file. When saving, [property@AboutDialog:debug-info-filename] would be used as the suggested filename. Debug information cannot contain markup or links. The debug information filename. It will be used as the suggested filename when saving debug information to a file. See [property@AboutDialog:debug-info]. The list of designers of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutDialog:developers] * [property@AboutDialog:artists] * [property@AboutDialog:documenters] * [property@AboutDialog:translator-credits] * [method@AboutDialog.add_credit_section] * [method@AboutDialog.add_acknowledgement_section] The developer name. The developer name is displayed on the main page, under the application name. If the application is developed by multiple people, the developer name can be set to values like "AppName team", "AppName developers" or "The AppName project", and the individual contributors can be listed on the Credits page, with [property@AboutDialog:developers] and related properties. The list of developers of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutDialog:designers] * [property@AboutDialog:artists] * [property@AboutDialog:documenters] * [property@AboutDialog:translator-credits] * [method@AboutDialog.add_credit_section] * [method@AboutDialog.add_acknowledgement_section] The list of documenters of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutDialog:developers] * [property@AboutDialog:designers] * [property@AboutDialog:artists] * [property@AboutDialog:translator-credits] * [method@AboutDialog.add_credit_section] * [method@AboutDialog.add_acknowledgement_section] The URL for the application's issue tracker. The issue tracker link is displayed on the main page. The license text. This can be used to set a custom text for the license if it can't be set via [property@AboutDialog:license-type]. When set, [property@AboutDialog:license-type] will be set to `GTK_LICENSE_CUSTOM`. The license text will be displayed on the Legal page, below the copyright information. License text can contain Pango markup and links. [method@AboutDialog.add_legal_section] can be used to add license information for the application dependencies or other components. The license type. Allows to set the application's license froma list of known licenses. If the application's license is not in the list, [property@AboutDialog:license] can be used instead. The license type will be automatically set to `GTK_LICENSE_CUSTOM` in that case. If set to `GTK_LICENSE_UNKNOWN`, no information will be displayed. If the license type is different from `GTK_LICENSE_CUSTOM`. [property@AboutDialog:license] will be cleared out. The license description will be displayed on the Legal page, below the copyright information. [method@AboutDialog.add_legal_section] can be used to add license information for the application dependencies or other components. The release notes of the application. Release notes are displayed on the the What's New page. Release notes are formatted the same way as [AppStream descriptions](https://freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description). The supported formatting options are: * Paragraph (`<p>`) * Ordered list (`<ol>`), with list items (`<li>`) * Unordered list (`<ul>`), with list items (`<li>`) Within paragraphs and list items, emphasis (`<em>`) and inline code (`<code>`) text styles are supported. The emphasis is rendered in italic, while inline code is shown in a monospaced font. Any text outside paragraphs or list items is ignored. Nested lists are not supported. `AdwAboutDialog` displays the version above the release notes. If set, the [property@AboutDialog:release-notes-version] of the property will be used as the version; otherwise, [property@AboutDialog:version] is used. The version described by the application's release notes. The release notes version is displayed on the What's New page, above the release notes. If not set, [property@AboutDialog:version] will be used instead. For example, an application with the current version 2.0.2 might want to keep the release notes from 2.0.0, and set the release notes version accordingly. See [property@AboutDialog:release-notes]. The URL of the application's support page. The support page link is displayed on the main page. The translator credits string. It will be displayed on the Credits page. This string should be `"translator-credits"` or `"translator_credits"` and should be marked as translatable. The string may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutDialog:developers] * [property@AboutDialog:designers] * [property@AboutDialog:artists] * [property@AboutDialog:documenters] * [method@AboutDialog.add_credit_section] * [method@AboutDialog.add_acknowledgement_section] The version of the application. The version is displayed on the main page. If [property@AboutDialog:release-notes-version] is not set, the version will also be displayed above the release notes on the What's New page. The URL of the application's website. Website is displayed on the Details page, below comments, or on the main page if the Details page doesn't have any other content. Applications can add other links below, see [method@AboutDialog.add_link]. Emitted when a URL is activated. Applications may connect to it to override the default behavior, which is to call [func@Gtk.show_uri]. `TRUE` if the link has been activated the URI to activate A window showing information about the application. <picture> <source srcset="about-window-dark.png" media="(prefers-color-scheme: dark)"> <img src="about-window.png" alt="about-window"> </picture> An about window is typically opened when the user activates the `About …` item in the application's primary menu. All parts of the window are optional. ## Main page `AdwAboutWindow` prominently displays the application's icon, name, developer name and version. They can be set with the [property@AboutWindow:application-icon], [property@AboutWindow:application-name], [property@AboutWindow:developer-name] and [property@AboutWindow:version] respectively. ## What's New `AdwAboutWindow` provides a way for applications to display their release notes, set with the [property@AboutWindow:release-notes] property. Release notes are formatted the same way as [AppStream descriptions](https://freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description). The supported formatting options are: * Paragraph (`<p>`) * Ordered list (`<ol>`), with list items (`<li>`) * Unordered list (`<ul>`), with list items (`<li>`) Within paragraphs and list items, emphasis (`<em>`) and inline code (`<code>`) text styles are supported. The emphasis is rendered in italic, while inline code is shown in a monospaced font. Any text outside paragraphs or list items is ignored. Nested lists are not supported. Only one version can be shown at a time. By default, the displayed version number matches [property@AboutWindow:version]. Use [property@AboutWindow:release-notes-version] to override it. ## Details The Details page displays the application comments and links. The comments can be set with the [property@AboutWindow:comments] property. Unlike [property@Gtk.AboutDialog:comments], this string can be long and detailed. It can also contain links and Pango markup. To set the application website, use [property@AboutWindow:website]. To add extra links below the website, use [method@AboutWindow.add_link]. If the Details page doesn't have any other content besides website, the website will be displayed on the main page instead. ## Troubleshooting `AdwAboutWindow` displays the following two links on the main page: * Support Questions, set with the [property@AboutWindow:support-url] property, * Report an Issue, set with the [property@AboutWindow:issue-url] property. Additionally, applications can provide debugging information. It will be shown separately on the Troubleshooting page. Use the [property@AboutWindow:debug-info] property to specify it. It's intended to be attached to issue reports when reporting issues against the application. As such, it cannot contain markup or links. `AdwAboutWindow` provides a quick way to save debug information to a file. When saving, [property@AboutWindow:debug-info-filename] would be used as the suggested filename. ## Credits and Acknowledgements The Credits page has the following default sections: * Developers, set with the [property@AboutWindow:developers] property, * Designers, set with the [property@AboutWindow:designers] property, * Artists, set with the [property@AboutWindow:artists] property, * Documenters, set with the [property@AboutWindow:documenters] property, * Translators, set with the [property@AboutWindow:translator-credits] property. When setting translator credits, use the strings `"translator-credits"` or `"translator_credits"` and mark them as translatable. The default sections that don't contain any names won't be displayed. The Credits page can also contain an arbitrary number of extra sections below the default ones. Use [method@AboutWindow.add_credit_section] to add them. The Acknowledgements page can be used to acknowledge additional people and organizations for their non-development contributions. Use [method@AboutWindow.add_acknowledgement_section] to add sections to it. For example, it can be used to list backers in a crowdfunded project or to give special thanks. Each of the people or organizations can have an email address or a website specified. To add a email address, use a string like `Edgar Allan Poe <edgar@poe.com>`. To specify a website with a title, use a string like `The GNOME Project https://www.gnome.org`: <picture> <source srcset="about-window-credits-dark.png" media="(prefers-color-scheme: dark)"> <img src="about-window-credits.png" alt="about-window-credits"> </picture> ## Legal The Legal page displays the copyright and licensing information for the application and other modules. The copyright string is set with the [property@AboutWindow:copyright] property and should be a short string of one or two lines, for example: `© 2022 Example`. Licensing information can be quickly set from a list of known licenses with the [property@AboutWindow:license-type] property. If the application's license is not in the list, [property@AboutWindow:license] can be used instead. To add information about other modules, such as application dependencies or data, use [method@AboutWindow.add_legal_section]. ## Constructing To make constructing an `AdwAboutWindow` as convenient as possible, you can use the function [func@show_about_window] which constructs and shows a window. ```c static void show_about (GtkApplication *app) { const char *developers[] = { "Angela Avery", NULL }; const char *designers[] = { "GNOME Design Team", NULL }; adw_show_about_window (gtk_application_get_active_window (app), "application-name", _("Example"), "application-icon", "org.example.App", "version", "1.2.3", "copyright", "© 2022 Angela Avery", "issue-url", "https://gitlab.gnome.org/example/example/-/issues/", "license-type", GTK_LICENSE_GPL_3_0, "developers", developers, "designers", designers, "translator-credits", _("translator-credits"), NULL); } ``` ## CSS nodes `AdwAboutWindow` has a main CSS node with the name `window` and the style class `.about`. Use [class@AboutDialog]. Creates a new `AdwAboutWindow`. Use [class@AboutDialog]. the newly created `AdwAboutWindow` Creates a new `AdwAboutWindow` using AppStream metadata. This automatically sets the following properties with the following AppStream values: * [property@AboutWindow:application-icon] is set from the `<id>` * [property@AboutWindow:application-name] is set from the `<name>` * [property@AboutWindow:developer-name] is set from the `<name>` within `<developer>` * [property@AboutWindow:version] is set from the version of the latest release * [property@AboutWindow:website] is set from the `<url type="homepage">` * [property@AboutWindow:support-url] is set from the `<url type="help">` * [property@AboutWindow:issue-url] is set from the `<url type="bugtracker">` * [property@AboutWindow:license-type] is set from the `<project_license>`. If the license type retrieved from AppStream is not listed in [enum@Gtk.License], it will be set to `GTK_LICENCE_CUSTOM`. If @release_notes_version is not `NULL`, [property@AboutWindow:release-notes-version] is set to match it, while [property@AboutWindow:release-notes] is set from the AppStream release description for that version. Use [class@AboutDialog]. the newly created `AdwAboutWindow` The resource to use The version to retrieve release notes for Adds a section to the Acknowledgements page. This can be used to acknowledge additional people and organizations for their non-development contributions - for example, backers in a crowdfunded project. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutWindow:developers] * [property@AboutWindow:designers] * [property@AboutWindow:artists] * [property@AboutWindow:documenters] * [property@AboutWindow:translator-credits] * [method@AboutWindow.add_credit_section] Use [class@AboutDialog]. an about window the section name the list of names Adds an extra section to the Credits page. Extra sections are displayed below the standard categories. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutWindow:developers] * [property@AboutWindow:designers] * [property@AboutWindow:artists] * [property@AboutWindow:documenters] * [property@AboutWindow:translator-credits] * [method@AboutWindow.add_acknowledgement_section] Use [class@AboutDialog]. an about window the section name the list of names Adds an extra section to the Legal page. Extra sections will be displayed below the application's own information. The parameters @copyright, @license_type and @license will be used to present the it the same way as [property@AboutWindow:copyright], [property@AboutWindow:license-type] and [property@AboutWindow:license] are for the application's own information. See those properties for more details. This can be useful to attribute the application dependencies or data. Examples: ```c adw_about_window_add_legal_section (ADW_ABOUT_WINDOW (about), _("Copyright and a known license"), "© 2022 Example", GTK_LICENSE_LGPL_2_1, NULL); adw_about_window_add_legal_section (ADW_ABOUT_WINDOW (about), _("Copyright and custom license"), "© 2022 Example", GTK_LICENSE_CUSTOM, "Custom license text"); adw_about_window_add_legal_section (ADW_ABOUT_WINDOW (about), _("Copyright only"), "© 2022 Example", GTK_LICENSE_UNKNOWN, NULL); adw_about_window_add_legal_section (ADW_ABOUT_WINDOW (about), _("Custom license only"), NULL, GTK_LICENSE_CUSTOM, "Something completely custom here."); ``` Use [class@AboutDialog]. an about window the name of the section a copyright string the type of license custom license information Adds an extra link to the Details page. Extra links are displayed under the comment and website. Underlines in @title will be interpreted as indicating a mnemonic. See [property@AboutWindow:website]. Use [class@AboutDialog]. an about window the link title the link URL Gets the name of the application icon for @self. Use [class@AboutDialog]. the application icon name an about window Gets the application name for @self. Use [class@AboutDialog]. the application name an about window Gets the list of artists of the application. Use [class@AboutDialog]. The list of artists an about window Gets the comments about the application. Use [class@AboutDialog]. the comments an about window Gets the copyright information for @self. Use [class@AboutDialog]. the copyright information an about window Gets the debug information for @self. Use [class@AboutDialog]. the debug information an about window Gets the debug information filename for @self. Use [class@AboutDialog]. the debug information filename an about window Gets the list of designers of the application. Use [class@AboutDialog]. The list of designers an about window Gets the developer name for @self. Use [class@AboutDialog]. the developer_name an about window Gets the list of developers of the application. Use [class@AboutDialog]. The list of developers an about window Gets the list of documenters of the application. Use [class@AboutDialog]. The list of documenters an about window Gets the issue tracker URL for @self. Use [class@AboutDialog]. the issue tracker URL an about window Gets the license for @self. Use [class@AboutDialog]. the license an about window Gets the license type for @self. Use [class@AboutDialog]. the license type an about window Gets the release notes for @self. Use [class@AboutDialog]. the release notes an about window Gets the version described by the application's release notes. Use [class@AboutDialog]. the release notes version an about window Gets the URL of the support page for @self. Use [class@AboutDialog]. the support page URL an about window Gets the translator credits string. Use [class@AboutDialog]. The translator credits string an about window Gets the version for @self. Use [class@AboutDialog]. the version an about window Gets the application website URL for @self. Use [class@AboutDialog]. the website URL an about window Sets the name of the application icon for @self. The icon is displayed at the top of the main page. Use [class@AboutDialog]. an about window the application icon name Sets the application name for @self. The name is displayed at the top of the main page. Use [class@AboutDialog]. an about window the application name Sets the list of artists of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutWindow:developers] * [property@AboutWindow:designers] * [property@AboutWindow:documenters] * [property@AboutWindow:translator-credits] * [method@AboutWindow.add_credit_section] * [method@AboutWindow.add_acknowledgement_section] Use [class@AboutDialog]. an about window the list of artists Sets the comments about the application. Comments will be shown on the Details page, above links. Unlike [property@Gtk.AboutDialog:comments], this string can be long and detailed. It can also contain links and Pango markup. Use [class@AboutDialog]. an about window the comments Sets the copyright information for @self. This should be a short string of one or two lines, for example: `© 2022 Example`. The copyright information will be displayed on the Legal page, before the application license. [method@AboutWindow.add_legal_section] can be used to add copyright information for the application dependencies or other components. Use [class@AboutDialog]. an about window the copyright information Sets the debug information for @self. Debug information will be shown on the Troubleshooting page. It's intended to be attached to issue reports when reporting issues against the application. `AdwAboutWindow` provides a quick way to save debug information to a file. When saving, [property@AboutWindow:debug-info-filename] would be used as the suggested filename. Debug information cannot contain markup or links. Use [class@AboutDialog]. an about window the debug information Sets the debug information filename for @self. It will be used as the suggested filename when saving debug information to a file. See [property@AboutWindow:debug-info]. Use [class@AboutDialog]. an about window the debug info filename Sets the list of designers of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutWindow:developers] * [property@AboutWindow:artists] * [property@AboutWindow:documenters] * [property@AboutWindow:translator-credits] * [method@AboutWindow.add_credit_section] * [method@AboutWindow.add_acknowledgement_section] Use [class@AboutDialog]. an about window the list of designers Sets the developer name for @self. The developer name is displayed on the main page, under the application name. If the application is developed by multiple people, the developer name can be set to values like "AppName team", "AppName developers" or "The AppName project", and the individual contributors can be listed on the Credits page, with [property@AboutWindow:developers] and related properties. Use [class@AboutDialog]. an about window the developer name Sets the list of developers of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutWindow:designers] * [property@AboutWindow:artists] * [property@AboutWindow:documenters] * [property@AboutWindow:translator-credits] * [method@AboutWindow.add_credit_section] * [method@AboutWindow.add_acknowledgement_section] Use [class@AboutDialog]. an about window the list of developers Sets the list of documenters of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutWindow:developers] * [property@AboutWindow:designers] * [property@AboutWindow:artists] * [property@AboutWindow:translator-credits] * [method@AboutWindow.add_credit_section] * [method@AboutWindow.add_acknowledgement_section] Use [class@AboutDialog]. an about window the list of documenters Sets the issue tracker URL for @self. The issue tracker link is displayed on the main page. Use [class@AboutDialog]. an about window the issue tracker URL Sets the license for @self. This can be used to set a custom text for the license if it can't be set via [property@AboutWindow:license-type]. When set, [property@AboutWindow:license-type] will be set to `GTK_LICENSE_CUSTOM`. The license text will be displayed on the Legal page, below the copyright information. License text can contain Pango markup and links. [method@AboutWindow.add_legal_section] can be used to add license information for the application dependencies or other components. Use [class@AboutDialog]. an about window the license Sets the license for @self from a list of known licenses. If the application's license is not in the list, [property@AboutWindow:license] can be used instead. The license type will be automatically set to `GTK_LICENSE_CUSTOM` in that case. If @license_type is `GTK_LICENSE_UNKNOWN`, no information will be displayed. If @license_type is different from `GTK_LICENSE_CUSTOM`. [property@AboutWindow:license] will be cleared out. The license description will be displayed on the Legal page, below the copyright information. [method@AboutWindow.add_legal_section] can be used to add license information for the application dependencies or other components. Use [class@AboutDialog]. an about window the license type Sets the release notes for @self. Release notes are displayed on the the What's New page. Release notes are formatted the same way as [AppStream descriptions](https://freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description). The supported formatting options are: * Paragraph (`<p>`) * Ordered list (`<ol>`), with list items (`<li>`) * Unordered list (`<ul>`), with list items (`<li>`) Within paragraphs and list items, emphasis (`<em>`) and inline code (`<code>`) text styles are supported. The emphasis is rendered in italic, while inline code is shown in a monospaced font. Any text outside paragraphs or list items is ignored. Nested lists are not supported. `AdwAboutWindow` displays the version above the release notes. If set, the [property@AboutWindow:release-notes-version] of the property will be used as the version; otherwise, [property@AboutWindow:version] is used. Use [class@AboutDialog]. an about window the release notes Sets the version described by the application's release notes. The release notes version is displayed on the What's New page, above the release notes. If not set, [property@AboutWindow:version] will be used instead. For example, an application with the current version 2.0.2 might want to keep the release notes from 2.0.0, and set the release notes version accordingly. See [property@AboutWindow:release-notes]. Use [class@AboutDialog]. an about window the release notes version Sets the URL of the support page for @self. The support page link is displayed on the main page. Use [class@AboutDialog]. an about window the support page URL Sets the translator credits string. It will be displayed on the Credits page. This string should be `"translator-credits"` or `"translator_credits"` and should be marked as translatable. The string may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutWindow:developers] * [property@AboutWindow:designers] * [property@AboutWindow:artists] * [property@AboutWindow:documenters] * [method@AboutWindow.add_credit_section] * [method@AboutWindow.add_acknowledgement_section] Use [class@AboutDialog]. an about window the translator credits Sets the version for @self. The version is displayed on the main page. If [property@AboutWindow:release-notes-version] is not set, the version will also be displayed above the release notes on the What's New page. Use [class@AboutDialog]. an about window the version Sets the application website URL for @self. Website is displayed on the Details page, below comments, or on the main page if the Details page doesn't have any other content. Applications can add other links below, see [method@AboutWindow.add_link]. Use [class@AboutDialog]. an about window the website URL The name of the application icon. The icon is displayed at the top of the main page. Use [class@AboutDialog]. The name of the application. The name is displayed at the top of the main page. Use [class@AboutDialog]. The list of artists of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutWindow:developers] * [property@AboutWindow:designers] * [property@AboutWindow:documenters] * [property@AboutWindow:translator-credits] * [method@AboutWindow.add_credit_section] * [method@AboutWindow.add_acknowledgement_section] Use [class@AboutDialog]. The comments about the application. Comments will be shown on the Details page, above links. Unlike [property@Gtk.AboutDialog:comments], this string can be long and detailed. It can also contain links and Pango markup. Use [class@AboutDialog]. The copyright information. This should be a short string of one or two lines, for example: `© 2022 Example`. The copyright information will be displayed on the Legal page, above the application license. [method@AboutWindow.add_legal_section] can be used to add copyright information for the application dependencies or other components. Use [class@AboutDialog]. The debug information. Debug information will be shown on the Troubleshooting page. It's intended to be attached to issue reports when reporting issues against the application. `AdwAboutWindow` provides a quick way to save debug information to a file. When saving, [property@AboutWindow:debug-info-filename] would be used as the suggested filename. Debug information cannot contain markup or links. Use [class@AboutDialog]. The debug information filename. It will be used as the suggested filename when saving debug information to a file. See [property@AboutWindow:debug-info]. Use [class@AboutDialog]. The list of designers of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutWindow:developers] * [property@AboutWindow:artists] * [property@AboutWindow:documenters] * [property@AboutWindow:translator-credits] * [method@AboutWindow.add_credit_section] * [method@AboutWindow.add_acknowledgement_section] Use [class@AboutDialog]. The developer name. The developer name is displayed on the main page, under the application name. If the application is developed by multiple people, the developer name can be set to values like "AppName team", "AppName developers" or "The AppName project", and the individual contributors can be listed on the Credits page, with [property@AboutWindow:developers] and related properties. Use [class@AboutDialog]. The list of developers of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutWindow:designers] * [property@AboutWindow:artists] * [property@AboutWindow:documenters] * [property@AboutWindow:translator-credits] * [method@AboutWindow.add_credit_section] * [method@AboutWindow.add_acknowledgement_section] Use [class@AboutDialog]. The list of documenters of the application. It will be displayed on the Credits page. Each name may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutWindow:developers] * [property@AboutWindow:designers] * [property@AboutWindow:artists] * [property@AboutWindow:translator-credits] * [method@AboutWindow.add_credit_section] * [method@AboutWindow.add_acknowledgement_section] Use [class@AboutDialog]. The URL for the application's issue tracker. The issue tracker link is displayed on the main page. Use [class@AboutDialog]. The license text. This can be used to set a custom text for the license if it can't be set via [property@AboutWindow:license-type]. When set, [property@AboutWindow:license-type] will be set to `GTK_LICENSE_CUSTOM`. The license text will be displayed on the Legal page, below the copyright information. License text can contain Pango markup and links. [method@AboutWindow.add_legal_section] can be used to add license information for the application dependencies or other components. Use [class@AboutDialog]. The license type. Allows to set the application's license froma list of known licenses. If the application's license is not in the list, [property@AboutWindow:license] can be used instead. The license type will be automatically set to `GTK_LICENSE_CUSTOM` in that case. If set to `GTK_LICENSE_UNKNOWN`, no information will be displayed. If the license type is different from `GTK_LICENSE_CUSTOM`. [property@AboutWindow:license] will be cleared out. The license description will be displayed on the Legal page, below the copyright information. [method@AboutWindow.add_legal_section] can be used to add license information for the application dependencies or other components. Use [class@AboutDialog]. The release notes of the application. Release notes are displayed on the the What's New page. Release notes are formatted the same way as [AppStream descriptions](https://freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-description). The supported formatting options are: * Paragraph (`<p>`) * Ordered list (`<ol>`), with list items (`<li>`) * Unordered list (`<ul>`), with list items (`<li>`) Within paragraphs and list items, emphasis (`<em>`) and inline code (`<code>`) text styles are supported. The emphasis is rendered in italic, while inline code is shown in a monospaced font. Any text outside paragraphs or list items is ignored. Nested lists are not supported. `AdwAboutWindow` displays the version above the release notes. If set, the [property@AboutWindow:release-notes-version] of the property will be used as the version; otherwise, [property@AboutWindow:version] is used. Use [class@AboutDialog]. The version described by the application's release notes. The release notes version is displayed on the What's New page, above the release notes. If not set, [property@AboutWindow:version] will be used instead. For example, an application with the current version 2.0.2 might want to keep the release notes from 2.0.0, and set the release notes version accordingly. See [property@AboutWindow:release-notes]. Use [class@AboutDialog]. The URL of the application's support page. The support page link is displayed on the main page. Use [class@AboutDialog]. The translator credits string. It will be displayed on the Credits page. This string should be `"translator-credits"` or `"translator_credits"` and should be marked as translatable. The string may contain email addresses and URLs, see the introduction for more details. See also: * [property@AboutWindow:developers] * [property@AboutWindow:designers] * [property@AboutWindow:artists] * [property@AboutWindow:documenters] * [method@AboutWindow.add_credit_section] * [method@AboutWindow.add_acknowledgement_section] Use [class@AboutDialog]. The version of the application. The version is displayed on the main page. If [property@AboutWindow:release-notes-version] is not set, the version will also be displayed above the release notes on the What's New page. Use [class@AboutDialog]. The URL of the application's website. Website is displayed on the Details page, below comments, or on the main page if the Details page doesn't have any other content. Applications can add other links below, see [method@AboutWindow.add_link]. Use [class@AboutDialog]. Emitted when a URL is activated. Applications may connect to it to override the default behavior, which is to call [func@Gtk.show_uri]. Use [class@AboutDialog]. `TRUE` if the link has been activated the URI to activate Describes the available system accent colors. Use a blue color (`#3584e4`). This is the default value. Use a teal color (`#2190a4`). Use a green color (`#3a944a`). Use a yellow color (`#c88800`). Use a orange color (`#ed5b00`). Use a red color (`#e62d42`). Use a pink color (`#d56199`). Use a purple color (`#9141ac`). Use a slate color (`#6f8396`). Converts @self to a `GdkRGBA` representing its background color. The matching foreground color is white. an accent color return location for the color Converts @self to a `GdkRGBA` representing its standalone color. It will typically be darker for light background, and lighter for dark background, ensuring contrast. an accent color Whether to calculate standalone color for light or dark background return location for the color A [class@Gtk.ListBoxRow] used to present actions. <picture> <source srcset="action-row-dark.png" media="(prefers-color-scheme: dark)"> <img src="action-row.png" alt="action-row"> </picture> The `AdwActionRow` widget can have a title, a subtitle and an icon. The row can receive additional widgets at its end, or prefix widgets at its start. It is convenient to present a preference and its related actions. `AdwActionRow` is unactivatable by default, giving it an activatable widget will automatically make it activatable, but unsetting it won't change the row's activatability. ## AdwActionRow as GtkBuildable The `AdwActionRow` implementation of the [iface@Gtk.Buildable] interface supports adding a child at its end by specifying “suffix” or omitting the “type” attribute of a <child> element. It also supports adding a child as a prefix widget by specifying “prefix” as the “type” attribute of a <child> element. ## CSS nodes `AdwActionRow` has a main CSS node with name `row`. It contains the subnode `box.header` for its main horizontal box, and `box.title` for the vertical box containing the title and subtitle labels. It contains subnodes `label.title` and `label.subtitle` representing respectively the title label and subtitle label. `AdwActionRow` can use the [`.property`](style-classes.html#property-rows) style class to emphasize the row subtitle instead of the row title, which is useful for displaying read-only properties. Creates a new `AdwActionRow`. the newly created `AdwActionRow` Activates @self. an action row Activates @self. an action row Adds a prefix widget to @self. an action row a widget Adds a suffix widget to @self. an action row a widget Gets the widget activated when @self is activated. the activatable widget for @self an action row Gets the icon name for @self. Use [method@ActionRow.add_prefix] to add an icon. the icon name for @self an action row Gets the subtitle for @self. the subtitle for @self an action row Gets the number of lines at the end of which the subtitle label will be ellipsized. the number of lines at the end of which the subtitle label will be ellipsized an action row Gets whether the user can copy the subtitle from the label whether the user can copy the subtitle from the label an action row Gets the number of lines at the end of which the title label will be ellipsized. the number of lines at the end of which the title label will be ellipsized an action row Removes a child from @self. an action row the child to be removed Sets the widget to activate when @self is activated. The row can be activated either by clicking on it, calling [method@ActionRow.activate], or via mnemonics in the title. See the [property@PreferencesRow:use-underline] property to enable mnemonics. The target widget will be activated by emitting the [signal@Gtk.Widget::mnemonic-activate] signal on it. an action row the target widget Sets the icon name for @self. Use [method@ActionRow.add_prefix] to add an icon. an action row the icon name Sets the subtitle for @self. The subtitle is interpreted as Pango markup unless [property@PreferencesRow:use-markup] is set to `FALSE`. an action row the subtitle Sets the number of lines at the end of which the subtitle label will be ellipsized. If the value is 0, the number of lines won't be limited. an action row the number of lines at the end of which the subtitle label will be ellipsized Sets whether the user can copy the subtitle from the label See also [property@Gtk.Label:selectable]. an action row `TRUE` if the user can copy the subtitle from the label Sets the number of lines at the end of which the title label will be ellipsized. If the value is 0, the number of lines won't be limited. an action row the number of lines at the end of which the title label will be ellipsized The widget to activate when the row is activated. The row can be activated either by clicking on it, calling [method@ActionRow.activate], or via mnemonics in the title. See the [property@PreferencesRow:use-underline] property to enable mnemonics. The target widget will be activated by emitting the [signal@Gtk.Widget::mnemonic-activate] signal on it. The icon name for this row. Use [method@ActionRow.add_prefix] to add an icon. The subtitle for this row. The subtitle is interpreted as Pango markup unless [property@PreferencesRow:use-markup] is set to `FALSE`. The number of lines at the end of which the subtitle label will be ellipsized. If the value is 0, the number of lines won't be limited. Whether the user can copy the subtitle from the label. See also [property@Gtk.Label:selectable]. The number of lines at the end of which the title label will be ellipsized. If the value is 0, the number of lines won't be limited. This signal is emitted after the row has been activated. The parent class Activates the row to trigger its main action. an action row A dialog presenting a message or a question. <picture> <source srcset="alert-dialog-dark.png" media="(prefers-color-scheme: dark)"> <img src="alert-dialog.png" alt="alert-dialog"> </picture> Alert dialogs have a heading, a body, an optional child widget, and one or multiple responses, each presented as a button. Each response has a unique string ID, and a button label. Additionally, each response can be enabled or disabled, and can have a suggested or destructive appearance. When one of the responses is activated, or the dialog is closed, the [signal@AlertDialog::response] signal will be emitted. This signal is detailed, and the detail, as well as the `response` parameter will be set to the ID of the activated response, or to the value of the [property@AlertDialog:close-response] property if the dialog had been closed without activating any of the responses. Response buttons can be presented horizontally or vertically depending on available space. When a response is activated, `AdwAlertDialog` is closed automatically. An example of using an alert dialog: ```c AdwDialog *dialog; dialog = adw_alert_dialog_new (_("Replace File?"), NULL); adw_alert_dialog_format_body (ADW_ALERT_DIALOG (dialog), _("A file named “%s” already exists. Do you want to replace it?"), filename); adw_alert_dialog_add_responses (ADW_ALERT_DIALOG (dialog), "cancel", _("_Cancel"), "replace", _("_Replace"), NULL); adw_alert_dialog_set_response_appearance (ADW_ALERT_DIALOG (dialog), "replace", ADW_RESPONSE_DESTRUCTIVE); adw_alert_dialog_set_default_response (ADW_ALERT_DIALOG (dialog), "cancel"); adw_alert_dialog_set_close_response (ADW_ALERT_DIALOG (dialog), "cancel"); g_signal_connect (dialog, "response", G_CALLBACK (response_cb), self); adw_dialog_present (dialog, parent); ``` ## Async API `AdwAlertDialog` can also be used via the [method@AlertDialog.choose] method. This API follows the GIO async pattern, for example: ```c static void dialog_cb (AdwAlertDialog *dialog, GAsyncResult *result, MyWindow *self) { const char *response = adw_alert_dialog_choose_finish (dialog, result); // ... } static void show_dialog (MyWindow *self) { AdwDialog *dialog; dialog = adw_alert_dialog_new (_("Replace File?"), NULL); adw_alert_dialog_format_body (ADW_ALERT_DIALOG (dialog), _("A file named “%s” already exists. Do you want to replace it?"), filename); adw_alert_dialog_add_responses (ADW_ALERT_DIALOG (dialog), "cancel", _("_Cancel"), "replace", _("_Replace"), NULL); adw_alert_dialog_set_response_appearance (ADW_ALERT_DIALOG (dialog), "replace", ADW_RESPONSE_DESTRUCTIVE); adw_alert_dialog_set_default_response (ADW_ALERT_DIALOG (dialog), "cancel"); adw_alert_dialog_set_close_response (ADW_ALERT_DIALOG (dialog), "cancel"); adw_alert_dialog_choose (ADW_ALERT_DIALOG (dialog), GTK_WIDGET (self), NULL, (GAsyncReadyCallback) dialog_cb, self); } ``` ## AdwAlertDialog as GtkBuildable `AdwAlertDialog` supports adding responses in UI definitions by via the `<responses>` element that may contain multiple `<response>` elements, each respresenting a response. Each of the `<response>` elements must have the `id` attribute specifying the response ID. The contents of the element are used as the response label. Response labels can be translated with the usual `translatable`, `context` and `comments` attributes. The `<response>` elements can also have `enabled` and/or `appearance` attributes. See [method@AlertDialog.set_response_enabled] and [method@AlertDialog.set_response_appearance] for details. Example of an `AdwAlertDialog` UI definition: ```xml <object class="AdwAlertDialog" id="dialog"> <property name="heading" translatable="yes">Save Changes?</property> <property name="body" translatable="yes">Open documents contain unsaved changes. Changes which are not saved will be permanently lost.</property> <property name="default-response">save</property> <property name="close-response">cancel</property> <signal name="response" handler="response_cb"/> <responses> <response id="cancel" translatable="yes">_Cancel</response> <response id="discard" translatable="yes" appearance="destructive">_Discard</response> <response id="save" translatable="yes" appearance="suggested" enabled="false">_Save</response> </responses> </object> ``` Creates a new `AdwAlertDialog`. @heading and @body can be set to `NULL`. This can be useful if they need to be formatted or use markup. In that case, set them to `NULL` and call [method@AlertDialog.format_body] or similar methods afterwards: ```c AdwDialog *dialog; dialog = adw_alert_dialog_new (_("Replace File?"), NULL); adw_alert_dialog_format_body (ADW_ALERT_DIALOG (dialog), _("A file named “%s” already exists. Do you want to replace it?"), filename); ``` the newly created `AdwAlertDialog` the heading the body text Adds a response with @id and @label to @self. Responses are represented as buttons in the dialog. Response ID must be unique. It will be used in [signal@AlertDialog::response] to tell which response had been activated, as well as to inspect and modify the response later. An embedded underline in @label indicates a mnemonic. [method@AlertDialog.set_response_label] can be used to change the response label after it had been added. [method@AlertDialog.set_response_enabled] and [method@AlertDialog.set_response_appearance] can be used to customize the responses further. an alert dialog the response ID the response label Adds multiple responses to @self. This is the same as calling [method@AlertDialog.add_response] repeatedly. The variable argument list should be `NULL`-terminated list of response IDs and labels. Example: ```c adw_alert_dialog_add_responses (dialog, "cancel", _("_Cancel"), "discard", _("_Discard"), "save", _("_Save"), NULL); ``` an alert dialog response id label for first response, then more id-label pairs This function shows @self to the user. If the window is an [class@Window] or [class@ApplicationWindow], the dialog will be shown within it. Otherwise, it will be a separate window. an alert dialog the parent widget a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@AlertDialog.choose] call and returns the response ID. the ID of the response that was selected, or [property@AlertDialog:close-response] if the call was cancelled. an alert dialog a `GAsyncResult` Sets the formatted body text of @self. See [property@AlertDialog:body]. an alert dialog the formatted string for the body text the parameters to insert into @format Sets the formatted body text of @self with Pango markup. The @format is assumed to contain Pango markup. Special XML characters in the `printf()` arguments passed to this function will automatically be escaped as necessary, see [func@GLib.markup_printf_escaped]. See [property@AlertDialog:body]. an alert dialog the formatted string for the body text with Pango markup the parameters to insert into @format Sets the formatted heading of @self. See [property@AlertDialog:heading]. an alert dialog the formatted string for the heading the parameters to insert into @format Sets the formatted heading of @self with Pango markup. The @format is assumed to contain Pango markup. Special XML characters in the `printf()` arguments passed to this function will automatically be escaped as necessary, see [func@GLib.markup_printf_escaped]. See [property@AlertDialog:heading]. an alert dialog the formatted string for the heading with Pango markup the parameters to insert into @format Gets the body text of @self. the body of @self. an alert dialog Gets whether the body text of @self includes Pango markup. whether @self uses markup for body text an alert dialog Gets the ID of the close response of @self. the close response ID an alert dialog Gets the ID of the default response of @self. the default response ID an alert dialog Gets the child widget of @self. the child widget of @self. an alert dialog Gets the heading of @self. the heading of @self. an alert dialog Gets whether the heading of @self includes Pango markup. whether @self uses markup for heading an alert dialog Gets whether @self prefers wide layout. whether to prefer wide layout an alert dialog Gets the appearance of @response. See [method@AlertDialog.set_response_appearance]. the appearance of @response an alert dialog a response ID Gets whether @response is enabled. See [method@AlertDialog.set_response_enabled]. whether @response is enabled an alert dialog a response ID Gets the label of @response. See [method@AlertDialog.set_response_label]. the label of @response an alert dialog a response ID Gets whether @self has a response with the ID @response. whether @self has a response with the ID @response. an alert dialog response ID Removes a response from @self. an alert dialog the response ID Sets the body text of @self. an alert dialog the body of @self Sets whether the body text of @self includes Pango markup. See [func@Pango.parse_markup]. an alert dialog whether to use markup for body text Sets the ID of the close response of @self. It will be passed to [signal@AlertDialog::response] if the dialog is closed by pressing <kbd>Escape</kbd> or with a system action. It doesn't have to correspond to any of the responses in the dialog. The default close response is `close`. an alert dialog the close response ID Sets the ID of the default response of @self. If set, pressing <kbd>Enter</kbd> will activate the corresponding button. If set to `NULL` or to a non-existent response ID, pressing <kbd>Enter</kbd> will do nothing. an alert dialog the default response ID Sets the child widget of @self. The child widget is displayed below the heading and body. an alert dialog the child widget Sets the heading of @self. an alert dialog the heading of @self Sets whether the heading of @self includes Pango markup. See [func@Pango.parse_markup]. an alert dialog whether to use markup for heading Sets whether @self prefers wide layout. Prefer horizontal button layout when possible, and wider dialog width otherwise. an alert dialog whether to prefer wide layout Sets the appearance for @response. <picture> <source srcset="alert-dialog-appearance-dark.png" media="(prefers-color-scheme: dark)"> <img src="alert-dialog-appearance.png" alt="alert-dialog-appearance"> </picture> Use `ADW_RESPONSE_SUGGESTED` to mark important responses such as the affirmative action, like the Save button in the example. Use `ADW_RESPONSE_DESTRUCTIVE` to draw attention to the potentially damaging consequences of using @response. This appearance acts as a warning to the user. The Discard button in the example is using this appearance. The default appearance is `ADW_RESPONSE_DEFAULT`. Negative responses like Cancel or Close should use the default appearance. an alert dialog a response ID appearance for @response Sets whether @response is enabled. If @response is not enabled, the corresponding button will have [property@Gtk.Widget:sensitive] set to `FALSE` and it can't be activated as a default response. @response can still be used as [property@AlertDialog:close-response] while it's not enabled. Responses are enabled by default. an alert dialog a response ID whether to enable @response Sets the label of @response to @label. Labels are displayed on the dialog buttons. An embedded underline in @label indicates a mnemonic. an alert dialog a response ID the label of @response The body text of the dialog. Whether the body text includes Pango markup. See [func@Pango.parse_markup]. The ID of the close response. It will be passed to [signal@AlertDialog::response] if the dialog is closed by pressing <kbd>Escape</kbd> or with a system action. It doesn't have to correspond to any of the responses in the dialog. The default close response is `close`. The response ID of the default response. If set, pressing <kbd>Enter</kbd> will activate the corresponding button. If set to `NULL` or a non-existent response ID, pressing <kbd>Enter</kbd> will do nothing. The child widget. Displayed below the heading and body. The heading of the dialog. Whether the heading includes Pango markup. See [func@Pango.parse_markup]. Whether to prefer wide layout. Prefer horizontal button layout when possible, and wider dialog width otherwise. This signal is emitted when the dialog is closed. @response will be set to the response ID of the button that had been activated. if the dialog was closed by pressing <kbd>Escape</kbd> or with a system action, @response will be set to the value of [property@AlertDialog:close-response]. the response ID A base class for animations. `AdwAnimation` represents an animation on a widget. It has a target that provides a value to animate, and a state indicating whether the animation hasn't been started yet, is playing, paused or finished. Currently there are two concrete animation types: [class@TimedAnimation] and [class@SpringAnimation]. `AdwAnimation` will automatically skip the animation if [property@Animation:widget] is unmapped, or if [property@Gtk.Settings:gtk-enable-animations] is `FALSE`. The [signal@Animation::done] signal can be used to perform an action after the animation ends, for example hiding a widget after animating its [property@Gtk.Widget:opacity] to 0. `AdwAnimation` will be kept alive while the animation is playing. As such, it's safe to create an animation, start it and immediately unref it: A fire-and-forget animation: ```c static void animation_cb (double value, MyObject *self) { // Do something with @value } static void my_object_animate (MyObject *self) { AdwAnimationTarget *target = adw_callback_animation_target_new ((AdwAnimationTargetFunc) animation_cb, self, NULL); g_autoptr (AdwAnimation) animation = adw_timed_animation_new (widget, 0, 1, 250, target); adw_animation_play (animation); } ``` If there's a chance the previous animation for the same target hasn't yet finished, the previous animation should be stopped first, or the existing `AdwAnimation` object can be reused. Gets whether @self should be skipped when animations are globally disabled. whether to follow the global setting an animation Gets the current value of @self. The state indicates whether @self is currently playing, paused, finished or hasn't been started yet. the animation value an animation Gets the target @self animates. the animation target an animation Gets the current value of @self. the current value an animation Gets the widget @self was created for. It provides the frame clock for the animation. It's not strictly necessary for this widget to be same as the one being animated. The widget must be mapped in order for the animation to work. If it's not mapped, or if it gets unmapped during an ongoing animation, the animation will be automatically skipped. the animation widget an animation Pauses a playing animation for @self. Does nothing if the current state of @self isn't `ADW_ANIMATION_PLAYING`. Sets [property@Animation:state] to `ADW_ANIMATION_PAUSED`. an animation Starts the animation for @self. If the animation is playing, paused or has been completed, restarts it from the beginning. This allows to easily play an animation regardless of whether it's already playing or not. Sets [property@Animation:state] to `ADW_ANIMATION_PLAYING`. The animation will be automatically skipped if [property@Animation:widget] is unmapped, or if [property@Gtk.Settings:gtk-enable-animations] is `FALSE`. As such, it's not guaranteed that the animation will actually run. For example, when using [func@GLib.idle_add] and starting an animation immediately afterwards, it's entirely possible that the idle callback will run after the animation has already finished, and not while it's playing. an animation Resets the animation for @self. Sets [property@Animation:state] to `ADW_ANIMATION_IDLE`. an animation Resumes a paused animation for @self. This function must only be used if the animation has been paused with [method@Animation.pause]. Sets [property@Animation:state] to `ADW_ANIMATION_PLAYING`. an animation Sets whether to skip @self when animations are globally disabled. The default behavior is to skip the animation. Set to `FALSE` to disable this behavior. This can be useful for cases where animation is essential, like spinners, or in demo applications. Most other animations should keep it enabled. See [property@Gtk.Settings:gtk-enable-animations]. an animation whether to follow the global setting Sets the target @self animates to @target. an animation an animation target Skips the animation for @self. If the animation hasn't been started yet, is playing, or is paused, instantly skips the animation to the end and causes [signal@Animation::done] to be emitted. Sets [property@Animation:state] to `ADW_ANIMATION_FINISHED`. an animation Whether to skip the animation when animations are globally disabled. The default behavior is to skip the animation. Set to `FALSE` to disable this behavior. This can be useful for cases where animation is essential, like spinners, or in demo applications. Most other animations should keep it enabled. See [property@Gtk.Settings:gtk-enable-animations]. The animation state. The state indicates whether the animation is currently playing, paused, finished or hasn't been started yet. The target to animate. The current value of the animation. The animation widget. It provides the frame clock for the animation. It's not strictly necessary for this widget to be same as the one being animated. The widget must be mapped in order for the animation to work. If it's not mapped, or if it gets unmapped during an ongoing animation, the animation will be automatically skipped. This signal is emitted when the animation has been completed, either on its own or via calling [method@Animation.skip]. Describes the possible states of an [class@Animation]. The state can be controlled with [method@Animation.play], [method@Animation.pause], [method@Animation.resume], [method@Animation.reset] and [method@Animation.skip]. The animation hasn't started yet. The animation has been paused. The animation is currently playing. The animation has finished. Represents a value [class@Animation] can animate. Prototype for animation targets based on user callbacks. The animation value The user data provided when creating the target A base class for Adwaita applications. `AdwApplication` handles library initialization by calling [func@init] in the default [signal@Gio.Application::startup] signal handler, in turn chaining up as required by [class@Gtk.Application]. Therefore, any subclass of `AdwApplication` should always chain up its `startup` handler before using any Adwaita or GTK API. ## Automatic Resources `AdwApplication` will automatically load stylesheets located in the application's resource base path (see [method@Gio.Application.set_resource_base_path], if they're present. They can be used to add custom styles to the application, as follows: - `style.css` contains styles that are always present. - `style-dark.css` contains styles only used when [property@StyleManager:dark] is `TRUE`. - `style-hc.css` contains styles used when the system high contrast preference is enabled. - `style-hc-dark.css` contains styles used when the system high contrast preference is enabled and [property@StyleManager:dark] is `TRUE`. Creates a new `AdwApplication`. If `application_id` is not `NULL`, then it must be valid. See [func@Gio.Application.id_is_valid]. If no application ID is given then some features (most notably application uniqueness) will be disabled. the newly created `AdwApplication` The application ID The application flags Gets the style manager for @self. This is a convenience property allowing to access `AdwStyleManager` through property bindings or expressions. the style manager an application The style manager for this application. This is a convenience property allowing to access `AdwStyleManager` through property bindings or expressions. The parent class A freeform application window. <picture> <source srcset="application-window-dark.png" media="(prefers-color-scheme: dark)"> <img src="application-window.png" alt="application-window"> </picture> `AdwApplicationWindow` is a [class@Gtk.ApplicationWindow] subclass providing the same features as [class@Window]. See [class@Window] for details. Example of an `AdwApplicationWindow` UI definition: ```xml <object class="AdwApplicationWindow"> <property name="content"> <object class="AdwToolbarView"> <child type="top"> <object class="AdwHeaderBar"/> </child> <property name="content"> <!-- ... --> </property> </object> </property> </object> ``` Using [property@Gtk.Application:menubar] is not supported and may result in visual glitches. Creates a new `AdwApplicationWindow` for @app. the newly created `AdwApplicationWindow` an application instance Adds @breakpoint to @self. an application window the breakpoint to add Gets the content widget of @self. This method should always be used instead of [method@Gtk.Window.get_child]. the content widget of @self an application window Gets the current breakpoint. the current breakpoint an application window Returns a [iface@Gio.ListModel] that contains the open dialogs of @self. This can be used to keep an up-to-date view. a list model for the dialogs of @self an application window Returns the currently visible dialog in @self, if there's one. the visible dialog an application window Sets the content widget of @self. This method should always be used instead of [method@Gtk.Window.set_child]. an application window the content widget The content widget. This property should always be used instead of [property@Gtk.Window:child]. The current breakpoint. The open dialogs. The currently visible dialog A widget displaying an image, with a generated fallback. <picture> <source srcset="avatar-dark.png" media="(prefers-color-scheme: dark)"> <img src="avatar.png" alt="avatar"> </picture> `AdwAvatar` is a widget that shows a round avatar. `AdwAvatar` generates an avatar with the initials of the [property@Avatar:text] on top of a colored background. The color is picked based on the hash of the [property@Avatar:text]. If [property@Avatar:show-initials] is set to `FALSE`, [property@Avatar:icon-name] or `avatar-default-symbolic` is shown instead of the initials. Use [property@Avatar:custom-image] to set a custom image. ## CSS nodes `AdwAvatar` has a single CSS node with name `avatar`. Creates a new `AdwAvatar`. the newly created `AdwAvatar` The size of the avatar the text used to get the initials and color whether to use initials instead of an icon as fallback Renders @self into a [class@Gdk.Texture] at @scale_factor. This can be used to export the fallback avatar. the texture an avatar The scale factor Gets the custom image paintable. the custom image an avatar Gets the name of an icon to use as a fallback. the icon name an avatar Gets whether initials are used instead of an icon on the fallback avatar. whether initials are used instead of an icon as fallback an avatar Gets the size of the avatar. the size of the avatar an avatar Gets the text used to generate the fallback initials and color. the text used to generate the fallback initials and color an avatar Sets the custom image paintable. Custom image is displayed instead of initials or icon. an avatar a custom image Sets the name of an icon to use as a fallback. If no name is set, `avatar-default-symbolic` will be used. an avatar the icon name Sets whether to use initials instead of an icon on the fallback avatar. See [property@Avatar:icon-name] for how to change the fallback icon. an avatar whether to use initials instead of an icon as fallback Sets the size of the avatar. an avatar The size of the avatar Sets the text used to generate the fallback initials and color. It's only used to generate the color if [property@Avatar:show-initials] is `FALSE`. an avatar the text used to get the initials and color A custom image paintable. Custom image is displayed instead of initials or icon. The name of an icon to use as a fallback. If no name is set, `avatar-default-symbolic` will be used. Whether initials are used instead of an icon on the fallback avatar. See [property@Avatar:icon-name] for how to change the fallback icon. The size of the avatar. Sets the text used to generate the fallback initials and color. It's only used to generate the color if [property@Avatar:show-initials] is `FALSE`. A bar with contextual information. <picture> <source srcset="banner-dark.png" media="(prefers-color-scheme: dark)"> <img src="banner.png" alt="banner"> </picture> Banners are hidden by default, use [property@Banner:revealed] to show them. Banners have a title, set with [property@Banner:title]. Titles can be marked up with Pango markup, use [property@Banner:use-markup] to enable it. The title will be shown centered or left-aligned depending on available space. Banners can optionally have a button with text on it, set through [property@Banner:button-label]. The button can be used with a `GAction`, or with the [signal@Banner::button-clicked] signal. ## CSS nodes `AdwBanner` has a main CSS node with the name `banner`. Creates a new `AdwBanner`. the newly created `AdwBanner` the banner title Gets the button label for @self. the button label for @self a banner Gets if a banner is revealed Whether a banner is revealed a banner Gets the title for @self. the title for @self a banner Gets whether to use Pango markup for the banner title. whether to use markup a banner Sets the button label for @self. If set to `""` or `NULL`, the button won't be shown. The button can be used with a `GAction`, or with the [signal@Banner::button-clicked] signal. a banner the label Sets whether a banner should be revealed a banner whether a banner should be revealed Sets the title for this banner. See also: [property@Banner:use-markup]. a banner the title Sets whether to use Pango markup for the banner title. See also [func@Pango.parse_markup]. a banner whether to use markup The label to show on the button. If set to `""` or `NULL`, the button won't be shown. The button can be used with a `GAction`, or with the [signal@Banner::button-clicked] signal. Whether the banner is currently revealed. The title for this banner. See also: [property@Banner:use-markup]. Whether to use Pango markup for the banner title. See also [func@Pango.parse_markup]. This signal is emitted after the action button has been clicked. It can be used as an alternative to setting an action. A widget with one child. <picture> <source srcset="bin-dark.png" media="(prefers-color-scheme: dark)"> <img src="bin.png" alt="bin"> </picture> The `AdwBin` widget has only one child, set with the [property@Bin:child] property. It is useful for deriving subclasses, since it provides common code needed for handling a single child widget. Creates a new `AdwBin`. the new created `AdwBin` Gets the child widget of @self. the child widget of @self a bin Sets the child widget of @self. a bin the child widget The child widget of the `AdwBin`. A bottom sheet with an optional bottom bar. <picture> <source srcset="bottom-sheet-dark.png" media="(prefers-color-scheme: dark)"> <img src="bottom-sheet.png" alt="bottom-sheet"> </picture> `AdwBottomSheet` has three child widgets. [property@BottomSheet:content] is shown persistently. [property@BottomSheet:sheet] is displayed above it when it's open, and [property@BottomSheet:bottom-bar] is displayed when it's not. Bottom sheet and bottom bar are attached to the bottom edge of the widget. They take the full width by default, but can only take a portion of it if [property@BottomSheet:full-width] is set to `FALSE`. In this case, [property@BottomSheet:align] determines where along the bottom edge they are placed. `AdwBottomSheet` can be useful for applications such as music players, that want to have a persistent bottom bar that expands into a bottom sheet when clicked. It's meant for cases where a bottom sheet is tightly integrated into the UI. For more transient bottom sheets, see [class@Dialog]. To open or close the bottom sheet, use the [property@BottomSheet:open] property. By default, the bottom sheet has an overlaid drag handle. It can be disabled by setting [property@BottomSheet:show-drag-handle] to `FALSE`. Note that the handle also controls whether the sheet can be dragged using a pointer. Bottom sheets are modal by default, meaning that the content is dimmed and cannot be accessed while the sheet is open. Set [property@BottomSheet:modal] to `FALSE` if this behavior is unwanted. To disable user interactions for opening or closing the bottom sheet (such as swipes or clicking the bottom bar or close button), set [property@BottomSheet:can-open] or [property@BottomSheet:can-close] to `FALSE`. In some cases, particularly when using a full-width bottom bar, it may be necessary to shift [property@BottomSheet:content] upwards. Use the [property@BottomSheet:bottom-bar-height] and [property@BottomSheet:sheet-height] for that. `AdwBottomSheet` is not adaptive, and for larger window sizes applications may want to replace it with another UI, such as a sidebar. This can be done using [class@MultiLayoutView]. ## Sizing Unlike [class@Dialog] presented as a bottom sheet, `AdwBottomSheet` just follows the content's natural size, and it's up to the applications to make sure their content provides one. For example, when using [class@Gtk.ScrolledWindow], make sure to set [property@Gtk.ScrolledWindow:propagate-natural-height] to `TRUE`. ## Header Bar Integration When placed inside an `AdwBottomSheet`, [class@HeaderBar] will not show the title when [property@BottomSheet:show-drag-handle] is `TRUE`, regardless of [property@HeaderBar:show-title]. This only applies to the default title, titles set with [property@HeaderBar:title-widget] will still be shown. ## `AdwBottomSheet` as `GtkBuildable`: The `AdwBottomSheet` implementation of the [iface@Gtk.Buildable] interface supports setting the sheet widget by specifying “sheet” as the “type” attribute of a `<child>` element, and the bottom bar by specifying “bottom-bar”. Specifying “content” or omitting the child type results in setting the content child. Creates a new `AdwBottomSheet`. the new created `AdwBottomSheet` Gets horizontal alignment of the bottom sheet. the horizontal alignment a bottom sheet Gets the bottom bar widget for @self. the bottom bar widget a bottom sheet Gets the current bottom bar height. It can be used to shift the content upwards permanently to accommodate for the bottom bar. the bottom bar height a bottom sheet Gets whether the bottom sheet can be closed by user. whether the sheet can be closed by user a bottom sheet Gets whether the bottom sheet can be opened by user. whether the sheet can be opened by user. a bottom sheet Gets the content widget for @self. the content widget a bottom sheet Gets whether the bottom sheet takes the full width. whether the sheet takes up the full width a bottom sheet Gets whether the bottom sheet is modal. whether the sheet is modal a bottom sheet Gets whether the bottom sheet is open. whether the sheet is open a bottom sheet Gets the bottom sheet widget for @self. the sheet widget a bottom sheet Gets the current bottom sheet height. It can be used to shift the content upwards when the bottom sheet is open. the sheet height a bottom sheet Gets whether to show a drag handle in the bottom sheet. whether to show the drag handle a bottom sheet Sets horizontal alignment of the bottom sheet. 0 means the bottom sheet is flush with the start edge, 1 means it's flush with the end edge. 0.5 means it's centered. Only used when [property@BottomSheet:full-width] is set to `FALSE`. a bottom sheet the new alignment Sets the bottom bar widget for @self. Shown when [property@BottomSheet:open] is `FALSE`. When open, morphs into the [property@BottomSheet:sheet]. a bottom sheet the bottom bar widget Sets whether the bottom sheet can be closed by user. It can be closed via the close button, swiping down, pressing <kbd>Escape</kbd> or clicking the content dimming (when modal). Bottom sheet can still be closed using [property@BottomSheet:open]. a bottom sheet whether the sheet can be closed by user Sets whether the bottom sheet can be opened by user. It can be opened via clicking or swiping up from the bottom bar. Does nothing if [property@BottomSheet:bottom-bar] is not set. Bottom sheet can still be opened using [property@BottomSheet:open]. a bottom sheet whether the sheet can be opened by user. Sets the content widget for @self. It's always shown, and the bottom sheet is overlaid over it. a bottom sheet the content widget Sets whether the bottom sheet takes the full width. When full width, [property@BottomSheet:align] is ignored. a bottom sheet whether the sheet takes up the full width Sets whether the bottom sheet is modal. When modal, [property@BottomSheet:content] will be dimmed when the bottom sheet is open, and clicking it will close the bottom sheet. It also cannot be focused with keyboard. Otherwise, the content is accessible even when the bottom sheet is open. a bottom sheet whether the sheet is modal Sets whether the bottom sheet is open. a bottom sheet whether to open the sheet Sets the bottom sheet widget for @self. Only shown when [property@BottomSheet:open] is `TRUE`. a bottom sheet the sheet widget Sets whether to show a drag handle in the bottom sheet. The handle will be overlaid over [property@BottomSheet:sheet]. When the handle is shown, [class@HeaderBar] will hide its default title, and [class@ToolbarView] will reserve space if there are no top bars. Showing drag handle also allows to swipe the bottom sheet down (and to swipe the bottom bar up) with a pointer, instead of just touchscreen. a bottom sheet whether to show the drag handle Horizontal alignment of the bottom sheet. 0 means the bottom sheet is flush with the start edge, 1 means it's flush with the end edge. 0.5 means it's centered. Only used when [property@BottomSheet:full-width] is set to `FALSE`. The bottom bar widget. Shown when [property@BottomSheet:open] is `FALSE`. When open, morphs into the [property@BottomSheet:sheet]. The current bottom bar height. It can be used to shift the content upwards permanently to accommodate for the bottom bar. Whether the bottom sheet can be closed by user. It can be closed via the close button, swiping down, pressing <kbd>Escape</kbd> or clicking the content dimming (when modal). Bottom sheet can still be closed using [property@BottomSheet:open]. Whether the bottom sheet can be opened by user. It can be opened via clicking or swiping up from the bottom bar. Does nothing if [property@BottomSheet:bottom-bar] is not set. Bottom sheet can still be opened using [property@BottomSheet:open]. The content widget. It's always shown, and the bottom sheet is overlaid over it. Whether the bottom sheet takes the full width. When full width, [property@BottomSheet:align] is ignored. Whether the bottom sheet is modal. When modal, [property@BottomSheet:content] will be dimmed when the bottom sheet is open, and clicking it will close the bottom sheet. It also cannot be focused with keyboard. Otherwise, the content is accessible even when the bottom sheet is open. Whether the bottom sheet is open. The bottom sheet widget. Only shown when [property@BottomSheet:open] is `TRUE`. The current bottom sheet height. It can be used to shift the content upwards when the bottom sheet is open. Whether to overlay a drag handle in the bottom sheet. The handle will be overlaid over [property@BottomSheet:sheet]. When the handle is shown, [class@HeaderBar] will hide its default title, and [class@ToolbarView] will reserve space if there are no top bars. Showing drag handle also allows to swipe the bottom sheet down (and to swipe the bottom bar up) with a pointer, instead of just touchscreen. Emitted when the close button or shortcut is used while [property@Dialog:can-close] is set to `FALSE`. Describes a breakpoint for [class@Window] or [class@Dialog]. Breakpoints are used to create adaptive UI, allowing to change the layout depending on available size. Breakpoint is a size threshold, specified by its condition, as well as one or more setters. Each setter has a target object, a property and a value. When a breakpoint is applied, each setter sets the target property on their target object to the specified value, and reset it back to the original value when it's unapplied. For more complicated scenarios, [signal@Breakpoint::apply] and [signal@Breakpoint::unapply] can be used instead. Breakpoints can be used within [class@Window], [class@ApplicationWindow], [class@Dialog] or [class@BreakpointBin]. ## `AdwBreakpoint` as `GtkBuildable`: `AdwBreakpoint` supports specifying its condition via the `<condition>` element. The contents of the element must be a string in a format accepted by [func@BreakpointCondition.parse]. It also supports adding setters via the `<setter>` element. Each `<setter>` element must have the `object` attribute specifying the target object, and the `property` attribute specifying the property name. The contents of the element are used as the setter value. For `G_TYPE_OBJECT` and `G_TYPE_BOXED` derived properties, empty contents are treated as `NULL`. Setter values can be translated with the usual `translatable`, `context` and `comments` attributes. Example of an `AdwBreakpoint` UI definition: ```xml <object class="AdwBreakpoint"> <condition>max-width: 400px</condition> <setter object="button" property="visible">True</setter> <setter object="box" property="orientation">vertical</setter> <setter object="page" property="title" translatable="yes">Example</setter> </object> ``` Creates a new `AdwBreakpoint` with @condition. the newly created `AdwBreakpoint` the condition Adds a setter to @self. The setter will automatically set @property on @object to @value when applying the breakpoint, and set it back to its original value upon unapplying it. ::: note Setting properties to their original values does not work for properties that have irreversible side effects. For example, changing [property@Gtk.Button:label] while [property@Gtk.Button:icon-name] is set will reset the icon. However, resetting the label will not set `icon-name` to its original value. Use the [signal@Breakpoint::apply] and [signal@Breakpoint::unapply] signals for those properties instead, as follows: ```c static void breakpoint_apply_cb (MyWidget *self) { gtk_button_set_icon_name (self->button, "go-previous-symbolic"); } static void breakpoint_apply_cb (MyWidget *self) { gtk_button_set_label (self->button, _("_Back")); } // ... g_signal_connect_swapped (breakpoint, "apply", G_CALLBACK (breakpoint_apply_cb), self); g_signal_connect_swapped (breakpoint, "unapply", G_CALLBACK (breakpoint_unapply_cb), self); ``` a breakpoint the target object the target property the value to set Adds multiple setters to @self. See [method@Breakpoint.add_setter]. Example: ```c adw_breakpoint_add_setters (breakpoint, G_OBJECT (box), "orientation", GTK_ORIENTATION_VERTICAL, G_OBJECT (button), "halign", GTK_ALIGN_FILL, G_OBJECT (button), "valign", GTK_ALIGN_END, NULL); ``` a breakpoint the first target object the first target property the value of the first setter, followed by a list of object, property and value triplets, terminated by `NULL` Adds multiple setters to @self. See [method@Breakpoint.add_setters]. a breakpoint the first target object the first target property the value of the first setter, followed by a list of object, property and value triplets, terminated by `NULL` Adds @n_setters setters to @self. This is a convenience function for adding multiple setters at once. See [method@Breakpoint.add_setter]. This function is meant to be used by language bindings. a breakpoint the number of setters to add setter target object setter target properties setter values Gets the condition for @self. the condition a breakpoint Sets the condition for @self. a breakpoint the new condition The breakpoint's condition. Emitted when the breakpoint is applied. This signal is emitted after the setters have been applied. Emitted when the breakpoint is unapplied. This signal is emitted before resetting the setter values. A widget that changes layout based on available size. <picture> <source srcset="breakpoint-bin-dark.png" media="(prefers-color-scheme: dark)"> <img src="breakpoint-bin.png" alt="breakpoint-bin"> </picture> `AdwBreakpointBin` provides a way to use breakpoints without [class@Window], [class@ApplicationWindow] or [class@Dialog]. It can be useful for limiting breakpoints to a single page and similar purposes. Most applications shouldn't need it. `AdwBreakpointBin` is similar to [class@Bin]. It has one child, set via the [property@BreakpointBin:child] property. When `AdwBreakpointBin` is resized, its child widget can rearrange its layout at specific thresholds. The thresholds and layout changes are defined via [class@Breakpoint] objects. They can be added using [method@BreakpointBin.add_breakpoint]. Each breakpoint has a condition, specifying the bin's size and/or aspect ratio, and setters that automatically set object properties when that happens. The [signal@Breakpoint::apply] and [signal@Breakpoint::unapply] can be used instead for more complex scenarios. Breakpoints are only allowed to modify widgets inside the `AdwBreakpointBin`, but not on the `AdwBreakpointBin` itself or any other widgets. If multiple breakpoints can be used for the current size, the last one is always picked. The current breakpoint can be tracked using the [property@BreakpointBin:current-breakpoint] property. If none of the breakpoints can be used, that property will be set to `NULL`, and the original property values will be used instead. ## Minimum Size Adding a breakpoint to `AdwBreakpointBin` will result in it having no minimum size. The [property@Gtk.Widget:width-request] and [property@Gtk.Widget:height-request] properties must always be set when using breakpoints, indicating the smallest size you want to support. The minimum size and breakpoint conditions must be carefully selected so that the child widget completely fits. If it doesn't, it will overflow and a warning message will be printed. When choosing minimum size, consider translations and text scale factor changes. Make sure to leave enough space for text labels, and enable ellipsizing or wrapping if they might not fit. For [class@Gtk.Label] this can be done via [property@Gtk.Label:ellipsize], or via [property@Gtk.Label:wrap] together with [property@Gtk.Label:wrap-mode]. For buttons, use [property@Gtk.Button:can-shrink], [property@Gtk.MenuButton:can-shrink], [property@Adw.SplitButton:can-shrink], or [property@Adw.ButtonContent:can-shrink]. ## Example ```c GtkWidget *bin, *child; AdwBreakpoint *breakpoint; bin = adw_breakpoint_bin_new (); gtk_widget_set_size_request (bin, 150, 150); child = gtk_label_new ("Wide"); gtk_label_set_ellipsize (GTK_LABEL (label), PANGO_ELLIPSIZE_END); gtk_widget_add_css_class (child, "title-1"); adw_breakpoint_bin_set_child (ADW_BREAKPOINT_BIN (bin), child); breakpoint = adw_breakpoint_new (adw_breakpoint_condition_parse ("max-width: 200px")); adw_breakpoint_add_setters (breakpoint, G_OBJECT (child), "label", "Narrow", NULL); adw_breakpoint_bin_add_breakpoint (ADW_BREAKPOINT_BIN (bin), breakpoint); ``` The bin has a single label inside it, displaying "Wide". When the bin's width is smaller than or equal to 200px, it changes to "Narrow". ## `AdwBreakpointBin` as `GtkBuildable` `AdwBreakpointBin` allows adding `AdwBreakpoint` objects as children. Example of an `AdwBreakpointBin` UI definition: ```xml <object class="AdwBreakpointBin"> <property name="width-request">150</property> <property name="height-request">150</property> <property name="child"> <object class="GtkLabel" id="child"> <property name="label">Wide</property> <property name="ellipsize">end</property> <style> <class name="title-1"/> </style> </object> </property> <child> <object class="AdwBreakpoint"> <condition>max-width: 200px</condition> <setter object="child" property="label">Narrow</setter> </object> </child> </object> ``` See [class@Breakpoint] documentation for details. Creates a new `AdwBreakpointBin`. the newly created `AdwBreakpointBin` Adds @breakpoint to @self. a breakpoint bin the breakpoint to add Gets the child widget of @self. the child widget of @self a breakpoint bin Gets the current breakpoint. the current breakpoint a breakpoint bin Removes @breakpoint from @self. a breakpoint bin a breakpoint to remove Sets the child widget of @self. a breakpoint bin the child widget The child widget. The current breakpoint. Describes condition for an [class@Breakpoint]. Creates a condition that triggers when @condition_1 and @condition_2 are both true. the newly created condition first condition second condition Creates a condition that triggers on length changes. the newly created condition the length type the length value the length unit Creates a condition that triggers when either @condition_1 or @condition_2 is true. the newly created condition first condition second condition Creates a condition that triggers on ratio changes. The ratio is represented as @width divided by @height. the newly created condition the ratio type ratio width ratio height Copies @self. a copy of @self a breakpoint condition Frees @self. a breakpoint condition Returns a textual representation of @self. The returned string can be parsed by [func@BreakpointCondition.parse]. A newly allocated text string a breakpoint condition Parses a condition from a string. Length conditions are specified as `<type>: <value>[<unit>]`, where: - `<type>` can be `min-width`, `max-width`, `min-height` or `max-height` - `<value>` is a fractional number - `<unit>` can be `px`, `pt` or `sp` If the unit is omitted, `px` is assumed. See [ctor@BreakpointCondition.new_length]. Examples: - `min-width: 500px` - `min-height: 400pt` - `max-width: 100sp` - `max-height: 500` Ratio conditions are specified as `<type>: <width>[/<height>]`, where: - `<type>` can be `min-aspect-ratio` or `max-aspect-ratio` - `<width>` and `<height>` are integer numbers See [ctor@BreakpointCondition.new_ratio]. The ratio is represented as `<width>` divided by `<height>`. If `<height>` is omitted, it's assumed to be 1. Examples: - `min-aspect-ratio: 4/3` - `max-aspect-ratio: 1` The logical operators `and`, `or` can be used to compose a complex condition as follows: - `<condition> and <condition>`: the condition is true when both `<condition>`s are true, same as when using [ctor@BreakpointCondition.new_and] - `<condition> or <condition>`: the condition is true when either of the `<condition>`s is true, same as when using [ctor@BreakpointCondition.new_or] Examples: - `min-width: 400px and max-aspect-ratio: 4/3` - `max-width: 360sp or max-width: 360px` Conditions can be further nested using parentheses, for example: - `min-width: 400px and (max-aspect-ratio: 4/3 or max-height: 400px)` If parentheses are omitted, the first operator takes priority. the parsed condition the string specifying the condition Describes length types for [struct@BreakpointCondition]. See [ctor@BreakpointCondition.new_length]. New values may be added to this enumeration over time. true if the width is greater than or equal to the condition value true if the width is less than or equal to the condition value true if the height is greater than or equal to the condition value true if the height is less than or equal to the condition value Describes ratio types for [struct@BreakpointCondition]. See [ctor@BreakpointCondition.new_ratio]. New values may be added to this enumeration over time. true if the aspect ratio is greater than or equal to the condition value true if the aspect ratio is less than or equal to the condition value A helper widget for creating buttons. <picture> <source srcset="button-content-dark.png" media="(prefers-color-scheme: dark)"> <img src="button-content.png" alt="button-content"> </picture> `AdwButtonContent` is a box-like widget with an icon and a label. It's intended to be used as a direct child of [class@Gtk.Button], [class@Gtk.MenuButton] or [class@SplitButton], when they need to have both an icon and a label, as follows: ```xml <object class="GtkButton"> <property name="child"> <object class="AdwButtonContent"> <property name="icon-name">document-open-symbolic</property> <property name="label" translatable="yes">_Open</property> <property name="use-underline">True</property> </object> </property> </object> ``` `AdwButtonContent` handles style classes and connecting the mnemonic to the button automatically. ## CSS nodes ``` buttoncontent ╰── box ├── image ╰── label ``` `AdwButtonContent`'s CSS node is called `buttoncontent`. It contains a `box` subnode that serves as a container for the `image` and `label` nodes. When inside a `GtkButton` or `AdwSplitButton`, the button will receive the `.image-text-button` style class. When inside a `GtkMenuButton`, the internal `GtkButton` will receive it instead. ## Accessibility `AdwButtonContent` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. Creates a new `AdwButtonContent`. the new created `AdwButtonContent` gets whether the button can be smaller than the natural size of its contents. whether the button can shrink a button content Gets the name of the displayed icon. the icon name a button content Gets the displayed label. the label a button content Gets whether an underline in the text indicates a mnemonic. whether an underline in the text indicates a mnemonic a button content Sets whether the button can be smaller than the natural size of its contents. If set to `TRUE`, the label will ellipsize. See [method@Gtk.Button.set_can_shrink]. a button content whether the button can shrink Sets the name of the displayed icon. If empty, the icon is not shown. a button content the new icon name Sets the displayed label. a button content the new label Sets whether an underline in the text indicates a mnemonic. The mnemonic can be used to activate the parent button. See [property@ButtonContent:label]. a button content whether an underline in the text indicates a mnemonic Whether the button can be smaller than the natural size of its contents. If set to `TRUE`, the label will ellipsize. See [property@Gtk.Button:can-shrink]. The name of the displayed icon. If empty, the icon is not shown. The displayed label. Whether an underline in the text indicates a mnemonic. The mnemonic can be used to activate the parent button. See [property@ButtonContent:label]. A [class@Gtk.ListBoxRow] that looks like a button. <picture> <source srcset="button-rows-dark.png" media="(prefers-color-scheme: dark)"> <img src="button-rows.png" alt="button-rows"> </picture> The `AdwButtonRow` widget has a title and two icons: before and after the title. It is convenient to present actions like "Delete" at the end of a boxed list. `AdwButtonRow` is always activatable. ## CSS nodes `AdwButtonRow` has a main CSS node with name `row` and the style class `.button`. It contains the subnode `box` for its main horizontal box, which contains the nodes: `image.icon.start` for the start icon, `label.title` for the title, and `image.icon.end` for the end icon. `AdwButtonRow` can have the [`.suggested-action`](style-classes.html#suggested-action) or [`.destructive-action`](style-classes.html#destructive-action) style classes. Creates a new `AdwButtonRow`. the newly created `AdwButtonRow` Gets the end icon name for @self. the end icon name for @self a button row Gets the start icon name for @self. the start icon name for @self a button row Sets the end icon name for @self. a button row the end icon name Sets the start icon name for @self. a button row the start icon name The icon name to show after the title. The icon name to show before the title. This signal is emitted after the row has been activated. Compile-time version checking. Evaluates to `TRUE` if the version of Adwaita is greater than the required one. required major version required minor version required micro version An [class@AnimationTarget] that calls a given callback during the animation. Creates a new `AdwAnimationTarget` that calls the given @callback during the animation. the newly created callback target the callback to call the data to be passed to @callback the function to be called when the callback action is finalized A paginated scrolling widget. <picture> <source srcset="carousel-dark.png" media="(prefers-color-scheme: dark)"> <img src="carousel.png" alt="carousel"> </picture> The `AdwCarousel` widget can be used to display a set of pages with swipe-based navigation between them. [class@CarouselIndicatorDots] and [class@CarouselIndicatorLines] can be used to provide page indicators for `AdwCarousel`. ## CSS nodes `AdwCarousel` has a single CSS node with name `carousel`. Creates a new `AdwCarousel`. the newly created `AdwCarousel` Appends @child to @self. a carousel a widget to add Gets whether to allow swiping for more than one page at a time. `TRUE` if long swipes are allowed a carousel Sets whether @self can be dragged with mouse pointer. whether @self can be dragged with mouse pointer a carousel Gets whether @self will respond to scroll wheel events. `TRUE` if @self will respond to scroll wheel events a carousel Gets whether @self can be navigated. whether @self can be navigated a carousel Gets the number of pages in @self. the number of pages in @self a carousel Gets the page at position @n. the page a carousel index of the page Gets current scroll position in @self, unitless. 1 matches 1 page. Use [method@Carousel.scroll_to] for changing it. the scroll position a carousel Gets the page reveal duration, in milliseconds. the duration a carousel Gets the scroll animation spring parameters for @self. the animation parameters a carousel Gets spacing between pages in pixels. spacing between pages a carousel Inserts @child into @self at position @position. If position is -1, or larger than the number of pages, @child will be appended to the end. a carousel a widget to add the position to insert @child at Prepends @child to @self. a carousel a widget to add Removes @child from @self. a carousel a widget to remove Moves @child into position @position. If position is -1, or larger than the number of pages, @child will be moved at the end. a carousel a widget to add the position to move @child to Scrolls to @widget. If @animate is `TRUE`, the transition will be animated. a carousel a child of @self whether to animate the transition Sets whether to allow swiping for more than one page at a time. If @allow_long_swipes is `FALSE`, each swipe can only move to the adjacent pages. a carousel whether to allow long swipes Sets whether @self can be dragged with mouse pointer. If @allow_mouse_drag is `FALSE`, dragging is only available on touch. a carousel whether @self can be dragged with mouse pointer Sets whether @self will respond to scroll wheel events. If @allow_scroll_wheel is `FALSE`, wheel events will be ignored. a carousel whether @self will respond to scroll wheel events Sets whether @self can be navigated. This can be used to temporarily disable the carousel to only allow navigating it in a certain state. a carousel whether @self can be navigated Sets the page reveal duration, in milliseconds. Reveal duration is used when animating adding or removing pages. a carousel the new reveal duration value Sets the scroll animation spring parameters for @self. The default value is equivalent to: ```c adw_spring_params_new (1, 0.5, 500) ``` a carousel the new parameters Sets spacing between pages in pixels. a carousel the new spacing value Whether to allow swiping for more than one page at a time. If the value is `FALSE`, each swipe can only move to the adjacent pages. Sets whether the `AdwCarousel` can be dragged with mouse pointer. If the value is `FALSE`, dragging is only available on touch. Whether the widget will respond to scroll wheel events. If the value is `FALSE`, wheel events will be ignored. Whether the carousel can be navigated. This can be used to temporarily disable the carousel to only allow navigating it in a certain state. The number of pages in a `AdwCarousel`. Current scrolling position, unitless. 1 matches 1 page. Use [method@Carousel.scroll_to] for changing it. Page reveal duration, in milliseconds. Reveal duration is used when animating adding or removing pages. Scroll animation spring parameters. The default value is equivalent to: ```c adw_spring_params_new (1, 0.5, 500) ``` Spacing between pages in pixels. This signal is emitted after a page has been changed. It can be used to implement "infinite scrolling" by amending the pages after every scroll. ::: note An empty carousel is indicated by `(int)index == -1`. current page A dots indicator for [class@Carousel]. <picture> <source srcset="carousel-indicator-dots-dark.png" media="(prefers-color-scheme: dark)"> <img src="carousel-indicator-dots.png" alt="carousel-indicator-dots"> </picture> The `AdwCarouselIndicatorDots` widget shows a set of dots for each page of a given [class@Carousel]. The dot representing the carousel's active page is larger and more opaque than the others, the transition to the active and inactive state is gradual to match the carousel's position. See also [class@CarouselIndicatorLines]. ## CSS nodes `AdwCarouselIndicatorDots` has a single CSS node with name `carouselindicatordots`. Creates a new `AdwCarouselIndicatorDots`. the newly created `AdwCarouselIndicatorDots` Gets the displayed carousel. the displayed carousel an indicator Sets the displayed carousel. an indicator a carousel The displayed carousel. A lines indicator for [class@Carousel]. <picture> <source srcset="carousel-indicator-dots-lines.png" media="(prefers-color-scheme: dark)"> <img src="carousel-indicator-lines.png" alt="carousel-indicator-lines"> </picture> The `AdwCarouselIndicatorLines` widget shows a set of lines for each page of a given [class@Carousel]. The carousel's active page is shown as another line that moves between them to match the carousel's position. See also [class@CarouselIndicatorDots]. ## CSS nodes `AdwCarouselIndicatorLines` has a single CSS node with name `carouselindicatorlines`. Creates a new `AdwCarouselIndicatorLines`. the newly created `AdwCarouselIndicatorLines` Gets the displayed carousel. the displayed carousel an indicator Sets the displayed carousel. an indicator a carousel The displayed carousel. Describes title centering behavior of a [class@HeaderBar] widget. Keep the title centered when possible Keep the title centered at all cost A widget constraining its child to a given size. <picture> <source srcset="clamp-wide-dark.png" media="(prefers-color-scheme: dark)"> <img src="clamp-wide.png" alt="clamp-wide"> </picture> <picture> <source srcset="clamp-narrow-dark.png" media="(prefers-color-scheme: dark)"> <img src="clamp-narrow.png" alt="clamp-narrow"> </picture> The `AdwClamp` widget constrains the size of the widget it contains to a given maximum size. It will constrain the width if it is horizontal, or the height if it is vertical. The expansion of the child from its minimum to its maximum size is eased out for a smooth transition. If the child requires more than the requested maximum size, it will be allocated the minimum size it can fit in instead. `AdwClamp` can scale with the text scale factor, use the [property@ClampLayout:unit] property to enable that behavior. ## CSS nodes `AdwClamp` has a single CSS node with name `clamp`. Creates a new `AdwClamp`. the newly created `AdwClamp` Gets the child widget of @self. the child widget of @self a clamp Gets the maximum size allocated to the child. the maximum size to allocate to the child a clamp Gets the size above which the child is clamped. the size above which the child is clamped a clamp Gets the length unit for maximum size and tightening threshold. the length unit a clamp Sets the child widget of @self. a clamp the child widget Sets the maximum size allocated to the child. It is the width if the clamp is horizontal, or the height if it is vertical. a clamp the maximum size Sets the size above which the child is clamped. Starting from this size, the clamp will tighten its grip on the child, slowly allocating less and less of the available size up to the maximum allocated size. Below that threshold and below the maximum size, the child will be allocated all the available size. If the threshold is greater than the maximum size to allocate to the child, the child will be allocated all the size up to the maximum. If the threshold is lower than the minimum size to allocate to the child, that size will be used as the tightening threshold. Effectively, tightening the grip on the child before it reaches its maximum size makes transitions to and from the maximum size smoother when resizing. a clamp the tightening threshold Sets the length unit for maximum size and tightening threshold. Allows the sizes to vary depending on the text scale factor. a clamp the length unit The child widget of the `AdwClamp`. The maximum size allocated to the child. It is the width if the clamp is horizontal, or the height if it is vertical. The size above which the child is clamped. Starting from this size, the clamp will tighten its grip on the child, slowly allocating less and less of the available size up to the maximum allocated size. Below that threshold and below the maximum size, the child will be allocated all the available size. If the threshold is greater than the maximum size to allocate to the child, the child will be allocated all the size up to the maximum. If the threshold is lower than the minimum size to allocate to the child, that size will be used as the tightening threshold. Effectively, tightening the grip on the child before it reaches its maximum size makes transitions to and from the maximum size smoother when resizing. The length unit for maximum size and tightening threshold. Allows the sizes to vary depending on the text scale factor. A layout manager constraining its children to a given size. <picture> <source srcset="clamp-wide-dark.png" media="(prefers-color-scheme: dark)"> <img src="clamp-wide.png" alt="clamp-wide"> </picture> <picture> <source srcset="clamp-narrow-dark.png" media="(prefers-color-scheme: dark)"> <img src="clamp-narrow.png" alt="clamp-narrow"> </picture> `AdwClampLayout` constraints the size of the widgets it contains to a given maximum size. It will constrain the width if it is horizontal, or the height if it is vertical. The expansion of the children from their minimum to their maximum size is eased out for a smooth transition. If a child requires more than the requested maximum size, it will be allocated the minimum size it can fit in instead. `AdwClampLayout` can scale with the text scale factor, use the [property@ClampLayout:unit] property to enable that behavior. Creates a new `AdwClampLayout`. the newly created `AdwClampLayout` Gets the maximum size allocated to the children. the maximum size to allocate to the children a clamp layout Gets the size above which the children are clamped. the size above which the children are clamped a clamp layout Gets the length unit for maximum size and tightening threshold. the length unit a clamp layout Sets the maximum size allocated to the children. It is the width if the layout is horizontal, or the height if it is vertical. a clamp layout the maximum size Sets the size above which the children are clamped. Starting from this size, the layout will tighten its grip on the children, slowly allocating less and less of the available size up to the maximum allocated size. Below that threshold and below the maximum size, the children will be allocated all the available size. If the threshold is greater than the maximum size to allocate to the children, they will be allocated the whole size up to the maximum. If the threshold is lower than the minimum size to allocate to the children, that size will be used as the tightening threshold. Effectively, tightening the grip on a child before it reaches its maximum size makes transitions to and from the maximum size smoother when resizing. a clamp layout the tightening threshold Sets the length unit for maximum size and tightening threshold. Allows the sizes to vary depending on the text scale factor. a clamp layout the length unit The maximum size to allocate to the children. It is the width if the layout is horizontal, or the height if it is vertical. The size above which the children are clamped. Starting from this size, the layout will tighten its grip on the children, slowly allocating less and less of the available size up to the maximum allocated size. Below that threshold and below the maximum size, the children will be allocated all the available size. If the threshold is greater than the maximum size to allocate to the children, they will be allocated the whole size up to the maximum. If the threshold is lower than the minimum size to allocate to the children, that size will be used as the tightening threshold. Effectively, tightening the grip on a child before it reaches its maximum size makes transitions to and from the maximum size smoother when resizing. The length unit for maximum size and tightening threshold. Allows the sizes to vary depending on the text scale factor. A scrollable [class@Clamp]. `AdwClampScrollable` is a variant of [class@Clamp] that implements the [iface@Gtk.Scrollable] interface. The primary use case for `AdwClampScrollable` is clamping [class@Gtk.ListView]. Creates a new `AdwClampScrollable`. the newly created `AdwClampScrollable` Gets the child widget of @self. the child widget of @self a clamp scrollable Gets the maximum size allocated to the child. the maximum size to allocate to the child a clamp scrollable Gets the size above which the child is clamped. the size above which the child is clamped a clamp scrollable Gets the length unit for maximum size and tightening threshold. the length unit a clamp scrollable Sets the child widget of @self. a clamp scrollable the child widget Sets the maximum size allocated to the child. It is the width if the clamp is horizontal, or the height if it is vertical. a clamp scrollable the maximum size Sets the size above which the child is clamped. Starting from this size, the clamp will tighten its grip on the child, slowly allocating less and less of the available size up to the maximum allocated size. Below that threshold and below the maximum width, the child will be allocated all the available size. If the threshold is greater than the maximum size to allocate to the child, the child will be allocated all the width up to the maximum. If the threshold is lower than the minimum size to allocate to the child, that size will be used as the tightening threshold. Effectively, tightening the grip on the child before it reaches its maximum size makes transitions to and from the maximum size smoother when resizing. a clamp scrollable the tightening threshold Sets the length unit for maximum size and tightening threshold. Allows the sizes to vary depending on the text scale factor. a clamp the length unit The child widget of the `AdwClampScrollable`. The maximum size allocated to the child. It is the width if the clamp is horizontal, or the height if it is vertical. The size above which the child is clamped. Starting from this size, the clamp will tighten its grip on the child, slowly allocating less and less of the available size up to the maximum allocated size. Below that threshold and below the maximum width, the child will be allocated all the available size. If the threshold is greater than the maximum size to allocate to the child, the child will be allocated all the width up to the maximum. If the threshold is lower than the minimum size to allocate to the child, that size will be used as the tightening threshold. Effectively, tightening the grip on the child before it reaches its maximum size makes transitions to and from the maximum size smoother when resizing. The length unit for maximum size and tightening threshold. Allows the sizes to vary depending on the text scale factor. Application color schemes for [property@StyleManager:color-scheme]. Inherit the parent color-scheme. When set on the `AdwStyleManager` returned by [func@StyleManager.get_default], it's equivalent to `ADW_COLOR_SCHEME_PREFER_LIGHT`. Always use light appearance. Use light appearance unless the system prefers dark colors. Use dark appearance unless the system prefers prefers light colors. Always use dark appearance. A [class@Gtk.ListBoxRow] used to choose from a list of items. <picture> <source srcset="combo-row-dark.png" media="(prefers-color-scheme: dark)"> <img src="combo-row.png" alt="combo-row"> </picture> The `AdwComboRow` widget allows the user to choose from a list of valid choices. The row displays the selected choice. When activated, the row displays a popover which allows the user to make a new choice. Example of an `AdwComboRow` UI definition: ```xml <object class="AdwComboRow"> <property name="title" translatable="yes">Combo Row</property> <property name="model"> <object class="GtkStringList"> <items> <item translatable="yes">Foo</item> <item translatable="yes">Bar</item> <item translatable="yes">Baz</item> </items> </object> </property> </object> ``` The [property@ComboRow:selected] and [property@ComboRow:selected-item] properties can be used to keep track of the selected item and react to their changes. `AdwComboRow` mirrors [class@Gtk.DropDown], see that widget for details. `AdwComboRow` is [property@Gtk.ListBoxRow:activatable] if a model is set. ## CSS nodes `AdwComboRow` has a main CSS node with name `row` and the `.combo` style class. Its popover has the node named `popover` with the `.menu` style class, it contains a [class@Gtk.ScrolledWindow], which in turn contains a [class@Gtk.ListView], both are accessible via their regular nodes. ## Accessibility `AdwComboRow` uses the `GTK_ACCESSIBLE_ROLE_COMBO_BOX` role. Creates a new `AdwComboRow`. the newly created `AdwComboRow` Gets whether search is enabled. If set to `TRUE`, a search entry will be shown in the popup that allows to search for items in the list. Search requires [property@ComboRow:expression] to be set. whether the popup includes a search entry a combo row Gets the expression used to obtain strings from items. the expression used to obtain strings from items a combo row Gets the factory for populating list items. the factory in use a combo row Gets the factory that's currently used to create header widgets for the popup. The factory in use a combo row Gets the factory for populating list items in the popup. the factory in use a combo row Gets the model that provides the displayed items. The model in use a combo row Returns the match mode that the search filter is using. the match mode of the search filter a combo row Gets the position of the selected item. the position of the selected item, or [const@Gtk.INVALID_LIST_POSITION] if no item is selected a combo row Gets the selected item. the selected item a combo row Gets whether to use the current value as the subtitle. whether to use the current value as the subtitle a combo row Sets whether to enable search. If set to `TRUE`, a search entry will be shown in the popup that allows to search for items in the list. Search requires [property@ComboRow:expression] to be set. a combo row whether to enable search Sets the expression used to obtain strings from items. The expression must have a value type of `G_TYPE_STRING`. It's used to bind strings to labels produced by the default factory if [property@ComboRow:factory] is not set, or when [property@ComboRow:use-subtitle] is set to `TRUE`. a combo row an expression Sets the factory for populating list items. This factory is always used for the item in the row. It is also used for items in the popup unless [property@ComboRow:list-factory] is set. a combo row the factory to use Sets the factory to use for creating header widgets for the popup. a combo row the factory to use Sets the factory for populating list items in the popup. If this is not set, [property@ComboRow:factory] is used. a combo row the factory to use Sets the model that provides the displayed items. a combo row the model to use Sets the match mode for the search filter. a combo row the new match mode Selects the item at the given position. a combo row the position of the item to select, or [const@Gtk.INVALID_LIST_POSITION] Sets whether to use the current value as the subtitle. If you use a custom list item factory, you will need to give the row a name conversion expression with [property@ComboRow:expression]. If set to `TRUE`, you should not access [property@ActionRow:subtitle]. The subtitle is interpreted as Pango markup if [property@PreferencesRow:use-markup] is set to `TRUE`. a combo row whether to use the current value as the subtitle Whether to show a search entry in the popup. If set to `TRUE`, a search entry will be shown in the popup that allows to search for items in the list. Search requires [property@ComboRow:expression] to be set. An expression used to obtain strings from items. The expression must have a value type of `G_TYPE_STRING`. It's used to bind strings to labels produced by the default factory if [property@ComboRow:factory] is not set, or when [property@ComboRow:use-subtitle] is set to `TRUE`. Factory for populating list items. This factory is always used for the item in the row. It is also used for items in the popup unless [property@ComboRow:list-factory] is set. The factory for creating header widgets for the popup. The factory for populating list items in the popup. If this is not set, [property@ComboRow:factory] is used. The model that provides 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 [const@Gtk.INVALID_LIST_POSITION] The selected item. Whether to use the current value as the subtitle. If you use a custom list item factory, you will need to give the row a name conversion expression with [property@ComboRow:expression]. If set to `TRUE`, you should not access [property@ActionRow:subtitle]. The subtitle is interpreted as Pango markup if [property@PreferencesRow:use-markup] is set to `TRUE`. The parent class Indicates an [class@Animation] with an infinite duration. This value is mostly used internally. An adaptive dialog container. <picture> <source srcset="dialog-floating-dark.png" media="(prefers-color-scheme: dark)"> <img src="dialog-floating.png" alt="dialog-floating"> </picture> <picture> <source srcset="dialog-bottom-dark.png" media="(prefers-color-scheme: dark)"> <img src="dialog-bottom.png" alt="dialog-bottom"> </picture> `AdwDialog` is similar to a window, but is shown within another window. It can be used with [class@Window] and [class@ApplicationWindow], use [method@Dialog.present] to show it. `AdwDialog` is not resizable. Use the [property@Dialog:content-width] and [property@Dialog:content-height] properties to set its size, or set [property@Dialog:follows-content-size] to `TRUE` to make the dialog track the content's size as it changes. `AdwDialog` can never be larger than its parent window. `AdwDialog` can be presented as a centered floating window or a bottom sheet. By default it's automatic depending on the available size. [property@Dialog:presentation-mode] can be used to change that. `AdwDialog` can be closed via [method@Dialog.close]. When presented as a bottom sheet, `AdwDialog` can also be closed via swiping it down. The [property@Dialog:can-close] can be used to prevent closing. In that case, [signal@Dialog::close-attempt] gets emitted instead. Use [method@Dialog.force_close] to close the dialog even when `can-close` is set to `FALSE`. `AdwDialog` is transient and doesn't integrate with the window below it, for example it's not possible to collapse it into a bottom bar. See [class@BottomSheet] for persistent and more tightly integrated bottom sheets. ## Header Bar Integration When placed inside an `AdwDialog`, [class@HeaderBar] will display the dialog title instead of window title. It will also adjust the decoration layout to ensure it always has a close button and nothing else. Set [property@HeaderBar:show-start-title-buttons] and [property@HeaderBar:show-end-title-buttons] to `FALSE` to remove it if it's unwanted. ## Breakpoints `AdwDialog` can be used with [class@Breakpoint] the same way as [class@BreakpointBin]. Refer to that widget's documentation for details. Like `AdwBreakpointBin`, if breakpoints are used, `AdwDialog` doesn't have a minimum size, and [property@Gtk.Widget:width-request] and [property@Gtk.Widget:height-request] properties must be set manually. Creates a new `AdwDialog`. the new created `AdwDialog` Adds @breakpoint to @self. a dialog the breakpoint to add Attempts to close @self. If the [property@Dialog:can-close] property is set to `FALSE`, the [signal@Dialog::close-attempt] signal is emitted. See also: [method@Dialog.force_close]. whether @self was successfully closed a dialog Closes @self. Unlike [method@Dialog.close], it succeeds even if [property@Dialog:can-close] is set to `FALSE`. a dialog Gets whether @self can be closed. whether the dialog can be closed a dialog Gets the child widget of @self. the child widget of @self a dialog Gets the height of the dialog's contents. the content height a dialog Gets the width of the dialog's contents. the content width a dialog Gets the current breakpoint. the current breakpoint a dialog Gets the default widget for @self. the default widget a dialog Gets the focus widget for @self. the focus widget a dialog Gets whether to size content of @self automatically. whether to size content automatically a dialog Gets presentation mode for @self. the presentation mode a dialog Gets the title of @self. the title a dialog Presents @self within @parent's window. If @self is already shown, raises it to the top instead. If the window is an [class@Window] or [class@ApplicationWindow], the dialog will be shown within it. Otherwise, it will be a separate window. a dialog a widget within the toplevel Sets whether @self can be closed. If set to `FALSE`, the close button, shortcuts and [method@Dialog.close] will result in [signal@Dialog::close-attempt] being emitted instead, and bottom sheet close swipe will be disabled. [method@Dialog.force_close] still works. a dialog whether to allow closing Sets the child widget of @self. a dialog the child widget Sets the height of the dialog's contents. Set it to -1 to reset it to the content's natural height. See also: [property@Gtk.Window:default-height] a dialog the content height Sets the width of the dialog's contents. Set it to -1 to reset it to the content's natural width. See also: [property@Gtk.Window:default-width] a dialog the content width Sets the default widget for @self. It's activated when the user presses Enter. a dialog the default widget Sets the focus widget for @self. If @focus is not the current focus widget, and is focusable, sets it as the focus widget for the dialog. If focus is `NULL`, unsets the focus widget for this dialog. To set the focus to a particular widget in the dialog, it is usually more convenient to use [method@Gtk.Widget.grab_focus] instead of this function. a dialog the focus widget Sets whether to size content of @self automatically. If set to `TRUE`, always use the content's natural size instead of [property@Dialog:content-width] and [property@Dialog:content-height]. If the content resizes, the dialog will immediately resize as well. See also: [property@Gtk.Window:resizable] a dialog whether to size content automatically Sets presentation mode for @self. When set to `ADW_DIALOG_AUTO`, the dialog appears as a bottom sheet when the following condition is met: `max-width: 450px or max-height: 360px`, and as a floating window otherwise. Set it to `ADW_DIALOG_FLOATING` or `ADW_DIALOG_BOTTOM_SHEET` to always present it a floating window or a bottom sheet respectively, regardless of available size. Presentation mode does nothing for dialogs presented as a window. a dialog the new presentation mode Sets the title of @self. a dialog the new title Whether the dialog can be closed. If set to `FALSE`, the close button, shortcuts and [method@Dialog.close] will result in [signal@Dialog::close-attempt] being emitted instead, and bottom sheet close swipe will be disabled. [method@Dialog.force_close] still works. The child widget of the `AdwDialog`. The height of the dialog's contents. Set it to -1 to reset it to the content's natural height. See also: [property@Gtk.Window:default-height] The width of the dialog's contents. Set it to -1 to reset it to the content's natural width. See also: [property@Gtk.Window:default-width] The current breakpoint. The default widget. It's activated when the user presses Enter. The focus widget. Whether to size content automatically. If set to `TRUE`, always use the content's natural size instead of [property@Dialog:content-width] and [property@Dialog:content-height]. If the content resizes, the dialog will immediately resize as well. See also: [property@Gtk.Window:resizable] The dialog's presentation mode. When set to `ADW_DIALOG_AUTO`, the dialog appears as a bottom sheet when the following condition is met: `max-width: 450px or max-height: 360px`, and as a floating window otherwise. Set it to `ADW_DIALOG_FLOATING` or `ADW_DIALOG_BOTTOM_SHEET` to always present it a floating window or a bottom sheet respectively, regardless of available size. Presentation mode does nothing for dialogs presented as a window. The title of the dialog. Emitted when the close button or shortcut is used, or [method@Dialog.close] is called while [property@Dialog:can-close] is set to `FALSE`. Emitted when the dialog is successfully closed. Describes the available presentation modes for [class@Dialog]. New values may be added to this enumeration over time. See [property@Dialog:presentation-mode]. Switch between `ADW_DIALOG_FLOATING` and `ADW_DIALOG_BOTTOM_SHEET` depending on available size. Present dialog as a centered floating window. Present dialog as a bottom sheet. Describes the available easing functions for use with [class@TimedAnimation]. New values may be added to this enumeration over time. Linear tweening. Quadratic tweening. Quadratic tweening, inverse of `ADW_EASE_IN_QUAD`. Quadratic tweening, combining `ADW_EASE_IN_QUAD` and `ADW_EASE_OUT_QUAD`. Cubic tweening. Cubic tweening, inverse of `ADW_EASE_IN_CUBIC`. Cubic tweening, combining `ADW_EASE_IN_CUBIC` and `ADW_EASE_OUT_CUBIC`. Quartic tweening. Quartic tweening, inverse of `ADW_EASE_IN_QUART`. Quartic tweening, combining `ADW_EASE_IN_QUART` and `ADW_EASE_OUT_QUART`. Quintic tweening. Quintic tweening, inverse of `ADW_EASE_IN_QUINT`. Quintic tweening, combining `ADW_EASE_IN_QUINT` and `ADW_EASE_OUT_QUINT`. Sine wave tweening. Sine wave tweening, inverse of `ADW_EASE_IN_SINE`. Sine wave tweening, combining `ADW_EASE_IN_SINE` and `ADW_EASE_OUT_SINE`. Exponential tweening. Exponential tweening, inverse of `ADW_EASE_IN_EXPO`. Exponential tweening, combining `ADW_EASE_IN_EXPO` and `ADW_EASE_OUT_EXPO`. Circular tweening. Circular tweening, inverse of `ADW_EASE_IN_CIRC`. Circular tweening, combining `ADW_EASE_IN_CIRC` and `ADW_EASE_OUT_CIRC`. Elastic tweening, with offshoot on start. Elastic tweening, with offshoot on end, inverse of `ADW_EASE_IN_ELASTIC`. Elastic tweening, with offshoot on both ends, combining `ADW_EASE_IN_ELASTIC` and `ADW_EASE_OUT_ELASTIC`. Overshooting cubic tweening, with backtracking on start. Overshooting cubic tweening, with backtracking on end, inverse of `ADW_EASE_IN_BACK`. Overshooting cubic tweening, with backtracking on both ends, combining `ADW_EASE_IN_BACK` and `ADW_EASE_OUT_BACK`. Exponentially decaying parabolic (bounce) tweening, on start. Exponentially decaying parabolic (bounce) tweening, with bounce on end, inverse of `ADW_EASE_IN_BOUNCE`. Exponentially decaying parabolic (bounce) tweening, with bounce on both ends, combining `ADW_EASE_IN_BOUNCE` and `ADW_EASE_OUT_BOUNCE`. Computes easing with @easing for @value. @value should generally be in the [0, 1] range. the easing for @value an easing value a value to ease A [class@Gtk.ListBoxRow] with an embedded text entry. <picture> <source srcset="entry-row-dark.png" media="(prefers-color-scheme: dark)"> <img src="entry-row.png" alt="entry-row"> </picture> `AdwEntryRow` has a title that doubles as placeholder text. It shows an icon indicating that it's editable and can receive additional widgets before or after the editable part. If [property@EntryRow:show-apply-button] is set to `TRUE`, `AdwEntryRow` can show an apply button when editing its contents. This can be useful if changing its contents can result in an expensive operation, such as network activity. `AdwEntryRow` provides only minimal API and should be used with the [iface@Gtk.Editable] API. See also [class@PasswordEntryRow]. ## AdwEntryRow as GtkBuildable The `AdwEntryRow` implementation of the [iface@Gtk.Buildable] interface supports adding a child at its end by specifying “suffix” or omitting the “type” attribute of a <child> element. It also supports adding a child as a prefix widget by specifying “prefix” as the “type” attribute of a <child> element. ## CSS nodes `AdwEntryRow` has a single CSS node with name `row` and the `.entry` style class. Creates a new `AdwEntryRow`. the newly created `AdwEntryRow` Adds a prefix widget to @self. an entry row a widget Adds a suffix widget to @self. an entry row a widget Gets whether activating the embedded entry can activate the default widget. whether to activate the default widget an entry row Gets Pango attributes applied to the text of the embedded entry. the list of attributes an entry row Gets whether to suggest emoji replacements on @self. whether or not emoji completion is enabled an entry row Gets the additional input hints of @self. The input hints an entry row Gets the input purpose of @self. the input purpose an entry row Retrieves the maximum length of the entry. The maximum length of the entry. an entry row Gets whether @self can show the apply button. whether to show the apply button an entry row Retrieves the current length of the text in @self. The current number of characters in @self, or 0 if there are none. an entry row Causes @self to have keyboard focus without selecting the text. See [method@Gtk.Text.grab_focus_without_selecting] for more information. whether the focus is now inside @self an entry row Removes a child from @self. an entry row the child to be removed Sets whether activating the embedded entry can activate the default widget. an entry row whether to activate the default widget Sets Pango attributes to apply to the text of the embedded entry. The [struct@Pango.Attribute]'s `start_index` and `end_index` must refer to the [class@Gtk.EntryBuffer] text, i.e. without the preedit string. an entry row a list of attributes Sets whether to suggest emoji replacements on @self. Emoji replacement is done with :-delimited names, like `:heart:`. an entry row Whether emoji completion should be enabled or not Set additional input hints for @self. Input hints allow input methods to fine-tune their behavior. See also: [property@AdwEntryRow:input-purpose] an entry row the hints Sets the input purpose of @self. The input purpose can be used by input methods to adjust their behavior. an entry row the purpose Sets the maximum length of the entry. an entry row maximum length of the entry Sets whether @self can show the apply button. When set to `TRUE`, typing text in the entry will reveal an apply button. Clicking it or pressing the <kbd>Enter</kbd> key will hide the button and emit the [signal@EntryRow::apply] signal. This is useful if changing the entry contents can trigger an expensive operation, e.g. network activity, to avoid triggering it after typing every character. an entry row whether to show the apply button Whether activating the embedded entry can activate the default widget. A list of Pango attributes to apply to the text of the embedded entry. The [struct@Pango.Attribute]'s `start_index` and `end_index` must refer to the [class@Gtk.EntryBuffer] text, i.e. without the preedit string. Whether to suggest emoji replacements on the entry row. Emoji replacement is done with :-delimited names, like `:heart:`. Additional input hints for the entry row. Input hints allow input methods to fine-tune their behavior. See also: [property@Adw.EntryRow:input-purpose] The input purpose of the entry row. The input purpose can be used by input methods to adjust their behavior. Maximum number of characters for the entry. Whether to show the apply button. When set to `TRUE`, typing text in the entry will reveal an apply button. Clicking it or pressing the <kbd>Enter</kbd> key will hide the button and emit the [signal@EntryRow::apply] signal. This is useful if changing the entry contents can trigger an expensive operation, e.g. network activity, to avoid triggering it after typing every character. The length of the text in the entry row. Emitted when the apply button is pressed. See [property@EntryRow:show-apply-button]. Emitted when the embedded entry is activated. The parent class `AdwEnumListItem` is the type of items in a [class@EnumListModel]. Gets the enum value name. the enum value name Gets the enum value nick. the enum value nick Gets the enum value. the enum value The enum value name. The enum value nick. The enum value. A [iface@Gio.ListModel] representing values of a given enum. `AdwEnumListModel` contains objects of type [class@EnumListItem]. Creates a new `AdwEnumListModel` for @enum_type. the newly created `AdwEnumListModel` the type of the enum to construct the model from Finds the position of a given enum value in @self. If the value is not found, `GTK_INVALID_LIST_POSITION` is returned. the position of the value an enum value Gets the type of the enum represented by @self. the enum type The type of the enum represented by the model. A [class@Gtk.ListBoxRow] used to reveal widgets. <picture> <source srcset="expander-row-dark.png" media="(prefers-color-scheme: dark)"> <img src="expander-row.png" alt="expander-row"> </picture> The `AdwExpanderRow` widget allows the user to reveal or hide widgets below it. It also allows the user to enable the expansion of the row, allowing to disable all that the row contains. ## AdwExpanderRow as GtkBuildable The `AdwExpanderRow` implementation of the [iface@Gtk.Buildable] interface supports adding a child as an suffix widget by specifying “suffix” as the “type” attribute of a <child> element. It also supports adding it as a prefix widget by specifying “prefix” as the “type” attribute of a <child> element. ## CSS nodes `AdwExpanderRow` has a main CSS node with name `row` and the `.expander` style class. It has the `.empty` style class when it contains no children. It contains the subnodes `row.header` for its main embedded row, `list.nested` for the list it can expand, and `image.expander-row-arrow` for its arrow. Creates a new `AdwExpanderRow`. the newly created `AdwExpanderRow` Adds an action widget to @self. Use [method@ExpanderRow.add_suffix] to add a suffix. an expander row a widget Adds a prefix widget to @self. an expander row a widget Adds a widget to @self. The widget will appear in the expanding list below @self. an expander row a widget Adds an suffix widget to @self. an expander row a widget Gets whether the expansion of @self is enabled. whether the expansion of @self is enabled. an expander row Gets whether @self is expanded. whether @self is expanded an expander row Gets the icon name for @self. Use [method@ExpanderRow.add_prefix] to add an icon. the icon name for @self an expander row Gets whether the switch enabling the expansion of @self is visible. whether the switch enabling the expansion is visible an expander row Gets the subtitle for @self. the subtitle for @self an expander row Gets the number of lines at the end of which the subtitle label will be ellipsized. the number of lines at the end of which the subtitle label will be ellipsized an expander row Gets the number of lines at the end of which the title label will be ellipsized. the number of lines at the end of which the title label will be ellipsized an expander row Removes a child from @self. an expander row the child to be removed Sets whether the expansion of @self is enabled. an expander row whether to enable the expansion Sets whether @self is expanded. an expander row whether to expand the row Sets the icon name for @self. Use [method@ExpanderRow.add_prefix] to add an icon. an expander row the icon name Sets whether the switch enabling the expansion of @self is visible. an expander row whether to show the switch enabling the expansion Sets the subtitle for @self. The subtitle is interpreted as Pango markup unless [property@PreferencesRow:use-markup] is set to `FALSE`. an expander row the subtitle Sets the number of lines at the end of which the subtitle label will be ellipsized. If the value is 0, the number of lines won't be limited. an expander row the number of lines at the end of which the subtitle label will be ellipsized Sets the number of lines at the end of which the title label will be ellipsized. If the value is 0, the number of lines won't be limited. an expander row the number of lines at the end of which the title label will be ellipsized Whether expansion is enabled. Whether the row is expanded. The icon name for this row. Use [method@ExpanderRow.add_prefix] to add an icon. Whether the switch enabling the expansion is visible. The subtitle for this row. The subtitle is interpreted as Pango markup unless [property@PreferencesRow:use-markup] is set to `FALSE`. The number of lines at the end of which the subtitle label will be ellipsized. If the value is 0, the number of lines won't be limited. The number of lines at the end of which the title label will be ellipsized. If the value is 0, the number of lines won't be limited. The parent class An adaptive container acting like a box or an overlay. <picture> <source srcset="flap-wide-dark.png" media="(prefers-color-scheme: dark)"> <img src="flap-wide.png" alt="flap-wide"> </picture> <picture> <source srcset="flap-narrow-dark.png" media="(prefers-color-scheme: dark)"> <img src="flap-narrow.png" alt="flap-narrow"> </picture> The `AdwFlap` widget can display its children like a [class@Gtk.Box] does or like a [class@Gtk.Overlay] does, according to the [property@Flap:fold-policy] value. `AdwFlap` has at most three children: [property@Flap:content], [property@Flap:flap] and [property@Flap:separator]. Content is the primary child, flap is displayed next to it when unfolded, or overlays it when folded. Flap can be shown or hidden by changing the [property@Flap:reveal-flap] value, as well as via swipe gestures if [property@Flap:swipe-to-open] and/or [property@Flap:swipe-to-close] are set to `TRUE`. Optionally, a separator can be provided, which would be displayed between the content and the flap when there's no shadow to separate them, depending on the transition type. [property@Flap:flap] is transparent by default; add the [`.background`](style-classes.html#background) style class to it if this is unwanted. If [property@Flap:modal] is set to `TRUE`, content becomes completely inaccessible when the flap is revealed while folded. The position of the flap and separator children relative to the content is determined by orientation, as well as the [property@Flap:flap-position] value. Folding the flap will automatically hide the flap widget, and unfolding it will automatically reveal it. If this behavior is not desired, the [property@Flap:locked] property can be used to override it. Common use cases include sidebars, header bars that need to be able to overlap the window content (for example, in fullscreen mode) and bottom sheets. ## AdwFlap as GtkBuildable The `AdwFlap` implementation of the [iface@Gtk.Buildable] interface supports setting the flap child by specifying “flap” as the “type” attribute of a `<child>` element, and separator by specifying “separator”. Specifying “content” child type or omitting it results in setting the content child. ## CSS nodes `AdwFlap` has a single CSS node with name `flap`. The node will get the style classes `.folded` when it is folded, and `.unfolded` when it's not. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) Creates a new `AdwFlap`. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) the newly created `AdwFlap` Gets the content widget for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) the content widget for @self a flap Gets the flap widget for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) the flap widget for @self a flap Gets the flap position for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) the flap position for @self a flap Gets the fold transition animation duration for @self, in milliseconds. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) the fold transition duration a flap Gets the fold policy for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) the fold policy for @self a flap Gets the fold threshold policy for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) the fold threshold policy a flap Gets whether @self is currently folded. See [property@Flap:fold-policy]. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) `TRUE` if @self is currently folded a flap Gets whether @self is locked. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) `TRUE` if @self is locked a flap Gets whether @self is modal. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) `TRUE` if @self is modal a flap Gets whether the flap widget is revealed for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) `TRUE` if the flap widget is revealed a flap Gets the reveal animation spring parameters for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) the reveal animation parameters a flap Gets the current reveal progress for @self. 0 means fully hidden, 1 means fully revealed. See [property@Flap:reveal-flap]. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) the current reveal progress for @self a flap Gets the separator widget for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) the separator widget for @self a flap Gets whether @self can be closed with a swipe gesture. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) `TRUE` if @self can be closed with a swipe gesture a flap Gets whether @self can be opened with a swipe gesture. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) `TRUE` if @self can be opened with a swipe gesture a flap Gets the type of animation used for reveal and fold transitions in @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) the current transition type of @self a flap Sets the content widget for @self. It's always displayed when unfolded, and partially visible when folded. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap the content widget Sets the flap widget for @self. It's only visible when [property@Flap:reveal-progress] is greater than 0. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap the flap widget Sets the flap position for @self. If it's set to `GTK_PACK_START`, the flap is displayed before the content, if `GTK_PACK_END`, it's displayed after the content. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap the new value Sets the fold transition animation duration for @self, in milliseconds. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap the new duration, in milliseconds Sets the fold policy for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap the fold policy Sets the fold threshold policy for @self. If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, flap will only fold when the children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it will fold as soon as children don't get their natural size. This can be useful if you have a long ellipsizing label and want to let it ellipsize instead of immediately folding. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap the policy to use Sets whether @self is locked. If `FALSE`, folding when the flap is revealed automatically closes it, and unfolding it when the flap is not revealed opens it. If `TRUE`, [property@Flap:reveal-flap] value never changes on its own. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap the new value Sets whether @self is modal. If `TRUE`, clicking the content widget while flap is revealed, as well as pressing the <kbd>Esc</kbd> key, will close the flap. If `FALSE`, clicks are passed through to the content widget. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap whether @self is modal Sets whether the flap widget is revealed for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap whether to reveal the flap widget Sets the reveal animation spring parameters for @self. The default value is equivalent to: ```c adw_spring_params_new (1, 0.5, 500) ``` See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap the new parameters Sets the separator widget for @self. It's displayed between content and flap when there's no shadow to display. When exactly it's visible depends on the [property@Flap:transition-type] value. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap the separator widget Sets whether @self can be closed with a swipe gesture. The area that can be swiped depends on the [property@Flap:transition-type] value. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap whether @self can be closed with a swipe gesture Sets whether @self can be opened with a swipe gesture. The area that can be swiped depends on the [property@Flap:transition-type] value. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap whether @self can be opened with a swipe gesture Sets the type of animation used for reveal and fold transitions in @self. [property@Flap:flap] is transparent by default, which means the content will be seen through it with `ADW_FLAP_TRANSITION_TYPE_OVER` transitions; add the [`.background`](style-classes.html#background) style class to it if this is unwanted. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) a flap the new transition type The content widget. It's always displayed when unfolded, and partially visible when folded. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) The flap widget. It's only visible when [property@Flap:reveal-progress] is greater than 0. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) The flap position. If it's set to `GTK_PACK_START`, the flap is displayed before the content, if `GTK_PACK_END`, it's displayed after the content. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) The fold transition animation duration, in milliseconds. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) The fold policy for the flap. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) Determines when the flap will fold. If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, flap will only fold when the children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it will fold as soon as children don't get their natural size. This can be useful if you have a long ellipsizing label and want to let it ellipsize instead of immediately folding. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) Whether the flap is currently folded. See [property@Flap:fold-policy]. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) Whether the flap is locked. If `FALSE`, folding when the flap is revealed automatically closes it, and unfolding it when the flap is not revealed opens it. If `TRUE`, [property@Flap:reveal-flap] value never changes on its own. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) Whether the flap is modal. If `TRUE`, clicking the content widget while flap is revealed, as well as pressing the <kbd>Esc</kbd> key, will close the flap. If `FALSE`, clicks are passed through to the content widget. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) Whether the flap widget is revealed. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) The reveal animation spring parameters. The default value is equivalent to: ```c adw_spring_params_new (1, 0.5, 500) ``` See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) The current reveal transition progress. 0 means fully hidden, 1 means fully revealed. See [property@Flap:reveal-flap]. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) The separator widget. It's displayed between content and flap when there's no shadow to display. When exactly it's visible depends on the [property@Flap:transition-type] value. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) Whether the flap can be closed with a swipe gesture. The area that can be swiped depends on the [property@Flap:transition-type] value. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) Whether the flap can be opened with a swipe gesture. The area that can be swiped depends on the [property@Flap:transition-type] value. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) the type of animation used for reveal and fold transitions. [property@Flap:flap] is transparent by default, which means the content will be seen through it with `ADW_FLAP_TRANSITION_TYPE_OVER` transitions; add the [`.background`](style-classes.html#background) style class to it if this is unwanted. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) Describes the possible folding behavior of a [class@Flap] widget. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) Disable folding, the flap cannot reach narrow sizes. Keep the flap always folded. Fold and unfold the flap based on available space. Describes transitions types of a [class@Flap] widget. It determines the type of animation when transitioning between children in a [class@Flap] widget, as well as which areas can be swiped via [property@Flap:swipe-to-open] and [property@Flap:swipe-to-close]. See [the migration guide](migrating-to-breakpoints.html#replace-adwflap) The flap slides over the content, which is dimmed. When folded, only the flap can be swiped. The content slides over the flap. Only the content can be swiped. The flap slides offscreen when hidden, neither the flap nor content overlap each other. Both widgets can be swiped. Determines when [class@Flap] and [class@Leaflet] will fold. Stop using `AdwLeaflet` and `AdwFlap` Folding is based on the minimum size Folding is based on the natural size A title bar widget. <picture> <source srcset="header-bar-dark.png" media="(prefers-color-scheme: dark)"> <img src="header-bar.png" alt="header-bar"> </picture> `AdwHeaderBar` is similar to [class@Gtk.HeaderBar], but provides additional features compared to it. Refer to `GtkHeaderBar` for details. It is typically used as a top bar within [class@ToolbarView]. ## Dialog Integration When placed inside an [class@Dialog], `AdwHeaderBar` will display the dialog title intead of window title. It will also adjust the decoration layout to ensure it always has a close button and nothing else. Set [property@HeaderBar:show-start-title-buttons] and [property@HeaderBar:show-end-title-buttons] to `FALSE` to remove it if it's unwanted. ## Navigation View Integration When placed inside an [class@NavigationPage], `AdwHeaderBar` will display the page title instead of window title. When used together with [class@NavigationView] or [class@NavigationSplitView], it will also display a back button that can be used to go back to the previous page. The button also has a context menu, allowing to pop multiple pages at once, potentially across multiple navigation views. Set [property@HeaderBar:show-back-button] to `FALSE` to disable this behavior in rare scenarios where it's unwanted. ## Split View Integration When placed inside [class@NavigationSplitView] or [class@OverlaySplitView], `AdwHeaderBar` will automatically hide the title buttons other than at the edges of the window. ## Bottom Sheet Integration When played inside [class@BottomSheet], `AdwHeaderBar` will not show the title unless [property@BottomSheet:show-drag-handle] is set to `FALSE`, regardless of [property@HeaderBar:show-title]. This only applies to the default title, titles set with [property@HeaderBar:title-widget] will still be shown. ## Centering Policy [property@HeaderBar:centering-policy] allows to enforce strict centering of the title widget. This can be useful for entries inside [class@Clamp]. ## Title Buttons Unlike `GtkHeaderBar`, `AdwHeaderBar` allows to toggle title button visibility for each side individually, using the [property@HeaderBar:show-start-title-buttons] and [property@HeaderBar:show-end-title-buttons] properties. ## CSS nodes ``` headerbar ╰── windowhandle ╰── box ├── widget │ ╰── box.start │ ├── windowcontrols.start │ ├── widget │ │ ╰── [button.back] │ ╰── [other children] ├── widget │ ╰── [Title Widget] ╰── widget ╰── box.end ├── [other children] ╰── windowcontrols.end ``` `AdwHeaderBar`'s CSS node is called `headerbar`. It contains a `windowhandle` subnode, which contains a `box` subnode, which contains three `widget` subnodes at the start, center and end of the header bar. The start and end subnotes contain a `box` subnode with the `.start` and `.end` style classes respectively, and the center node contains a node that represents the title. Each of the boxes contains a `windowcontrols` subnode, see [class@Gtk.WindowControls] for details, as well as other children. When [property@HeaderBar:show-back-button] is `TRUE`, the start box also contains a node with the name `widget` that contains a node with the name `button` and `.back` style class. ## Accessibility `AdwHeaderBar` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. Creates a new `AdwHeaderBar`. the newly created `AdwHeaderBar`. Gets the policy for aligning the center widget. the centering policy a header bar Gets the decoration layout for @self. the decoration layout a header bar Gets whether @self can show the back button. whether to show the back button a header bar Gets whether to show title buttons at the end of @self. `TRUE` if title buttons at the end are shown a header bar Gets whether to show title buttons at the start of @self. `TRUE` if title buttons at the start are shown a header bar Gets whether the title widget should be shown. whether the title widget should be shown. a header bar Gets the title widget widget of @self. the title widget a header bar Adds @child to @self, packed with reference to the end of @self. a header bar the widget to be added to @self Adds @child to @self, packed with reference to the start of the @self. a header bar the widget to be added to @self Removes a child from @self. The child must have been added with [method@HeaderBar.pack_start], [method@HeaderBar.pack_end] or [property@HeaderBar:title-widget]. a header bar the child to remove Sets the policy for aligning the center widget. a header bar the centering policy Sets the decoration layout for @self. If this property is not set, the [property@Gtk.Settings:gtk-decoration-layout] setting is used. The format of the string is button names, separated by commas. A colon separates the buttons that should appear at the start from those at the end. Recognized button names are minimize, maximize, close and icon (the window icon). For example, “icon:minimize,maximize,close” specifies an icon at the start, and minimize, maximize and close buttons at the end. a header bar a decoration layout Sets whether @self can show the back button. The back button will never be shown unless the header bar is placed inside an [class@NavigationView]. Usually, there is no reason to set it to `FALSE`. a header bar whether to show the back button Sets whether to show title buttons at the end of @self. See [property@HeaderBar:show-start-title-buttons] for the other side. Which buttons are actually shown and where is determined by the [property@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). a header bar `TRUE` to show standard title buttons Sets whether to show title buttons at the start of @self. See [property@HeaderBar:show-end-title-buttons] for the other side. Which buttons are actually shown and where is determined by the [property@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). a header bar `TRUE` to show standard title buttons Sets whether the title widget should be shown. a header bar whether the title widget is visible Sets the title widget for @self. When set to `NULL`, the header bar will display the title of the window it is contained in. To use a different title, use [class@WindowTitle]: ```xml <object class="AdwHeaderBar"> <property name="title-widget"> <object class="AdwWindowTitle"> <property name="title" translatable="yes">Title</property> </object> </property> </object> ``` a header bar a widget to use for a title The policy for aligning the center widget. The decoration layout for buttons. If this property is not set, the [property@Gtk.Settings:gtk-decoration-layout] setting is used. The format of the string is button names, separated by commas. A colon separates the buttons that should appear at the start from those at the end. Recognized button names are minimize, maximize, close and icon (the window icon). For example, “icon:minimize,maximize,close” specifies an icon at the start, and minimize, maximize and close buttons at the end. Whether the header bar can show the back button. The back button will never be shown unless the header bar is placed inside an [class@NavigationView]. Usually, there is no reason to set this to `FALSE`. Whether to show title buttons at the end of the header bar. See [property@HeaderBar:show-start-title-buttons] for the other side. Which buttons are actually shown and where is determined by the [property@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). Whether to show title buttons at the start of the header bar. See [property@HeaderBar:show-end-title-buttons] for the other side. Which buttons are actually shown and where is determined by the [property@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). Whether the title widget should be shown. The title widget to display. When set to `NULL`, the header bar will display the title of the window it is contained in. To use a different title, use [class@WindowTitle]: ```xml <object class="AdwHeaderBar"> <property name="title-widget"> <object class="AdwWindowTitle"> <property name="title" translatable="yes">Title</property> </object> </property> </object> ``` An individual layout in [class@MultiLayoutView]. Creates a new `AdwLayout` that contains @content. a new `AdwLayout` the content widget to use Gets the content widget. The content a layout Gets the name of the layout. the name of the layout a layout Sets the name of the layout. a layout the layout name The content widget. The name of the layout. A child slot within [class@Layout]. See [class@MultiLayoutView]. Creates a new `AdwLayoutSlot` with its ID set to @id. a new `AdwLayoutSlot` the slot ID Gets the slot id of @self. the slot ID a layout slot The slot ID. See [method@MultiLayoutView.set_child]. An adaptive container acting like a box or a stack. <picture> <source srcset="leaflet-wide-dark.png" media="(prefers-color-scheme: dark)"> <img src="leaflet-wide.png" alt="leaflet-wide"> </picture> <picture> <source srcset="leaflet-narrow-dark.png" media="(prefers-color-scheme: dark)"> <img src="leaflet-narrow.png" alt="leaflet-narrow"> </picture> The `AdwLeaflet` widget can display its children like a [class@Gtk.Box] does or like a [class@Gtk.Stack] does, adapting to size changes by switching between the two modes. When there is enough space the children are displayed side by side, otherwise only one is displayed and the leaflet is said to be “folded”. The threshold is dictated by the preferred minimum sizes of the children. When a leaflet is folded, the children can be navigated using swipe gestures. The “over” and “under” transition types stack the children one on top of the other, while the “slide” transition puts the children side by side. While navigating to a child on the side or below can be performed by swiping the current child away, navigating to an upper child requires dragging it from the edge where it resides. This doesn't affect non-dragging swipes. ## CSS nodes `AdwLeaflet` has a single CSS node with name `leaflet`. The node will get the style classes `.folded` when it is folded, `.unfolded` when it's not, or none if it hasn't computed its fold yet. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) Creates a new `AdwLeaflet`. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the new created `AdwLeaflet` Adds a child to @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the [class@LeafletPage] for @child a leaflet the widget to add Finds the previous or next navigatable child. This will be the same child [method@Leaflet.navigate] or swipe gestures will navigate to. If there's no child to navigate to, `NULL` will be returned instead. See [property@LeafletPage:navigatable]. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the previous or next child a leaflet the direction Gets whether gestures and shortcuts for navigating backward are enabled. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) Whether gestures and shortcuts are enabled. a leaflet Gets whether gestures and shortcuts for navigating forward are enabled. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) Whether gestures and shortcuts are enabled. a leaflet Gets whether @self can unfold. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) whether @self can unfold a leaflet Finds the child of @self with @name. Returns `NULL` if there is no child with this name. See [property@LeafletPage:name]. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the requested child of @self a leaflet the name of the child to find Gets the child transition spring parameters for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the child transition parameters a leaflet Gets whether a child transition is currently running for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) whether a transition is currently running a leaflet Gets the fold threshold policy for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the fold threshold policy a leaflet Gets whether @self is folded. The leaflet will be folded if the size allocated to it is smaller than the sum of the minimum or natural sizes of the children (see [property@Leaflet:fold-threshold-policy]), it will be unfolded otherwise. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) whether @self is folded. a leaflet Gets whether @self is homogeneous. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) whether @self is homogeneous a leaflet Gets the mode transition animation duration for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the mode transition duration, in milliseconds. a leaflet Returns the [class@LeafletPage] object for @child. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the page object for @child a leaflet a child of @self Returns a [iface@Gio.ListModel] that contains the pages of the leaflet. 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 change the visible page. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a `GtkSelectionModel` for the leaflet's children a leaflet Gets the type of animation used for transitions between modes and children. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the current transition type of @self a leaflet Gets the widget currently visible when the leaflet is folded. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the visible child a leaflet Gets the name of the currently visible child widget. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the name of the visible child a leaflet Inserts @child in the position after @sibling in the list of children. If @sibling is `NULL`, inserts @child at the first position. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the [class@LeafletPage] for @child a leaflet the widget to insert the sibling after which to insert @child Navigates to the previous or next child. The child must have the [property@LeafletPage:navigatable] property set to `TRUE`, otherwise it will be skipped. This will be the same child as returned by [method@Leaflet.get_adjacent_child] or navigated to via swipe gestures. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) whether the visible child was changed a leaflet the direction Inserts @child at the first position in @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the [class@LeafletPage] for @child a leaflet the widget to prepend Removes a child widget from @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet the child to remove Moves @child to the position after @sibling in the list of children. If @sibling is `NULL`, moves @child to the first position. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet the widget to move, must be a child of @self the sibling to move @child after Sets whether gestures and shortcuts for navigating backward are enabled. The supported gestures are: - One-finger swipe on touchscreens - Horizontal scrolling on touchpads (usually two-finger swipe) - Back/forward mouse buttons The keyboard back/forward keys are also supported, as well as the <kbd>Alt</kbd>+<kbd>←</kbd> shortcut for horizontal orientation, or <kbd>Alt</kbd>+<kbd>↑</kbd> for vertical orientation. If the orientation is horizontal, for right-to-left locales, gestures and shortcuts are reversed. Only children that have [property@LeafletPage:navigatable] set to `TRUE` can be navigated to. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet the new value Sets whether gestures and shortcuts for navigating forward are enabled. The supported gestures are: - One-finger swipe on touchscreens - Horizontal scrolling on touchpads (usually two-finger swipe) - Back/forward mouse buttons The keyboard back/forward keys are also supported, as well as the <kbd>Alt</kbd>+<kbd>→</kbd> shortcut for horizontal orientation, or <kbd>Alt</kbd>+<kbd>↓</kbd> for vertical orientation. If the orientation is horizontal, for right-to-left locales, gestures and shortcuts are reversed. Only children that have [property@LeafletPage:navigatable] set to `TRUE` can be navigated to. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet the new value Sets whether @self can unfold. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet whether @self can unfold Sets the child transition spring parameters for @self. The default value is equivalent to: ```c adw_spring_params_new (1, 0.5, 500) ``` See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet the new parameters Sets the fold threshold policy for @self. If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only fold when the children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it will fold as soon as children don't get their natural size. This can be useful if you have a long ellipsizing label and want to let it ellipsize instead of immediately folding. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet the policy to use Sets @self to be homogeneous or not. If set to `FALSE`, different children can have different size along the opposite orientation. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet whether to make @self homogeneous Sets the mode transition animation duration for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet the new duration, in milliseconds Sets the type of animation used for transitions between modes and children. The transition type can be changed without problems at runtime, so it is possible to change the animation based on the mode or child that is about to become current. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet the new transition type Sets the widget currently visible when the leaflet is folded. The transition is determined by [property@Leaflet:transition-type] and [property@Leaflet:child-transition-params]. The transition can be cancelled by the user, in which case visible child will change back to the previously visible child. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet the new child Makes the child with the name @name visible. See [property@Leaflet:visible-child]. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet the name of a child Whether gestures and shortcuts for navigating backward are enabled. The supported gestures are: - One-finger swipe on touchscreens - Horizontal scrolling on touchpads (usually two-finger swipe) - Back/forward mouse buttons The keyboard back/forward keys are also supported, as well as the <kbd>Alt</kbd>+<kbd>←</kbd> shortcut for horizontal orientation, or <kbd>Alt</kbd>+<kbd>↑</kbd> for vertical orientation. If the orientation is horizontal, for right-to-left locales, gestures and shortcuts are reversed. Only children that have [property@LeafletPage:navigatable] set to `TRUE` can be navigated to. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) Whether gestures and shortcuts for navigating forward are enabled. The supported gestures are: - One-finger swipe on touchscreens - Horizontal scrolling on touchpads (usually two-finger swipe) - Back/forward mouse buttons The keyboard back/forward keys are also supported, as well as the <kbd>Alt</kbd>+<kbd>→</kbd> shortcut for horizontal orientation, or <kbd>Alt</kbd>+<kbd>↓</kbd> for vertical orientation. If the orientation is horizontal, for right-to-left locales, gestures and shortcuts are reversed. Only children that have [property@LeafletPage:navigatable] set to `TRUE` can be navigated to. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) Whether or not the leaflet can unfold. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) The child transition spring parameters. The default value is equivalent to: ```c adw_spring_params_new (1, 0.5, 500) ``` See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) Whether a child transition is currently running. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) Determines when the leaflet will fold. If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only fold when the children cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it will fold as soon as children don't get their natural size. This can be useful if you have a long ellipsizing label and want to let it ellipsize instead of immediately folding. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) Whether the leaflet is folded. The leaflet will be folded if the size allocated to it is smaller than the sum of the minimum or natural sizes of the children (see [property@Leaflet:fold-threshold-policy]), it will be unfolded otherwise. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) Whether the leaflet allocates the same size for all children when folded. If set to `FALSE`, different children can have different size along the opposite orientation. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) The mode transition animation duration, in milliseconds. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) A selection model with the leaflet's pages. 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 change the visible page. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) The type of animation used for transitions between modes and children. The transition type can be changed without problems at runtime, so it is possible to change the animation based on the mode or child that is about to become current. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) The widget currently visible when the leaflet is folded. The transition is determined by [property@Leaflet:transition-type] and [property@Leaflet:child-transition-params]. The transition can be cancelled by the user, in which case visible child will change back to the previously visible child. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) The name of the widget currently visible when the leaflet is folded. See [property@Leaflet:visible-child]. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) An auxiliary class used by [class@Leaflet]. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) Gets the leaflet child to which @self belongs. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the child to which @self belongs a leaflet page Gets the name of @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) the name of @self. a leaflet page Gets whether the child can be navigated to when folded. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) whether @self can be navigated to when folded a leaflet page Sets the name of the @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet page the new value to set Sets whether @self can be navigated to when folded. If `FALSE`, the child will be ignored by [method@Leaflet.get_adjacent_child], [method@Leaflet.navigate], and swipe gestures. This can be used used to prevent switching to widgets like separators. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) a leaflet page whether @self can be navigated to when folded The leaflet child to which the page belongs. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) The name of the child page. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) Whether the child can be navigated to when folded. If `FALSE`, the child will be ignored by [method@Leaflet.get_adjacent_child], [method@Leaflet.navigate], and swipe gestures. This can be used used to prevent switching to widgets like separators. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) Describes the possible transitions in a [class@Leaflet] widget. New values may be added to this enumeration over time. See [the migration guide](migrating-to-breakpoints.html#replace-adwleaflet) Cover the old page or uncover the new page, sliding from or towards the end according to orientation, text direction and children order Uncover the new page or cover the old page, sliding from or towards the start according to orientation, text direction and children order Slide from left, right, up or down according to the orientation, text direction and the children order Describes length units. | Unit | Regular Text | Large Text | | ---- | ------------ | ---------- | | 1px | 1px | 1px | | 1pt | 1.333333px | 1.666667px | | 1sp | 1px | 1.25px | New values may be added to this enumeration over time. pixels points, changes with text scale factor scale independent pixels, changes with text scale factor Converts @value from pixels to @unit. the length in @unit a length unit a value in pixels settings to use, or `NULL` for default settings Converts @value from @unit to pixels. the length in pixels a length unit a value in @unit settings to use, or `NULL` for default settings Adwaita major version component (e.g. 1 if the version is 1.2.3). Adwaita micro version component (e.g. 3 if the version is 1.2.3). Adwaita minor version component (e.g. 2 if the version is 1.2.3). A dialog presenting a message or a question. <picture> <source srcset="message-dialog-dark.png" media="(prefers-color-scheme: dark)"> <img src="message-dialog.png" alt="message-dialog"> </picture> Message dialogs have a heading, a body, an optional child widget, and one or multiple responses, each presented as a button. Each response has a unique string ID, and a button label. Additionally, each response can be enabled or disabled, and can have a suggested or destructive appearance. When one of the responses is activated, or the dialog is closed, the [signal@MessageDialog::response] signal will be emitted. This signal is detailed, and the detail, as well as the `response` parameter will be set to the ID of the activated response, or to the value of the [property@MessageDialog:close-response] property if the dialog had been closed without activating any of the responses. Response buttons can be presented horizontally or vertically depending on available space. When a response is activated, `AdwMessageDialog` is closed automatically. An example of using a message dialog: ```c GtkWidget *dialog; dialog = adw_message_dialog_new (parent, _("Replace File?"), NULL); adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog), _("A file named “%s” already exists. Do you want to replace it?"), filename); adw_message_dialog_add_responses (ADW_MESSAGE_DIALOG (dialog), "cancel", _("_Cancel"), "replace", _("_Replace"), NULL); adw_message_dialog_set_response_appearance (ADW_MESSAGE_DIALOG (dialog), "replace", ADW_RESPONSE_DESTRUCTIVE); adw_message_dialog_set_default_response (ADW_MESSAGE_DIALOG (dialog), "cancel"); adw_message_dialog_set_close_response (ADW_MESSAGE_DIALOG (dialog), "cancel"); g_signal_connect (dialog, "response", G_CALLBACK (response_cb), self); gtk_window_present (GTK_WINDOW (dialog)); ``` ## Async API `AdwMessageDialog` can also be used via the [method@MessageDialog.choose] method. This API follows the GIO async pattern, for example: ```c static void dialog_cb (AdwMessageDialog *dialog, GAsyncResult *result, MyWindow *self) { const char *response = adw_message_dialog_choose_finish (dialog, result); // ... } static void show_dialog (MyWindow *self) { GtkWidget *dialog; dialog = adw_message_dialog_new (GTK_WINDOW (self), _("Replace File?"), NULL); adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog), _("A file named “%s” already exists. Do you want to replace it?"), filename); adw_message_dialog_add_responses (ADW_MESSAGE_DIALOG (dialog), "cancel", _("_Cancel"), "replace", _("_Replace"), NULL); adw_message_dialog_set_response_appearance (ADW_MESSAGE_DIALOG (dialog), "replace", ADW_RESPONSE_DESTRUCTIVE); adw_message_dialog_set_default_response (ADW_MESSAGE_DIALOG (dialog), "cancel"); adw_message_dialog_set_close_response (ADW_MESSAGE_DIALOG (dialog), "cancel"); adw_message_dialog_choose (ADW_MESSAGE_DIALOG (dialog), NULL, (GAsyncReadyCallback) dialog_cb, self); } ``` ## AdwMessageDialog as GtkBuildable `AdwMessageDialog` supports adding responses in UI definitions by via the `<responses>` element that may contain multiple `<response>` elements, each respresenting a response. Each of the `<response>` elements must have the `id` attribute specifying the response ID. The contents of the element are used as the response label. Response labels can be translated with the usual `translatable`, `context` and `comments` attributes. The `<response>` elements can also have `enabled` and/or `appearance` attributes. See [method@MessageDialog.set_response_enabled] and [method@MessageDialog.set_response_appearance] for details. Example of an `AdwMessageDialog` UI definition: ```xml <object class="AdwMessageDialog" id="dialog"> <property name="heading" translatable="yes">Save Changes?</property> <property name="body" translatable="yes">Open documents contain unsaved changes. Changes which are not saved will be permanently lost.</property> <property name="default-response">save</property> <property name="close-response">cancel</property> <signal name="response" handler="response_cb"/> <responses> <response id="cancel" translatable="yes">_Cancel</response> <response id="discard" translatable="yes" appearance="destructive">_Discard</response> <response id="save" translatable="yes" appearance="suggested" enabled="false">_Save</response> </responses> </object> ``` ## Accessibility `AdwMessageDialog` uses the `GTK_ACCESSIBLE_ROLE_DIALOG` role. Use [class@AlertDialog]. Creates a new `AdwMessageDialog`. @heading and @body can be set to `NULL`. This can be useful if they need to be formatted or use markup. In that case, set them to `NULL` and call [method@MessageDialog.format_body] or similar methods afterwards: ```c GtkWidget *dialog; dialog = adw_message_dialog_new (parent, _("Replace File?"), NULL); adw_message_dialog_format_body (ADW_MESSAGE_DIALOG (dialog), _("A file named “%s” already exists. Do you want to replace it?"), filename); ``` Use [class@AlertDialog]. the newly created `AdwMessageDialog` transient parent the heading the body text Emits the [signal@MessageDialog::response] signal with the given response ID. Used to indicate that the user has responded to the dialog in some way. Use [class@AlertDialog]. a message dialog response ID Adds a response with @id and @label to @self. Responses are represented as buttons in the dialog. Response ID must be unique. It will be used in [signal@MessageDialog::response] to tell which response had been activated, as well as to inspect and modify the response later. An embedded underline in @label indicates a mnemonic. [method@MessageDialog.set_response_label] can be used to change the response label after it had been added. [method@MessageDialog.set_response_enabled] and [method@MessageDialog.set_response_appearance] can be used to customize the responses further. Use [class@AlertDialog]. a message dialog the response ID the response label Adds multiple responses to @self. This is the same as calling [method@MessageDialog.add_response] repeatedly. The variable argument list should be `NULL`-terminated list of response IDs and labels. Example: ```c adw_message_dialog_add_responses (dialog, "cancel", _("_Cancel"), "discard", _("_Discard"), "save", _("_Save"), NULL); ``` Use [class@AlertDialog]. a message dialog response id label for first response, then more id-label pairs This function shows @self to the user. Use [class@AlertDialog]. a message dialog a `GCancellable` to cancel the operation a callback to call when the operation is complete data to pass to @callback Finishes the [method@MessageDialog.choose] call and returns the response ID. Use [class@AlertDialog]. the ID of the response that was selected, or [property@MessageDialog:close-response] if the call was cancelled. a message dialog a `GAsyncResult` Sets the formatted body text of @self. See [property@MessageDialog:body]. Use [class@AlertDialog]. a message dialog the formatted string for the body text the parameters to insert into @format Sets the formatted body text of @self with Pango markup. The @format is assumed to contain Pango markup. Special XML characters in the `printf()` arguments passed to this function will automatically be escaped as necessary, see [func@GLib.markup_printf_escaped]. See [property@MessageDialog:body]. Use [class@AlertDialog]. a message dialog the formatted string for the body text with Pango markup the parameters to insert into @format Sets the formatted heading of @self. See [property@MessageDialog:heading]. Use [class@AlertDialog]. a message dialog the formatted string for the heading the parameters to insert into @format Sets the formatted heading of @self with Pango markup. The @format is assumed to contain Pango markup. Special XML characters in the `printf()` arguments passed to this function will automatically be escaped as necessary, see [func@GLib.markup_printf_escaped]. See [property@MessageDialog:heading]. Use [class@AlertDialog]. a message dialog the formatted string for the heading with Pango markup the parameters to insert into @format Gets the body text of @self. Use [class@AlertDialog]. the body of @self. a message dialog Gets whether the body text of @self includes Pango markup. Use [class@AlertDialog]. whether @self uses markup for body text a message dialog Gets the ID of the close response of @self. Use [class@AlertDialog]. the close response ID a message dialog Gets the ID of the default response of @self. Use [class@AlertDialog]. the default response ID a message dialog Gets the child widget of @self. Use [class@AlertDialog]. the child widget of @self. a message dialog Gets the heading of @self. Use [class@AlertDialog]. the heading of @self. a message dialog Gets whether the heading of @self includes Pango markup. Use [class@AlertDialog]. whether @self uses markup for heading a message dialog Gets the appearance of @response. See [method@MessageDialog.set_response_appearance]. Use [class@AlertDialog]. the appearance of @response a message dialog a response ID Gets whether @response is enabled. See [method@MessageDialog.set_response_enabled]. Use [class@AlertDialog]. whether @response is enabled a message dialog a response ID Gets the label of @response. See [method@MessageDialog.set_response_label]. Use [class@AlertDialog]. the label of @response a message dialog a response ID Gets whether @self has a response with the ID @response. Use [class@AlertDialog]. whether @self has a response with the ID @response. a message dialog response ID Removes a response from @self. Use [class@AlertDialog]. a message dialog the response ID Emits the [signal@MessageDialog::response] signal with the given response ID. Used to indicate that the user has responded to the dialog in some way. Use [class@AlertDialog]. a message dialog response ID Sets the body text of @self. Use [class@AlertDialog]. a message dialog the body of @self Sets whether the body text of @self includes Pango markup. See [func@Pango.parse_markup]. Use [class@AlertDialog]. a message dialog whether to use markup for body text Sets the ID of the close response of @self. It will be passed to [signal@MessageDialog::response] if the window is closed by pressing <kbd>Escape</kbd> or with a system action. It doesn't have to correspond to any of the responses in the dialog. The default close response is `close`. Use [class@AlertDialog]. a message dialog the close response ID Sets the ID of the default response of @self. If set, pressing <kbd>Enter</kbd> will activate the corresponding button. If set to `NULL` or to a non-existent response ID, pressing <kbd>Enter</kbd> will do nothing. Use [class@AlertDialog]. a message dialog the default response ID Sets the child widget of @self. The child widget is displayed below the heading and body. Use [class@AlertDialog]. a message dialog the child widget Sets the heading of @self. Use [class@AlertDialog]. a message dialog the heading of @self Sets whether the heading of @self includes Pango markup. See [func@Pango.parse_markup]. Use [class@AlertDialog]. a message dialog whether to use markup for heading Sets the appearance for @response. <picture> <source srcset="message-dialog-appearance-dark.png" media="(prefers-color-scheme: dark)"> <img src="message-dialog-appearance.png" alt="message-dialog-appearance"> </picture> Use `ADW_RESPONSE_SUGGESTED` to mark important responses such as the affirmative action, like the Save button in the example. Use `ADW_RESPONSE_DESTRUCTIVE` to draw attention to the potentially damaging consequences of using @response. This appearance acts as a warning to the user. The Discard button in the example is using this appearance. The default appearance is `ADW_RESPONSE_DEFAULT`. Negative responses like Cancel or Close should use the default appearance. Use [class@AlertDialog]. a message dialog a response ID appearance for @response Sets whether @response is enabled. If @response is not enabled, the corresponding button will have [property@Gtk.Widget:sensitive] set to `FALSE` and it can't be activated as a default response. @response can still be used as [property@MessageDialog:close-response] while it's not enabled. Responses are enabled by default. Use [class@AlertDialog]. a message dialog a response ID whether to enable @response Sets the label of @response to @label. Labels are displayed on the dialog buttons. An embedded underline in @label indicates a mnemonic. Use [class@AlertDialog]. a message dialog a response ID the label of @response The body text of the dialog. Use [class@AlertDialog]. Whether the body text includes Pango markup. See [func@Pango.parse_markup]. Use [class@AlertDialog]. The ID of the close response. It will be passed to [signal@MessageDialog::response] if the window is closed by pressing <kbd>Escape</kbd> or with a system action. It doesn't have to correspond to any of the responses in the dialog. The default close response is `close`. Use [class@AlertDialog]. The response ID of the default response. If set, pressing <kbd>Enter</kbd> will activate the corresponding button. If set to `NULL` or a non-existent response ID, pressing <kbd>Enter</kbd> will do nothing. Use [class@AlertDialog]. The child widget. Displayed below the heading and body. Use [class@AlertDialog]. The heading of the dialog. Use [class@AlertDialog]. Whether the heading includes Pango markup. See [func@Pango.parse_markup]. Use [class@AlertDialog]. This signal is emitted when the dialog is closed. @response will be set to the response ID of the button that had been activated. if the dialog was closed by pressing <kbd>Escape</kbd> or with a system action, @response will be set to the value of [property@MessageDialog:close-response]. Use [class@AlertDialog]. the response ID a message dialog response ID A widget for switching between different layouts. `AdwMultiLayoutView` contains layouts and children. Each child has an ID, each layout has slots inside it, each slot also has an ID. When switching layouts, children are inserted into slots with matching IDs. This can be useful for rearranging children when it's difficult to do so otherwise, for example to move a child from a sidebar to a bottom bar. The currently used layout can be switched using the [property@MultiLayoutView:layout] or [property@MultiLayoutView:layout-name] properties. For example, it can be done via a [class@Adw.Breakpoint] setter to change layouts depending on the window size. ## AdwMultiLayoutView as GtkBuildable The `AdwMultiLayoutView` implementation of the [iface@Gtk.Buildable] interface supports adding layouts via `<child>` element with the `type` attribute omitted. It also supports setting children via `<child type="ID">`. Example of an `AdwMultiLayoutView` UI definition that can display a secondary child as either a sidebar or a bottom sheet. ```xml <object class="AdwMultiLayoutView"> <child> <object class="AdwLayout"> <property name="name">sidebar</property> <property name="content"> <object class="AdwOverlaySplitView"> <property name="sidebar"> <object class="AdwLayoutSlot"> <property name="id">secondary</property> </object> </property> <property name="content"> <object class="AdwLayoutSlot"> <property name="id">primary</property> </object> </property> </object> </property> </object> </child> <child> <object class="AdwLayout"> <property name="name">bottom-sheet</property> <property name="content"> <object class="AdwBottomSheet"> <property name="open">True</property> <property name="content"> <object class="AdwLayoutSlot"> <property name="id">primary</property> </object> </property> <property name="sheet"> <object class="AdwLayoutSlot"> <property name="id">secondary</property> </object> </property> </object> </property> </object> </child> <child type="primary"> <!-- ... --> </child> <child type="secondary"> <!-- ... --> </child> </object> ``` ## CSS nodes `AdwMultiLayoutView` has a single CSS node with name `multi-layout-view`. Creates a new `AdwMultiLayoutView`. the newly created `AdwMultiLayoutView` Adds @layout to @self. a multi-layout view the layout to add Gets the child for @id to @self. the child for @id a multi-layout view the id of the child Gets the currently used layout of @self. the current layout a multi-layout view Gets layout with the name @name from @self, or `NULL` if it doesn't exist. See [property@Layout:name]. the layout with @name a multi-layout view the name of the layout Returns the name of the currently used layout of @self. the name of the current layout a multi-layout view Removes @layout from @self. a multi-layout view the layout to add Sets @child as the child for @id in @self. When changing layouts, it will be inserted into the slot with @id. a multi-layout view the id of the child the child to set Makes @layout the current layout of @self. a multi-layout view a layout in @self Makes the layout with @name the current layout of @self. See [property@Layout:name]. a multi-layout view the name of the layout The currently used layout. The name of the currently used layout. See [property@Layout:name]. Describes the direction of a swipe navigation gesture. Corresponds to start or top, depending on orientation and text direction Corresponds to end or bottom, depending on orientation and text direction A page within [class@NavigationView] or [class@NavigationSplitView]. Each page has a child widget, a title and optionally a tag. The [signal@NavigationPage::showing], [signal@NavigationPage::shown], [signal@NavigationPage::hiding] and [signal@NavigationPage::hidden] signals can be used to track the page's visibility within its `AdwNavigationView`. ## Header Bar Integration When placed inside `AdwNavigationPage`, [class@HeaderBar] will display the page title instead of window title. When used together with [class@NavigationView], it will also display a back button that can be used to go back to the previous page. Set [property@HeaderBar:show-back-button] to `FALSE` to disable that behavior if it's unwanted. ## CSS Nodes `AdwNavigationPage` has a single CSS node with name `navigation-view-page`. ## Accessibility `AdwNavigationPage` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. Creates a new `AdwNavigationPage`. the new created `AdwNavigationPage` the child widget the page title Creates a new `AdwNavigationPage` with provided tag. the new created `AdwNavigationPage` the child widget the page title the page tag Called when the navigation view transition has been completed and the page is fully hidden. a navigation page Called when the page starts hiding at the beginning of the navigation view transition. a navigation page Called when the page shows at the beginning of the navigation view transition. a navigation page Called when the navigation view transition has been completed and the page is fully shown. a navigation page Gets whether @self can be popped from navigation stack. whether the page can be popped from navigation stack a navigation page Gets the child widget of @self. the child widget of @self a navigation page Gets the tag of @self. the page tag a navigation page Gets the title of @self. the title of @self a navigation page Sets whether @self can be popped from navigation stack. Set it to `FALSE` to disable shortcuts and gestures, as well as remove the back button from [class@HeaderBar]. Manually calling [method@NavigationView.pop] or using the `navigation.pop` action will still work. See [property@HeaderBar:show-back-button] for removing only the back button, but not shortcuts. a navigation page whether the page can be popped from navigation stack Sets the child widget of @self. a navigation page the child widget Sets the tag for @self. The tag can be used to retrieve the page with [method@NavigationView.find_page], as well as with [method@NavigationView.push_by_tag], [method@NavigationView.pop_to_tag] or [method@NavigationView.replace_with_tags]. Tags must be unique within each [class@NavigationView]. The tag also must be set to use the `navigation.push` action. a navigation page the page tag Sets the title of @self. It's displayed in [class@HeaderBar] instead of the window title, and used as the tooltip on the next page's back button, as well as by screen reader. a navigation page the title Whether the page can be popped from navigation stack. Set it to `FALSE` to disable shortcuts and gestures, as well as remove the back button from [class@HeaderBar]. Manually calling [method@NavigationView.pop] or using the `navigation.pop` action will still work. See [property@HeaderBar:show-back-button] for removing only the back button, but not shortcuts. The child widget. The page tag. The tag can be used to retrieve the page with [method@NavigationView.find_page], as well as with [method@NavigationView.push_by_tag], [method@NavigationView.pop_to_tag] or [method@NavigationView.replace_with_tags]. Tags must be unique within each [class@NavigationView]. The tag also must be set to use the `navigation.push` action. The page title. It's displayed in [class@HeaderBar] instead of the window title, and used as the tooltip on the next page's back button, as well as by screen reader. Emitted when the navigation view transition has been completed and the page is fully hidden. It will always be preceded by [signal@NavigationPage::hiding] or [signal@NavigationPage::showing]. Emitted when the page starts hiding at the beginning of the navigation view transition. It will always be followed by [signal@NavigationPage::hidden] or [signal@NavigationPage::shown]. Emitted when the page shows at the beginning of the navigation view transition. It will always be followed by [signal@NavigationPage::shown] or [signal@NavigationPage::hidden]. Emitted when the navigation view transition has been completed and the page is fully shown. It will always be preceded by [signal@NavigationPage::showing] or [signal@NavigationPage::hiding]. a navigation page a navigation page a navigation page a navigation page A widget presenting sidebar and content side by side or as a navigation view. <picture> <source srcset="navigation-split-view-dark.png" media="(prefers-color-scheme: dark)"> <img src="navigation-split-view.png" alt="navigation-split-view"> </picture> <picture> <source srcset="navigation-split-view-collapsed-dark.png" media="(prefers-color-scheme: dark)"> <img src="navigation-split-view-collapsed.png" alt="navigation-split-view-collapsed"> </picture> `AdwNavigationSplitView` has two [class@NavigationPage] children: sidebar and content, and displays them side by side. When [property@NavigationSplitView:collapsed] is set to `TRUE`, it instead puts both children inside an [class@NavigationView]. The [property@NavigationSplitView:show-content] controls which child is visible while collapsed. See also [class@OverlaySplitView]. `AdwNavigationSplitView` is typically used together with an [class@Breakpoint] setting the `collapsed` property to `TRUE` on small widths, as follows: ```xml <object class="AdwWindow"> <property name="width-request">280</property> <property name="height-request">200</property> <property name="default-width">800</property> <property name="default-height">800</property> <child> <object class="AdwBreakpoint"> <condition>max-width: 400sp</condition> <setter object="split_view" property="collapsed">True</setter> </object> </child> <property name="content"> <object class="AdwNavigationSplitView" id="split_view"> <property name="sidebar"> <object class="AdwNavigationPage"> <property name="title" translatable="yes">Sidebar</property> <property name="child"> <!-- ... --> </property> </object> </property> <property name="content"> <object class="AdwNavigationPage"> <property name="title" translatable="yes">Content</property> <property name="child"> <!-- ... --> </property> </object> </property> </object> </property> </object> ``` ## Sizing When not collapsed, `AdwNavigationSplitView` changes the sidebar width depending on its own width. If possible, it tries to allocate a fraction of the total width, controlled with the [property@NavigationSplitView:sidebar-width-fraction] property. The sidebar also has minimum and maximum sizes, controlled with the [property@NavigationSplitView:min-sidebar-width] and [property@NavigationSplitView:max-sidebar-width] properties. The minimum and maximum sizes are using the length unit specified with the [property@NavigationSplitView:sidebar-width-unit]. By default, sidebar is using 25% of the total width, with 180sp as the minimum size and 280sp as the maximum size. ## Header Bar Integration When used inside `AdwNavigationSplitView`, [class@HeaderBar] will automatically hide the window buttons in the middle. When collapsed, it also displays a back button for the content widget, as well as the page titles. See [class@NavigationView] documentation for details. ## Actions `AdwNavigationSplitView` defines the same actions as `AdwNavigationView`, but they can be used even when the split view is not collapsed: - `navigation.push` takes a string parameter specifying the tag of the page to push. If it matches the tag of the content widget, it sets [property@NavigationSplitView:show-content] to `TRUE`. - `navigation.pop` doesn't take any parameters and sets [property@NavigationSplitView:show-content] to `FALSE`. ## `AdwNavigationSplitView` as `GtkBuildable` The `AdwNavigationSplitView` implementation of the [iface@Gtk.Buildable] interface supports setting the sidebar widget by specifying “sidebar” as the “type” attribute of a `<child>` element, Specifying “content” child type or omitting it results in setting the content widget. ## CSS nodes `AdwNavigationSplitView` has a single CSS node with the name `navigation-split-view`. When collapsed, it contains a child node with the name `navigation-view` containing both children. ``` navigation-split-view ╰── navigation-view ├── [sidebar child] ╰── [content child] ``` When not collapsed, it contains two nodes with the name `widget`, one with the `.sidebar-pane` style class, the other one with `.content-view` style class, containing the sidebar and content children respectively. ``` navigation-split-view ├── widget.sidebar-pane │ ╰── [sidebar child] ╰── widget.content-pane ╰── [content child] ``` ## Accessibility `AdwNavigationSplitView` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. Creates a new `AdwNavigationSplitView`. the newly created `AdwNavigationSplitView` Gets whether @self is collapsed. whether @self is collapsed a navigation split view Sets the content widget for @self. the content widget a navigation split view Gets the maximum sidebar width for @self. the maximum width a navigation split view Gets the minimum sidebar width for @self. the minimum width a navigation split view Gets which page is visible when @self is collapsed. whether to show content when collapsed a navigation split view Gets the sidebar widget for @self. the sidebar widget a navigation split view Gets the preferred sidebar width fraction for @self. the preferred width fraction a navigation split view Gets the length unit for minimum and maximum sidebar widths. the length unit a navigation split view Sets whether @self is collapsed. When collapsed, the children are put inside an [class@NavigationView], otherwise they are displayed side by side. The [property@NavigationSplitView:show-content] controls which child is visible while collapsed. a navigation split view whether @self is collapsed Sets the content widget for @self. a navigation split view the content widget Sets the maximum sidebar width for @self. Maximum width is affected by [property@NavigationSplitView:sidebar-width-unit]. The sidebar widget can still be allocated with larger width if its own minimum width exceeds it. a navigation split view the maximum width Sets the minimum sidebar width for @self. Minimum width is affected by [property@NavigationSplitView:sidebar-width-unit]. The sidebar widget can still be allocated with larger width if its own minimum width exceeds it. a navigation split view the minimum width Sets which page is visible when @self is collapsed. If set to `TRUE`, the content widget will be the visible page when [property@NavigationSplitView:collapsed] is `TRUE`; otherwise the sidebar widget will be visible. If the split view is already collapsed, the visible page changes immediately. a navigation split view whether to show content when collapsed Sets the sidebar widget for @self. a navigation split view the sidebar widget Sets the preferred sidebar width as a fraction of the total width of @self. The preferred width is additionally limited by [property@NavigationSplitView:min-sidebar-width] and [property@NavigationSplitView:max-sidebar-width]. The sidebar widget can be allocated with larger width if its own minimum width exceeds the preferred width. a navigation split view the preferred width fraction Sets the length unit for minimum and maximum sidebar widths. See [property@NavigationSplitView:min-sidebar-width] and [property@NavigationSplitView:max-sidebar-width]. a navigation split view the length unit Whether the split view is collapsed. When collapsed, the children are put inside an [class@NavigationView], otherwise they are displayed side by side. The [property@NavigationSplitView:show-content] controls which child is visible while collapsed. The content widget. The maximum sidebar width. Maximum width is affected by [property@NavigationSplitView:sidebar-width-unit]. The sidebar widget can still be allocated with larger width if its own minimum width exceeds it. The minimum sidebar width. Minimum width is affected by [property@NavigationSplitView:sidebar-width-unit]. The sidebar widget can still be allocated with larger width if its own minimum width exceeds it. Determines the visible page when collapsed. If set to `TRUE`, the content widget will be the visible page when [property@NavigationSplitView:collapsed] is `TRUE`; otherwise the sidebar widget will be visible. If the split view is already collapsed, the visible page changes immediately. The sidebar widget. The preferred sidebar width as a fraction of the total width. The preferred width is additionally limited by [property@NavigationSplitView:min-sidebar-width] and [property@NavigationSplitView:max-sidebar-width]. The sidebar widget can be allocated with larger width if its own minimum width exceeds the preferred width. The length unit for minimum and maximum sidebar widths. See [property@NavigationSplitView:min-sidebar-width] and [property@NavigationSplitView:max-sidebar-width]. A page-based navigation container. <picture> <source srcset="navigation-view-dark.png" media="(prefers-color-scheme: dark)"> <img src="navigation-view.png" alt="navigation-view"> </picture> `AdwNavigationView` presents one child at a time, similar to [class@Gtk.Stack]. `AdwNavigationView` can only contain [class@NavigationPage] children. It maintains a navigation stack that can be controlled with [method@NavigationView.push] and [method@NavigationView.pop]. The whole navigation stack can also be replaced using [method@NavigationView.replace]. `AdwNavigationView` allows to manage pages statically or dynamically. Static pages can be added using the [method@NavigationView.add] method. The `AdwNavigationView` will keep a reference to these pages, but they aren't accessible to the user until [method@NavigationView.push] is called (except for the first page, which is pushed automatically). Use the [method@NavigationView.remove] method to remove them. This is useful for applications that have a small number of unique pages and just need navigation between them. Dynamic pages are automatically destroyed once they are popped off the navigation stack. To add a page like this, push it using the [method@NavigationView.push] method without calling [method@NavigationView.add] first. ## Tags Static pages, as well as any pages in the navigation stack, can be accessed by their [property@NavigationPage:tag]. For example, [method@NavigationView.push_by_tag] can be used to push a static page that's not in the navigation stack without having to keep a reference to it manually. ## Header Bar Integration When used inside `AdwNavigationView`, [class@HeaderBar] will automatically display a back button that can be used to go back to the previous page when possible. The button also has a context menu, allowing to pop multiple pages at once, potentially across multiple navigation views. Set [property@HeaderBar:show-back-button] to `FALSE` to disable this behavior in rare scenarios where it's unwanted. `AdwHeaderBar` will also display the title of the `AdwNavigationPage` it's placed into, so most applications shouldn't need to customize it at all. ## Shortcuts and Gestures `AdwNavigationView` supports the following shortcuts for going to the previous page: - <kbd>Escape</kbd> (unless [property@NavigationView:pop-on-escape] is set to `FALSE`) - <kbd>Alt</kbd>+<kbd>←</kbd> - Back mouse button Additionally, it supports interactive gestures: - One-finger swipe towards the right on touchscreens - Scrolling towards the right on touchpads (usually two-finger swipe) These gestures have transitions enabled regardless of the [property@NavigationView:animate-transitions] value. Applications can also enable shortcuts for pushing another page onto the navigation stack via connecting to the [signal@NavigationView::get-next-page] signal, in that case the following shortcuts are supported: - <kbd>Alt</kbd>+<kbd>→</kbd> - Forward mouse button - Swipe/scrolling towards the left For right-to-left locales, the gestures and shortcuts are reversed. [property@NavigationPage:can-pop] can be used to disable them, along with the header bar back buttons. ## Actions `AdwNavigationView` defines actions for controlling the navigation stack. actions for controlling the navigation stack: - `navigation.push` takes a string parameter specifying the tag of the page to push, and is equivalent to calling [method@NavigationView.push_by_tag]. - `navigation.pop` doesn't take any parameters and pops the current page from the navigation stack, equivalent to calling [method@NavigationView.pop]. ## `AdwNavigationView` as `GtkBuildable` `AdwNavigationView` allows to add pages as children, equivalent to using the [method@NavigationView.add] method. Example of an `AdwNavigationView` UI definition: ```xml <object class="AdwNavigationView"> <child> <object class="AdwNavigationPage"> <property name="title" translatable="yes">Page 1</property> <property name="child"> <object class="AdwToolbarView"> <child type="top"> <object class="AdwHeaderBar"/> </child> <property name="content"> <object class="GtkButton"> <property name="label" translatable="yes">Open Page 2</property> <property name="halign">center</property> <property name="valign">center</property> <property name="action-name">navigation.push</property> <property name="action-target">'page-2'</property> <style> <class name="pill"/> </style> </object> </property> </object> </property> </object> </child> <child> <object class="AdwNavigationPage"> <property name="title" translatable="yes">Page 2</property> <property name="tag">page-2</property> <property name="child"> <object class="AdwToolbarView"> <child type="top"> <object class="AdwHeaderBar"/> </child> <property name="content"> <!-- ... --> </property> </object> </property> </object> </child> </object> ``` <picture> <source srcset="navigation-view-example-dark.png" media="(prefers-color-scheme: dark)"> <img src="navigation-view-example.png" alt="navigation-view-example"> </picture> ## CSS nodes `AdwNavigationView` has a single CSS node with the name `navigation-view`. ## Accessibility `AdwNavigationView` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. Creates a new `AdwNavigationView`. the new created `AdwNavigationView` Permanently adds @page to @self. Any page that has been added will stay in @self even after being popped from the navigation stack. Adding a page while no page is visible will automatically push it to the navigation stack. See [method@NavigationView.remove]. a navigation view the page to add Finds a page in @self by its tag. See [property@NavigationPage:tag]. the page with the given tag a navigation view a page tag Gets whether @self animates page transitions. whether to animate page transitions a navigation view Returns a [iface@Gio.ListModel] that contains the pages in navigation stack. The pages are sorted from root page to visible page. This can be used to keep an up-to-date view. a list model for the navigation stack a navigation view Gets whether pressing Escape pops the current page on @self. whether to pop the current page a navigation view Gets the previous page for @page. If @page is in the navigation stack, returns the page popping @page will reveal. If @page is the root page or is not in the navigation stack, returns `NULL`. the previous page a navigation view a page in @self Gets the currently visible page in @self. the currently visible page a navigation view Pops the visible page from the navigation stack. Does nothing if the navigation stack contains less than two pages. If [method@NavigationView.add] hasn't been called, the page is automatically removed. [signal@NavigationView::popped] will be emitted for the current visible page. See [method@NavigationView.pop_to_page] and [method@NavigationView.pop_to_tag]. `TRUE` if a page has been popped a navigation view Pops pages from the navigation stack until @page is visible. @page must be in the navigation stack. If [method@NavigationView.add] hasn't been called for any of the popped pages, they are automatically removed. [signal@NavigationView::popped] will be be emitted for each of the popped pages. See [method@NavigationView.pop] and [method@NavigationView.pop_to_tag]. `TRUE` if any pages have been popped a navigation view the page to pop to Pops pages from the navigation stack until page with the tag @tag is visible. The page must be in the navigation stack. If [method@NavigationView.add] hasn't been called for any of the popped pages, they are automatically removed. [signal@NavigationView::popped] will be emitted for each of the popped pages. See [method@NavigationView.pop_to_page] and [property@NavigationPage:tag]. `TRUE` if any pages have been popped a navigation view a page tag Pushes @page onto the navigation stack. If [method@NavigationView.add] hasn't been called, the page is automatically removed once it's popped. [signal@NavigationView::pushed] will be emitted for @page. See [method@NavigationView.push_by_tag]. a navigation view the page to push Pushes the page with the tag @tag onto the navigation stack. If [method@NavigationView.add] hasn't been called, the page is automatically removed once it's popped. [signal@NavigationView::pushed] will be emitted for the page. See [method@NavigationView.push] and [property@NavigationPage:tag]. a navigation view the page tag Removes @page from @self. If @page is currently in the navigation stack, it will be removed once it's popped. Otherwise, it's removed immediately. See [method@NavigationView.add]. a navigation view the page to remove Replaces the current navigation stack with @pages. The last page becomes the visible page. Replacing the navigation stack has no animation. If [method@NavigationView.add] hasn't been called for any pages that are no longer in the navigation stack, they are automatically removed. @n_pages can be 0, in that case no page will be visible after calling this method. This can be useful for removing all pages from @self. The [signal@NavigationView::replaced] signal will be emitted. See [method@NavigationView.replace_with_tags]. a navigation view the new navigation stack the number of pages in @pages Replaces the current navigation stack with pages with the tags @tags. The last page becomes the visible page. Replacing the navigation stack has no animation. If [method@NavigationView.add] hasn't been called for any pages that are no longer in the navigation stack, they are automatically removed. @n_tags can be 0, in that case no page will be visible after calling this method. This can be useful for removing all pages from @self. The [signal@NavigationView::replaced] signal will be emitted. See [method@NavigationView.replace] and [property@NavigationPage:tag]. a navigation view tags of the pages in the navigation stack the number of tags Sets whether @self should animate page transitions. Gesture-based transitions are always animated. a navigation view whether to animate page transitions Sets whether pressing Escape pops the current page on @self. Applications using `AdwNavigationView` to implement a browser may want to disable it. a navigation view whether to pop the current page when pressing Escape Whether to animate page transitions. Gesture-based transitions are always animated. A list model that contains the pages in navigation stack. The pages are sorted from root page to visible page. This can be used to keep an up-to-date view. Whether pressing Escape pops the current page. Applications using `AdwNavigationView` to implement a browser may want to disable it. The currently visible page. Emitted when a push shortcut or a gesture is triggered. To support the push shortcuts and gestures, the application is expected to return the page to push in the handler. This signal can be emitted multiple times for the gestures, for example when the gesture is cancelled by the user. As such, the application must not make any irreversible changes in the handler, such as removing the page from a forward stack. Instead, it should be done in the [signal@NavigationView::pushed] handler. the page to push Emitted after @page has been popped from the navigation stack. See [method@NavigationView.pop]. When using [method@NavigationView.pop_to_page] or [method@NavigationView.pop_to_tag], this signal is emitted for each of the popped pages. the popped page Emitted after a page has been pushed to the navigation stack. See [method@NavigationView.push]. Emitted after the navigation stack has been replaced. See [method@NavigationView.replace]. A widget presenting sidebar and content side by side or as an overlay. <picture> <source srcset="overlay-split-view-dark.png" media="(prefers-color-scheme: dark)"> <img src="overlay-split-view.png" alt="overlay-split-view"> </picture> <picture> <source srcset="overlay-split-view-collapsed-dark.png" media="(prefers-color-scheme: dark)"> <img src="overlay-split-view-collapsed.png" alt="overlay-split-view-collapsed"> </picture> `AdwOverlaySplitView` has two children: sidebar and content, and displays them side by side. When [property@OverlaySplitView:collapsed] is set to `TRUE`, the sidebar is instead shown as an overlay above the content widget. The sidebar can be hidden or shown using the [property@OverlaySplitView:show-sidebar] property. Sidebar can be displayed before or after the content, this can be controlled with the [property@OverlaySplitView:sidebar-position] property. Collapsing the split view automatically hides the sidebar widget, and uncollapsing it shows the sidebar. If this behavior is not desired, the [property@OverlaySplitView:pin-sidebar] property can be used to override it. `AdwOverlaySplitView` supports an edge swipe gesture for showing the sidebar, and a swipe from the sidebar for hiding it. Gestures are only supported on touchscreen, but not touchpad. Gestures can be controlled with the [property@OverlaySplitView:enable-show-gesture] and [property@OverlaySplitView:enable-hide-gesture] properties. See also [class@NavigationSplitView]. `AdwOverlaySplitView` is typically used together with an [class@Breakpoint] setting the `collapsed` property to `TRUE` on small widths, as follows: ```xml <object class="AdwWindow"> <property name="default-width">800</property> <property name="default-height">800</property> <child> <object class="AdwBreakpoint"> <condition>max-width: 400sp</condition> <setter object="split_view" property="collapsed">True</setter> </object> </child> <property name="content"> <object class="AdwOverlaySplitView" id="split_view"> <property name="sidebar"> <!-- ... --> </property> <property name="content"> <!-- ... --> </property> </object> </property> </object> ``` `AdwOverlaySplitView` is often used for implementing the [utility pane](https://developer.gnome.org/hig/patterns/containers/utility-panes.html) pattern. ## Sizing When not collapsed, `AdwOverlaySplitView` changes the sidebar width depending on its own width. If possible, it tries to allocate a fraction of the total width, controlled with the [property@OverlaySplitView:sidebar-width-fraction] property. The sidebar also has minimum and maximum sizes, controlled with the [property@OverlaySplitView:min-sidebar-width] and [property@OverlaySplitView:max-sidebar-width] properties. The minimum and maximum sizes are using the length unit specified with the [property@OverlaySplitView:sidebar-width-unit]. By default, sidebar is using 25% of the total width, with 180sp as the minimum size and 280sp as the maximum size. When collapsed, the preferred width fraction is ignored and the sidebar uses [property@OverlaySplitView:max-sidebar-width] when possible. ## Header Bar Integration When used inside `AdwOverlaySplitView`, [class@HeaderBar] will automatically hide the window buttons in the middle. ## `AdwOverlaySplitView` as `GtkBuildable` The `AdwOverlaySplitView` implementation of the [iface@Gtk.Buildable] interface supports setting the sidebar widget by specifying “sidebar” as the “type” attribute of a `<child>` element, Specifying “content” child type or omitting it results in setting the content widget. ## CSS nodes `AdwOverlaySplitView` has a single CSS node with the name `overlay-split-view`. It contains two nodes with the name `widget`, containing the sidebar and content children. When not collapsed, they have the `.sidebar-view` and `.content-view` style classes respectively. ``` overlay-split-view ├── widget.sidebar-pane │ ╰── [sidebar child] ╰── widget.content-pane ╰── [content child] ``` When collapsed, the one containing the sidebar child has the `.background` style class and the other one has no style classes. ``` overlay-split-view ├── widget.background │ ╰── [sidebar child] ╰── widget ╰── [content child] ``` ## Accessibility `AdwOverlaySplitView` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. Creates a new `AdwOverlaySplitView`. the newly created `AdwOverlaySplitView` Gets whether @self is collapsed. whether @self is collapsed an overlay split view Gets the content widget for @self. the content widget for @self an overlay split view Gets whether @self can be closed with a swipe gesture. `TRUE` if @self can be closed with a swipe gesture an overlay split view Gets whether @self can be opened with an edge swipe gesture. `TRUE` if @self can be opened with a swipe gesture an overlay split view Gets the maximum sidebar width for @self. the maximum width an overlay split view Gets the minimum sidebar width for @self. the minimum width an overlay split view Gets whether the sidebar widget is pinned for @self. whether if the sidebar widget is pinned an overlay split view Gets whether the sidebar widget is shown for @self. `TRUE` if the sidebar widget is shown an overlay split view Gets the sidebar widget for @self. the sidebar widget for @self an overlay split view Gets the sidebar position for @self. the sidebar position for @self an overlay split view Gets the preferred sidebar width fraction for @self. the preferred width fraction an overlay split view Gets the length unit for minimum and maximum sidebar widths. the length unit an overlay split view Sets whether @self view is collapsed. When collapsed, the sidebar widget is presented as an overlay above the content widget, otherwise they are displayed side by side. an overlay split view whether @self is collapsed Sets the content widget for @self. an overlay split view the content widget Sets whether @self can be closed with a swipe gesture. Only touchscreen swipes are supported. an overlay split view whether @self can be closed with a swipe gesture Sets whether @self can be opened with an edge swipe gesture. Only touchscreen swipes are supported. an overlay split view whether @self can be opened with a swipe gesture Sets the maximum sidebar width for @self. Maximum width is affected by [property@OverlaySplitView:sidebar-width-unit]. The sidebar widget can still be allocated with larger width if its own minimum width exceeds it. an overlay split view the maximum width Sets the minimum sidebar width for @self. Minimum width is affected by [property@OverlaySplitView:sidebar-width-unit]. The sidebar widget can still be allocated with larger width if its own minimum width exceeds it. an overlay split view the minimum width Sets whether the sidebar widget is pinned for @self. By default, collapsing @self automatically hides the sidebar widget, and uncollapsing it shows the sidebar. If set to `TRUE`, sidebar visibility never changes on its own. an overlay split view whether to pin the sidebar widget Sets whether the sidebar widget is shown for @self. an overlay split view whether to show the sidebar widget Sets the sidebar widget for @self. an overlay split view the sidebar widget Sets the sidebar position for @self. If it's set to `GTK_PACK_START`, the sidebar is displayed before the content, if `GTK_PACK_END`, it's displayed after the content. an overlay split view the new position Sets the preferred sidebar width as a fraction of the total width of @self. The preferred width is additionally limited by [property@OverlaySplitView:min-sidebar-width] and [property@OverlaySplitView:max-sidebar-width]. The sidebar widget can be allocated with larger width if its own minimum width exceeds the preferred width. an overlay split view the preferred width fraction Sets the length unit for minimum and maximum sidebar widths. See [property@OverlaySplitView:min-sidebar-width] and [property@OverlaySplitView:max-sidebar-width]. an overlay split view the length unit Whether the split view is collapsed. When collapsed, the sidebar widget is presented as an overlay above the content widget, otherwise they are displayed side by side. The content widget. Whether the sidebar can be closed with a swipe gesture. Only touchscreen swipes are supported. Whether the sidebar can be opened with an edge swipe gesture. Only touchscreen swipes are supported. The maximum sidebar width. Maximum width is affected by [property@OverlaySplitView:sidebar-width-unit]. The sidebar widget can still be allocated with larger width if its own minimum width exceeds it. The minimum sidebar width. Minimum width is affected by [property@OverlaySplitView:sidebar-width-unit]. The sidebar widget can still be allocated with larger width if its own minimum width exceeds it. Whether the sidebar widget is pinned. By default, collapsing @self automatically hides the sidebar widget, and uncollapsing it shows the sidebar. If set to `TRUE`, sidebar visibility never changes on its own. Whether the sidebar widget is shown. The sidebar widget. The sidebar position. If it's set to `GTK_PACK_START`, the sidebar is displayed before the content, if `GTK_PACK_END`, it's displayed after the content. The preferred sidebar width as a fraction of the total width. The preferred width is additionally limited by [property@OverlaySplitView:min-sidebar-width] and [property@OverlaySplitView:max-sidebar-width]. The sidebar widget can be allocated with larger width if its own minimum width exceeds the preferred width. The length unit for minimum and maximum sidebar widths. See [property@OverlaySplitView:min-sidebar-width] and [property@OverlaySplitView:max-sidebar-width]. A [class@EntryRow] tailored for entering secrets. <picture> <source srcset="password-entry-row-dark.png" media="(prefers-color-scheme: dark)"> <img src="password-entry-row.png" alt="password-entry-row"> </picture> It does not show its contents in clear text, does not allow to copy it to the clipboard, and shows a warning when Caps Lock is engaged. If the underlying platform allows it, `AdwPasswordEntryRow` will also place the text in a non-pageable memory area, to avoid it being written out to disk by the operating system. It offer a way to reveal the contents in clear text. ## CSS Nodes `AdwPasswordEntryRow` has a single CSS node with name `row` that carries `.entry` and `.password` style classes. Creates a new `AdwPasswordEntryRow`. the newly created `AdwPasswordEntryRow` A dialog showing application's preferences. <picture> <source srcset="preferences-dialog-dark.png" media="(prefers-color-scheme: dark)"> <img src="preferences-dialog.png" alt="preferences-dialog"> </picture> The `AdwPreferencesDialog` widget presents an application's preferences gathered into pages and groups. The preferences are searchable by the user. ## CSS nodes `AdwPreferencesDialog` has a main CSS node with the name `dialog` and the style class `.preferences`. Creates a new `AdwPreferencesDialog`. the newly created `AdwPreferencesDialog` Adds a preferences page to @self. a preferences dialog the page to add Displays @toast. See [method@ToastOverlay.add_toast]. a preferences dialog a toast Gets whether search is enabled for @self. whether search is enabled for @self. a preferences dialog Gets the currently visible page of @self. the visible page a preferences dialog Gets the name of currently visible page of @self. the name of the visible page a preferences dialog Pop the visible page from the subpage stack of @self. `TRUE` if a page has been popped a preferences dialog Pushes @page onto the subpage stack of @self. The page will be automatically removed when popped. a preferences dialog the subpage Removes a page from @self. a preferences dialog the page to remove Sets whether search is enabled for @self. a preferences dialog whether search is enabled Makes @page the visible page of @self. a preferences dialog a page of @self Makes the page with the given name visible. See [property@PreferencesDialog:visible-page]. a preferences dialog the name of the page to make visible Whether search is enabled. The currently visible page. The name of the currently visible page. See [property@AdwPreferencesDialog:visible-page]. The parent class A group of preference rows. <picture> <source srcset="preferences-group-dark.png" media="(prefers-color-scheme: dark)"> <img src="preferences-group.png" alt="preferences-group"> </picture> An `AdwPreferencesGroup` represents a group or tightly related preferences, which in turn are represented by [class@PreferencesRow]. To summarize the role of the preferences it gathers, a group can have both a title and a description. The title will be used by [class@PreferencesDialog] to let the user look for a preference. The [property@PreferencesGroup:separate-rows] property can be used to separate the rows within the group, same as when using the [`.boxed-list-separate`](style-classes.html#boxed-lists-cards) style class instead of `.boxed-list`. ## AdwPreferencesGroup as GtkBuildable The `AdwPreferencesGroup` implementation of the [iface@Gtk.Buildable] interface supports adding [class@PreferencesRow]s to the list by omitting "type". If "type" is omitted and the widget isn't a [class@PreferencesRow] the child is added to a box below the list. When the "type" attribute of a child is `header-suffix`, the child is set as the suffix on the end of the title and description. ## CSS nodes `AdwPreferencesGroup` has a single CSS node with name `preferencesgroup`. ## Accessibility `AdwPreferencesGroup` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. Creates a new `AdwPreferencesGroup`. the newly created `AdwPreferencesGroup` Adds a child to @self. a preferences group the widget to add Gets the description of @self. the description of @self a preferences group Gets the suffix for @self's header. the suffix for @self's header. a preferences group Gets whether @self's rows are separated. whether rows are separated a preferences group Gets the title of @self. the title of @self a preferences group Removes a child from @self. a preferences group the child to remove Sets the description for @self. a preferences group the description Sets the suffix for @self's header. Displayed above the list, next to the title and description. Suffixes are commonly used to show a button or a spinner for the whole group. a preferences group the suffix to set Sets whether @self's rows are separated. Equivalent to using the [`.boxed-list-separate`](style-classes.html#boxed-lists-cards) style class on a [class@Gtk.ListBox] instead of `.boxed-list`. a preferences group whether to separate rows Sets the title for @self. a preferences group the title The description for this group of preferences. The header suffix widget. Displayed above the list, next to the title and description. Suffixes are commonly used to show a button or a spinner for the whole group. Whether to separate rows. Equivalent to using the [`.boxed-list-separate`](style-classes.html#boxed-lists-cards) style class on a [class@Gtk.ListBox] instead of `.boxed-list`. The title for this group of preferences. The parent class A page from [class@PreferencesDialog]. <picture> <source srcset="preferences-page-dark.png" media="(prefers-color-scheme: dark)"> <img src="preferences-page.png" alt="preferences-page"> </picture> The `AdwPreferencesPage` widget gathers preferences groups into a single page of a preferences window. ## CSS nodes `AdwPreferencesPage` has a single CSS node with name `preferencespage`. ## Accessibility `AdwPreferencesPage` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. Creates a new `AdwPreferencesPage`. the newly created `AdwPreferencesPage` Adds a preferences group to @self. a preferences page the group to add Gets the description of @self. the description of @self. a preferences page Gets whether the description is centered. whether the description is centered. a preferences page Gets the icon name for @self. the icon name for @self a preferences page Gets the name of @self. the name of @self a preferences page Gets the title of @self. the title of @self. a preferences page Gets whether an embedded underline in the title indicates a mnemonic. whether an embedded underline in the title indicates a mnemonic a preferences page Removes a group from @self. a preferences page the group to remove Scrolls the scrolled window of @self to the top. a preferences page Sets the description of @self. The description is displayed at the top of the page. a preferences page the description Sets whether the description should be centered. a preferences page If the description should be centered Sets the icon name for @self. a preferences page the icon name Sets the name of @self. a preferences page the name Sets the title of @self. a preferences page the title Sets whether an embedded underline in the title indicates a mnemonic. a preferences page `TRUE` if underlines in the text indicate mnemonics The description to be displayed at the top of the page. Whether the description should be centered. The icon name for this page. The name of this page. The title for this page. Whether an embedded underline in the title indicates a mnemonic. The parent class A [class@Gtk.ListBoxRow] used to present preferences. The `AdwPreferencesRow` widget has a title that [class@PreferencesDialog] will use to let the user look for a preference. It doesn't present the title in any way and lets you present the preference as you please. [class@ActionRow] and its derivatives are convenient to use as preference rows as they take care of presenting the preference's title while letting you compose the inputs of the preference around it. Creates a new `AdwPreferencesRow`. the newly created `AdwPreferencesRow` Gets the title of the preference represented by @self. the title a preferences row Gets whether the user can copy the title from the label whether the user can copy the title from the label a preferences row Gets whether to use Pango markup for the title label. whether to use markup a preferences row Gets whether an embedded underline in the title indicates a mnemonic. whether an embedded underline in the title indicates a mnemonic a preferences row Sets the title of the preference represented by @self. The title is interpreted as Pango markup unless [property@PreferencesRow:use-markup] is set to `FALSE`. a preferences row the title Sets whether the user can copy the title from the label See also [property@Gtk.Label:selectable]. a preferences row `TRUE` if the user can copy the title from the label Sets whether to use Pango markup for the title label. Subclasses may also use it for other labels, such as subtitle. See also [func@Pango.parse_markup]. a preferences row whether to use markup Sets whether an embedded underline in the title indicates a mnemonic. a preferences row `TRUE` if underlines in the text indicate mnemonics The title of the preference represented by this row. The title is interpreted as Pango markup unless [property@PreferencesRow:use-markup] is set to `FALSE`. Whether the user can copy the title from the label. See also [property@Gtk.Label:selectable]. Whether to use Pango markup for the title label. Subclasses may also use it for other labels, such as subtitle. See also [func@Pango.parse_markup]. Whether an embedded underline in the title indicates a mnemonic. The parent class A window to present an application's preferences. <picture> <source srcset="preferences-window-dark.png" media="(prefers-color-scheme: dark)"> <img src="preferences-window.png" alt="preferences-window"> </picture> The `AdwPreferencesWindow` widget presents an application's preferences gathered into pages and groups. The preferences are searchable by the user. ## CSS nodes `AdwPreferencesWindow` has a main CSS node with the name `window` and the style class `.preferences`. Use [class@PreferencesDialog]. Creates a new `AdwPreferencesWindow`. Use [class@PreferencesDialog]. the newly created `AdwPreferencesWindow` Adds a preferences page to @self. Use [class@PreferencesDialog]. a preferences window the page to add Displays @toast. See [method@ToastOverlay.add_toast]. Use [class@PreferencesDialog]. a preferences window a toast Closes the current subpage. If there is no presented subpage, this does nothing. Use [method@PreferencesWindow.pop_subpage] instead. a preferences window Gets whether gestures and shortcuts for closing subpages are enabled. Use [method@NavigationPage.get_can_pop] instead. whether gestures and shortcuts are enabled. a preferences window Gets whether search is enabled for @self. Use [class@PreferencesDialog]. whether search is enabled for @self. a preferences window Gets the currently visible page of @self. Use [class@PreferencesDialog]. the visible page a preferences window Gets the name of currently visible page of @self. Use [class@PreferencesDialog]. the name of the visible page a preferences window Pop the visible page from the subpage stack of @self. Use [class@PreferencesDialog]. `TRUE` if a page has been popped a preferences window Sets @subpage as the window's subpage and opens it. The transition can be cancelled by the user, in which case visible child will change back to the previously visible child. Use [method@PreferencesWindow.push_subpage] instead. a preferences window the subpage Pushes @page onto the subpage stack of @self. The page will be automatically removed when popped. Use [class@PreferencesDialog]. a preferences window the subpage Removes a page from @self. Use [class@PreferencesDialog]. a preferences window the page to remove Sets whether gestures and shortcuts for closing subpages are enabled. The supported gestures are: - One-finger swipe on touchscreens - Horizontal scrolling on touchpads (usually two-finger swipe) - Back mouse button The keyboard back key is also supported, as well as the <kbd>Alt</kbd>+<kbd>←</kbd> shortcut. For right-to-left locales, gestures and shortcuts are reversed. Has no effect for subpages added with [method@PreferencesWindow.push_subpage]. Use [method@NavigationPage.set_can_pop] instead. a preferences window the new value Sets whether search is enabled for @self. Use [class@PreferencesDialog]. a preferences window whether search is enabled Makes @page the visible page of @self. Use [class@PreferencesDialog]. a preferences window a page of @self Makes the page with the given name visible. See [property@PreferencesWindow:visible-page]. Use [class@PreferencesDialog]. a preferences window the name of the page to make visible Whether gestures and shortcuts for closing subpages are enabled. The supported gestures are: - One-finger swipe on touchscreens - Horizontal scrolling on touchpads (usually two-finger swipe) - Back mouse button The keyboard back key is also supported, as well as the <kbd>Alt</kbd>+<kbd>←</kbd> shortcut. For right-to-left locales, gestures and shortcuts are reversed. Has no effect for subpages added with [method@PreferencesWindow.push_subpage]. Use [property@NavigationPage:can-pop] instead. Whether search is enabled. Use [class@PreferencesDialog]. The currently visible page. Use [class@PreferencesDialog]. The name of the currently visible page. See [property@PreferencesWindow:visible-page]. Use [class@PreferencesDialog]. The parent class An [class@AnimationTarget] changing the value of a property of a [class@GObject.Object] instance. Creates a new `AdwPropertyAnimationTarget` for the @property_name property on @object. the newly created `AdwPropertyAnimationTarget` an object to be animated the name of the property on @object to animate Creates a new `AdwPropertyAnimationTarget` for the @pspec property on @object. new newly created `AdwPropertyAnimationTarget` an object to be animated the param spec of the property on @object to animate Gets the object animated by @self. The `AdwPropertyAnimationTarget` instance does not hold a strong reference on the object; make sure the object is kept alive throughout the target's lifetime. the animated object a property animation target Gets the `GParamSpec` of the property animated by @self. the animated property's `GParamSpec` a property animation target The object whose property will be animated. The `AdwPropertyAnimationTarget` instance does not hold a strong reference on the object; make sure the object is kept alive throughout the target's lifetime. The `GParamSpec` of the property to be animated. Describes the possible styles of [class@AlertDialog] response buttons. See [method@AlertDialog.set_response_appearance]. the default appearance. used to denote important responses such as the affirmative action. used to draw attention to the potentially damaging consequences of using the response. This appearance acts as a warning to the user. An [class@ActionRow] with an embedded spin button. <picture> <source srcset="spin-row-dark.png" media="(prefers-color-scheme: dark)"> <img src="spin-row.png" alt="spin-row"> </picture> Example of an `AdwSpinRow` UI definition: ```xml <object class="AdwSpinRow"> <property name="title" translatable="yes">Spin Row</property> <property name="adjustment"> <object class="GtkAdjustment"> <property name="lower">0</property> <property name="upper">100</property> <property name="value">50</property> <property name="page-increment">10</property> <property name="step-increment">1</property> </object> </property> </object> ``` See [class@Gtk.SpinButton] for details. ## CSS nodes `AdwSpinRow` has the same structure as [class@ActionRow], as well as the `.spin` style class on the main node. ## Accessibility `AdwSpinRow` uses an internal `GtkSpinButton` with the `GTK_ACCESSIBLE_ROLE_SPIN_BUTTON` role. Creates a new `AdwSpinRow`. the newly created `AdwSpinRow` the adjustment that this spin row should use the rate the value changes when holding a button or key the number of decimal places to display Creates a new `AdwSpinRow` with the given properties. This is a convenience constructor that allows creation of a numeric `AdwSpinRow` 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 row is equivalent to the precisions of @step. ::: note 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@SpinRow.set_digits] to correct it. the new `AdwSpinRow` minimum allowable value maximum allowable value increment added or subtracted by spinning the widget Changes the properties of an existing spin row. The adjustment, climb rate, and number of decimal places are updated accordingly. a spin row the adjustment that this spin row should use the new climb rate the number of decimal places to display Gets the adjustment that holds the value for the spin row. the adjustment that holds the spin row's value a spin row Gets the acceleration rate when you hold down a button or key. the acceleration rate when you hold down a button or key a spin row Gets the number of decimal places to display. the number of decimal places to display a spin row Gets whether non-numeric characters should be ignored. whether non-numeric characters should be ignored. a spin row Gets whether invalid values are snapped to nearest step increment. whether invalid values are snapped to the nearest step increment a spin row Gets the policy for updating the spin row. the policy for updating the spin row a spin row Gets the current value. the current value a spin row Gets whether the spin row should wrap upon reaching its limits. whether the spin row should wrap upon reaching its limits a spin row Sets the adjustment that holds the value for the spin row. a spin row an adjustment Sets the acceleration rate when you hold down a button or key. a spin row the acceleration rate when you hold down a button or key Sets the number of decimal places to display. a spin row the number of decimal places to display Sets whether non-numeric characters should be ignored. a spin row whether non-numeric characters should be ignored Sets the minimum and maximum allowable values for @self. If the current value is outside this range, it will be adjusted to fit within the range, otherwise it will remain unchanged. a spin row minimum allowable value maximum allowable value Sets whether invalid values are snapped to the nearest step increment. a spin row whether invalid values are snapped to the nearest step increment Sets the policy for updating the spin row. The options are always, or only when the value is invalid. a spin row the policy for updating the spin row Sets the current value. a spin row a new value Sets whether the spin row should wrap upon reaching its limits. a spin row whether the spin row should wrap upon reaching its limits Manually force an update of the spin row. a spin row The adjustment that holds the value of the spin row. 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 invalid values are snapped to the nearest step increment. The policy for updating the spin row. The options are always, or only when the value is invalid. The current value. Whether the spin row should wrap upon reaching its limits. Emitted to convert the user's 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 [func@GLib.strtod]. See [signal@Gtk.SpinButton::input]. `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. See [signal@Gtk.SpinButton::output]. `TRUE` if the value has been displayed Emitted right after the spinbutton wraps. See [signal@Gtk.SpinButton::wrapped]. A widget showing a loading spinner. <picture> <source srcset="spinner-dark.png" media="(prefers-color-scheme: dark)"> <img src="spinner.png" alt="spinner"> </picture> The size of the spinner depends on the available size, never smaller than 16×16 pixels and never larger than 64×64 pixels. Use the [property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties in combination with [property@Gtk.Widget:width-request] and [property@Gtk.Widget:height-request] for fine sizing control. For example, the following snippet shows the spinner at 48×48 pixels: ```xml <object class="AdwSpinner"> <property name="halign">center</property> <property name="valign">center</property> <property name="width-request">48</property> <property name="height-request">48</property> </object> ``` See [class@SpinnerPaintable] for cases where using a widget is impractical or impossible, such as [property@StatusPage:paintable]. ## CSS nodes `AdwSpinner` has a single node with the name `image` and the style class `.spinner`. Creates a new `AdwSpinner`. the newly created `AdwSpinner` A paintable showing a loading spinner. <picture> <source srcset="spinner-dark.png" media="(prefers-color-scheme: dark)"> <img src="spinner.png" alt="spinner"> </picture> `AdwSpinnerPaintable` size varies depending on the available space, but is capped at 64×64 pixels. To be able to animate, `AdwSpinnerPaintable` needs a widget. It will be animated according to that widget's frame clock, and only if that widget is mapped. Ideally it should be the same widget the paintable is displayed in, but that's not a requirement. Most applications should be using [class@Spinner] instead. `AdwSpinnerPaintable` is provided for the cases where using a widget is impractical or impossible, such as [property@StatusPage:paintable]: ```xml <object class="AdwStatusPage" id="status_page"> <property name="paintable"> <object class="AdwSpinnerPaintable"> <property name="widget">status_page</property> </object> </property> <!-- ... --> </object> ``` Creates a new `AdwSpinnerPaintable` for @widget. the newly created `AdwSpinnerPaintable` the widget used for frame clock Gets the widget used for frame clock. the widget a spinner paintable Sets the widget used for frame clock. a spinner paintable the widget to use for frame clock The widget the spinner uses for frame clock. A combined button and dropdown widget. <picture> <source srcset="split-button-dark.png" media="(prefers-color-scheme: dark)"> <img src="split-button.png" alt="split-button"> </picture> `AdwSplitButton` is typically used to present a set of actions in a menu, but allow access to one of them with a single click. The API is very similar to [class@Gtk.Button] and [class@Gtk.MenuButton], see their documentation for details. ## CSS nodes ``` splitbutton[.image-button][.text-button] ├── button │ ╰── <content> ├── separator ╰── menubutton ╰── button.toggle ╰── arrow ``` `AdwSplitButton`'s CSS node is called `splitbutton`. It contains the css nodes: `button`, `separator`, `menubutton`. See [class@Gtk.MenuButton] documentation for the `menubutton` contents. The main CSS node will contain the `.image-button` or `.text-button` style classes matching the button contents. The nested button nodes will never contain them. ## Accessibility `AdwSplitButton` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. Creates a new `AdwSplitButton`. the newly created `AdwSplitButton` gets whether the button can be smaller than the natural size of its contents. whether the button can shrink a split button Gets the child widget. the child widget a split button Gets the direction in which the popup will be popped up. the direction a split button Gets the tooltip of the dropdown button of @self. the dropdown tooltip of @self a split button Gets the name of the icon used to automatically populate the button. the icon name a split button Gets the label for @self. the label for @self a split button Gets the menu model from which the popup will be created. the menu model a split button Gets the popover that will be popped up when the dropdown is clicked. the popover a split button Gets whether an underline in the text indicates a mnemonic. whether an underline in the text indicates a mnemonic a split button Dismisses the menu. a split button Pops up the menu. a split button Sets whether the button can be smaller than the natural size of its contents. If set to `TRUE`, the label will ellipsize. See [method@Gtk.Button.set_can_shrink] and [method@Gtk.MenuButton.set_can_shrink]. a split button whether the button can shrink Sets the child widget. Setting the child widget will set [property@SplitButton:label] and [property@SplitButton:icon-name] to `NULL`. a split button the new child widget Sets the direction in which the popup will be popped up. The dropdown arrow icon will point at the same direction. If the does not fit in the available space in the given direction, GTK will try its best to keep it inside the screen and fully visible. If you pass `GTK_ARROW_NONE`, it's equivalent to `GTK_ARROW_DOWN`. a split button the direction Sets the tooltip of the dropdown button of @self. The tooltip can be marked up with the Pango text markup language. a split button the dropdown tooltip of @self Sets the name of the icon used to automatically populate the button. Setting the icon name will set [property@SplitButton:label] and [property@SplitButton:child] to `NULL`. a split button the icon name to set Sets the label for @self. Setting the label will set [property@SplitButton:icon-name] and [property@SplitButton:child] to `NULL`. a split button the label to set Sets the menu model from which the popup will be created. If the menu model is `NULL`, the dropdown 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@SplitButton:popover] is already set, it will be dissociated from the button, and the property is set to `NULL`. a split button the menu model Sets the popover that will be popped up when the dropdown is clicked. If the popover is `NULL`, the dropdown is disabled. If [property@SplitButton:menu-model] is set, the menu model is dissociated from the button, and the property is set to `NULL`. a split button the popover Sets whether an underline in the text indicates a mnemonic. See [property@SplitButton:label]. a split button whether an underline in the text indicates a mnemonic Whether the button can be smaller than the natural size of its contents. If set to `TRUE`, the label will ellipsize. See [property@Gtk.Button:can-shrink] and [property@Gtk.MenuButton:can-shrink]. The child widget. Setting the child widget will set [property@SplitButton:label] and [property@SplitButton:icon-name] to `NULL`. The direction in which the popup will be popped up. The dropdown arrow icon will point at the same direction. If the does not fit in the available space in the given direction, GTK will try its best to keep it inside the screen and fully visible. If you pass `GTK_ARROW_NONE`, it's equivalent to `GTK_ARROW_DOWN`. The tooltip of the dropdown button. The tooltip can be marked up with the Pango text markup language. The name of the icon used to automatically populate the button. Setting the icon name will set [property@SplitButton:label] and [property@SplitButton:child] to `NULL`. The label for the button. Setting the label will set [property@SplitButton:icon-name] and [property@SplitButton:child] to `NULL`. The `GMenuModel` from which the popup will be created. If the menu model is `NULL`, the dropdown 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@SplitButton:popover] is already set, it will be dissociated from the button, and the property is set to `NULL`. The `GtkPopover` that will be popped up when the dropdown is clicked. If the popover is `NULL`, the dropdown is disabled. If [property@SplitButton:menu-model] is set, the menu model is dissociated from the button, and the property is set to `NULL`. Whether an underline in the text indicates a mnemonic. See [property@SplitButton:label]. Emitted to animate press then release. This is an action signal. Applications should never connect to this signal, but use the [signal@SplitButton::clicked] signal. Emitted when the button has been activated (pressed and released). A spring-based [class@Animation]. `AdwSpringAnimation` implements an animation driven by a physical model of a spring described by [struct@SpringParams], with a resting position in [property@SpringAnimation:value-to], stretched to [property@SpringAnimation:value-from]. Since the animation is physically simulated, spring animations don't have a fixed duration. The animation will stop when the simulated spring comes to a rest - when the amplitude of the oscillations becomes smaller than [property@SpringAnimation:epsilon], or immediately when it reaches [property@SpringAnimation:value-to] if [property@SpringAnimation:clamp] is set to `TRUE`. The estimated duration can be obtained with [property@SpringAnimation:estimated-duration]. Due to the nature of spring-driven motion the animation can overshoot [property@SpringAnimation:value-to] before coming to a rest. Whether the animation will overshoot or not depends on the damping ratio of the spring. See [struct@SpringParams] for more information about specific damping ratio values. If [property@SpringAnimation:clamp] is `TRUE`, the animation will abruptly end as soon as it reaches the final value, preventing overshooting. Animations can have an initial velocity value, set via [property@SpringAnimation:initial-velocity], which adjusts the curve without changing the duration. This makes spring animations useful for deceleration at the end of gestures. If the initial and final values are equal, and the initial velocity is not 0, the animation value will bounce and return to its resting position. Creates a new `AdwSpringAnimation` on @widget. The animation will animate @target from @from to @to with the dynamics of a spring described by @spring_params. the newly created animation a widget to create animation on a value to animate from a value to animate to physical parameters of the spring a target value to animate Calculates the value @self will have at @time. The time starts at 0 and ends at [property@SpringAnimation:estimated_duration]. See also [method@SpringAnimation.calculate_velocity]. the value at @time a spring animation elapsed time, in milliseconds Calculates the velocity @self will have at @time. The time starts at 0 and ends at [property@SpringAnimation:estimated_duration]. See also [method@SpringAnimation.calculate_value]. the velocity at @time a spring animation elapsed time, in milliseconds Gets whether @self should be clamped. whether @self is clamped a spring animation Gets the precision of the spring. the epsilon value a spring animation Gets the estimated duration of @self, in milliseconds. Can be [const@DURATION_INFINITE] if the spring damping is set to 0. the estimated duration a spring animation Gets the initial velocity of @self. the initial velocity a spring animation Gets the physical parameters of the spring of @self. the spring parameters a spring animation Gets the value @self will animate from. the value to animate from a spring animation Gets the value @self will animate to. the value to animate to a spring animation Gets the current velocity of @self. the current velocity a spring animation Sets whether @self should be clamped. If set to `TRUE`, the animation will abruptly end as soon as it reaches the final value, preventing overshooting. It won't prevent overshooting [property@SpringAnimation:value-from] if a relative negative [property@SpringAnimation:initial-velocity] is set. a spring animation the new value Sets the precision of the spring. The level of precision used to determine when the animation has come to a rest, that is, when the amplitude of the oscillations becomes smaller than this value. If the epsilon value is too small, the animation will take a long time to stop after the animated value has stopped visibly changing. If the epsilon value is too large, the animation will end prematurely. The default value is 0.001. a spring animation the new value Sets the initial velocity of @self. Initial velocity affects only the animation curve, but not its duration. a spring animation the initial velocity Sets the physical parameters of the spring of @self. a spring animation the new spring parameters Sets the value @self will animate from. The animation will start at this value and end at [property@SpringAnimation:value-to]. a spring animation the value to animate from Sets the value @self will animate to. The animation will start at [property@SpringAnimation:value-from] and end at this value. a spring animation the value to animate to Whether the animation should be clamped. If set to `TRUE`, the animation will abruptly end as soon as it reaches the final value, preventing overshooting. It won't prevent overshooting [property@SpringAnimation:value-from] if a relative negative [property@SpringAnimation:initial-velocity] is set. Precision of the spring. The level of precision used to determine when the animation has come to a rest, that is, when the amplitude of the oscillations becomes smaller than this value. If the epsilon value is too small, the animation will take a long time to stop after the animated value has stopped visibly changing. If the epsilon value is too large, the animation will end prematurely. The default value is 0.001. Estimated duration of the animation, in milliseconds. Can be [const@DURATION_INFINITE] if the spring damping is set to 0. The initial velocity to start the animation with. Initial velocity affects only the animation curve, but not its duration. Physical parameters describing the spring. The value to animate from. The animation will start at this value and end at [property@SpringAnimation:value-to]. The value to animate to. The animation will start at [property@SpringAnimation:value-from] and end at this value. Current velocity of the animation. Physical parameters of a spring for [class@SpringAnimation]. Any spring can be described by three parameters: mass, stiffness and damping. An undamped spring will produce an oscillatory motion which will go on forever. The frequency and amplitude of the oscillations will be determined by the stiffness (how "strong" the spring is) and its mass (how much "inertia" it has). If damping is larger than 0, the amplitude of that oscillating motion will exponientally decrease over time. If that damping is strong enough that the spring can't complete a full oscillation, it's called an overdamped spring. If we the spring can oscillate, it's called an underdamped spring. The value between these two behaviors is called critical damping; a critically damped spring will comes to rest in the minimum possible time without producing oscillations. The damping can be replaced by damping ratio, which produces the following springs: * 0: an undamped spring. * Between 0 and 1: an underdamped spring. * 1: a critically damped spring. * Larger than 1: an overdamped spring. As such Creates a new `AdwSpringParams` from @mass, @stiffness and @damping_ratio. The damping value is calculated from @damping_ratio and the other two parameters. * If @damping_ratio is 0, the spring will not be damped and will oscillate endlessly. * If @damping_ratio is between 0 and 1, the spring is underdamped and will always overshoot. * If @damping_ratio is 1, the spring is critically damped and will reach its resting position the quickest way possible. * If @damping_ratio is larger than 1, the spring is overdamped and will reach its resting position faster than it can complete an oscillation. [ctor@SpringParams.new_full] allows to pass a raw damping value instead. the newly created spring parameters the damping ratio of the spring the mass of the spring the stiffness of the spring Creates a new `AdwSpringParams` from @mass, @stiffness and @damping. See [ctor@SpringParams.new] for a simplified constructor using damping ratio instead of @damping. the newly created spring parameters the damping of the spring the mass of the spring the stiffness of the spring Gets the damping of @self. the damping spring params Gets the damping ratio of @self. the damping ratio spring params Gets the mass of @self. the mass spring params Gets the stiffness of @self. the stiffness spring params Increases the reference count of @self. @self spring params Decreases the reference count of @self. If the last reference is dropped, the structure is freed. spring params A best fit container. <picture> <source srcset="squeezer-wide-dark.png" media="(prefers-color-scheme: dark)"> <img src="squeezer-wide.png" alt="squeezer-wide"> </picture> <picture> <source srcset="squeezer-narrow-dark.png" media="(prefers-color-scheme: dark)"> <img src="squeezer-narrow.png" alt="squeezer-narrow"> </picture> The `AdwSqueezer` widget is a container which only shows the first of its children that fits in the available size. It is convenient to offer different widgets to represent the same data with different levels of detail, making the widget seem to squeeze itself to fit in the available space. Transitions between children can be animated as fades. This can be controlled with [property@Squeezer:transition-type]. ## CSS nodes `AdwSqueezer` has a single CSS node with name `squeezer`. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) Creates a new `AdwSqueezer`. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) the newly created `AdwSqueezer` Adds a child to @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) the [class@SqueezerPage] for @child a squeezer the widget to add Gets whether to allow squeezing beyond the last child's minimum size. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) whether @self allows squeezing beyond the last child a squeezer Gets whether all children have the same size for the opposite orientation. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) whether @self is homogeneous a squeezer Gets whether @self interpolates its size when changing the visible child. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) whether the size is interpolated A squeezer Returns the [class@SqueezerPage] object for @child. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) the page object for @child a squeezer a child of @self Returns a [iface@Gio.ListModel] that contains the pages of @self. This can be used to keep an up-to-date view. The model also implements [iface@Gtk.SelectionModel] and can be used to track the visible page. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) a `GtkSelectionModel` for the squeezer's children a squeezer Gets the switch threshold policy for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) the fold threshold policy a squeezer Gets the transition animation duration for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) the transition duration, in milliseconds a squeezer Gets whether a transition is currently running for @self. If a transition is impossible, the property value will be set to `TRUE` and then immediately to `FALSE`, so it's possible to rely on its notifications to know that a transition has happened. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) whether a transition is currently running a squeezer Gets the type of animation used for transitions between children in @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) the current transition type of @self a squeezer Gets the currently visible child of @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) the visible child a squeezer Gets the horizontal alignment, from 0 (start) to 1 (end). See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) the alignment value a squeezer Gets the vertical alignment, from 0 (top) to 1 (bottom). See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) the alignment value a squeezer Removes a child widget from @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) a squeezer the child to remove Sets whether to allow squeezing beyond the last child's minimum size. If set to `TRUE`, the squeezer can shrink to the point where no child can be shown. This is functionally equivalent to appending a widget with 0×0 minimum size. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) a squeezer whether @self allows squeezing beyond the last child Sets whether all children have the same size for the opposite orientation. For example, if a squeezer is horizontal and is homogeneous, it will request the same height for all its children. If it isn't, the squeezer may change size when a different child becomes visible. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) a squeezer whether @self is homogeneous Sets whether @self interpolates its size when changing the visible child. If `TRUE`, the squeezer will interpolate its size between the one of the previous visible child and the one of the new visible child, according to the set transition duration and the orientation, e.g. if the squeezer is horizontal, it will interpolate the its height. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) A squeezer whether to interpolate the size Sets the switch threshold policy for @self. Determines when the squeezer will switch children. If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only switch when the visible child cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it will switch as soon as the visible child doesn't get their natural size. This can be useful if you have a long ellipsizing label and want to let it ellipsize instead of immediately switching. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) a squeezer the policy to use Sets the transition animation duration for @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) a squeezer the new duration, in milliseconds Sets the type of animation used for transitions between children in @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) a squeezer the new transition type Sets the horizontal alignment, from 0 (start) to 1 (end). This affects the children allocation during transitions, when they exceed the size of the squeezer. For example, 0.5 means the child will be centered, 0 means it will keep the start side aligned and overflow the end side, and 1 means the opposite. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) a squeezer the new alignment value Sets the vertical alignment, from 0 (top) to 1 (bottom). This affects the children allocation during transitions, when they exceed the size of the squeezer. For example, 0.5 means the child will be centered, 0 means it will keep the top side aligned and overflow the bottom side, and 1 means the opposite. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) a squeezer the new alignment value Whether to allow squeezing beyond the last child's minimum size. If set to `TRUE`, the squeezer can shrink to the point where no child can be shown. This is functionally equivalent to appending a widget with 0×0 minimum size. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) Whether all children have the same size for the opposite orientation. For example, if a squeezer is horizontal and is homogeneous, it will request the same height for all its children. If it isn't, the squeezer may change size when a different child becomes visible. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) Whether the squeezer interpolates its size when changing the visible child. If `TRUE`, the squeezer will interpolate its size between the one of the previous visible child and the one of the new visible child, according to the set transition duration and the orientation, e.g. if the squeezer is horizontal, it will interpolate the its height. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) A selection model with the squeezer's pages. This can be used to keep an up-to-date view. The model also implements [iface@Gtk.SelectionModel] and can be used to track the visible page. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) The switch threshold policy. Determines when the squeezer will switch children. If set to `ADW_FOLD_THRESHOLD_POLICY_MINIMUM`, it will only switch when the visible child cannot fit anymore. With `ADW_FOLD_THRESHOLD_POLICY_NATURAL`, it will switch as soon as the visible child doesn't get their natural size. This can be useful if you have a long ellipsizing label and want to let it ellipsize instead of immediately switching. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) The transition animation duration, in milliseconds. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) Whether a transition is currently running. If a transition is impossible, the property value will be set to `TRUE` and then immediately to `FALSE`, so it's possible to rely on its notifications to know that a transition has happened. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) The type of animation used for transitions between children. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) The currently visible child. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) The horizontal alignment, from 0 (start) to 1 (end). This affects the children allocation during transitions, when they exceed the size of the squeezer. For example, 0.5 means the child will be centered, 0 means it will keep the start side aligned and overflow the end side, and 1 means the opposite. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) The vertical alignment, from 0 (top) to 1 (bottom). This affects the children allocation during transitions, when they exceed the size of the squeezer. For example, 0.5 means the child will be centered, 0 means it will keep the top side aligned and overflow the bottom side, and 1 means the opposite. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) An auxiliary class used by [class@Squeezer]. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) Returns the squeezer child to which @self belongs. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) the child to which @self belongs a squeezer page Gets whether @self is enabled. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) whether @self is enabled a squeezer page Sets whether @self is enabled. If a child is disabled, it will be ignored when looking for the child fitting the available size best. This allows to programmatically and prematurely hide a child even if it fits in the available space. This can be used e.g. to ensure a certain child is hidden below a certain window width, or any other constraint you find suitable. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) a squeezer page whether @self is enabled The the squeezer child to which the page belongs. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) Whether the child is enabled. If a child is disabled, it will be ignored when looking for the child fitting the available size best. This allows to programmatically and prematurely hide a child even if it fits in the available space. This can be used e.g. to ensure a certain child is hidden below a certain window width, or any other constraint you find suitable. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) Describes the possible transitions in a [class@Squeezer] widget. See [the migration guide](migrating-to-breakpoints.html#replace-adwsqueezer) No transition A cross-fade A page used for empty/error states and similar use-cases. <picture> <source srcset="status-page-dark.png" media="(prefers-color-scheme: dark)"> <img src="status-page.png" alt="status-page"> </picture> The `AdwStatusPage` widget can have an icon, a title, a description and a custom widget which is displayed below them. ## CSS nodes `AdwStatusPage` has a main CSS node with name `statuspage`. `AdwStatusPage` can use the [`.compact`](style-classes.html#compact-status-page) style class for when it needs to fit into a small space such a sidebar or a popover. When setting an [class@SpinnerPaintable] as [property@StatusPage:paintable], the main nodes gains the `.spinner` style class for a more compact appearance, similar to `.compact`. Creates a new `AdwStatusPage`. the newly created `AdwStatusPage` Gets the child widget of @self. the child widget of @self a status page Gets the description markup for @self. the description a status page Gets the icon name for @self. the icon name a status page Gets the paintable for @self. the paintable a status page Gets the title for @self. the title a status page Sets the child widget of @self. a status page the child widget Sets the description markup for @self. The description is displayed below the title. It is parsed as Pango markup. a status page the description Sets the icon name for @self. Changing this will set [property@StatusPage:paintable] to `NULL`. a status page the icon name Sets the paintable for @self. Changing this will set [property@StatusPage:icon-name] to `NULL`. a status page the paintable Sets the title for @self. The title is displayed below the icon. It is not parsed as Pango markup. a status page the title The child widget. The description markup to be displayed below the title. The name of the icon to be used. Changing this will set [property@StatusPage:paintable] to `NULL`. The paintable to be used. Changing this will set [property@StatusPage:icon-name] to `NULL`. The title to be displayed below the icon. It is not parsed as Pango markup. A class for managing application-wide styling. `AdwStyleManager` provides a way to query and influence the application styles, such as whether to use dark style, the system accent color or high contrast appearance. It allows to set the color scheme via the [property@StyleManager:color-scheme] property, and to query the current appearance, as well as whether a system-wide color scheme and accent color preferences exists. Gets the default `AdwStyleManager` instance. It manages all [class@Gdk.Display] instances unless the style manager for that display has an override. See [func@StyleManager.get_for_display]. the default style manager Gets the `AdwStyleManager` instance managing @display. It can be used to override styles for that specific display instead of the whole application. Most applications should use [func@StyleManager.get_default] instead. the style manager for @display a `GdkDisplay` Gets the current system accent color. See also [property@StyleManager:accent-color-rgba]. the current system accent color a style manager Gets the current system accent color as a `GdkRGBA`. Equivalent to calling [func@AccentColor.to_rgba] on the value of [property@StyleManager:accent-color]. This is a background color. The matching foreground color is white. the current system accent color a style manager Gets the requested application color scheme. the color scheme a style manager Gets whether the application is using dark appearance. This can be used to query the current appearance, as requested via [property@StyleManager:color-scheme]. whether the application is using dark appearance a style manager Gets the display the style manager is associated with. The display will be `NULL` for the style manager returned by [func@StyleManager.get_default]. the display a style manager Gets whether the application is using high contrast appearance. This cannot be overridden by applications. whether the application is using high contrast appearance a style manager Gets whether the system supports accent colors. This can be used to check if the current environment provides an accent color preference. For example, applications might want to show a preference for choosing accent color if it's set to `FALSE`. See [property@StyleManager:accent-color]. whether the system supports accent colors a style manager Gets whether the system supports color schemes. This can be used to check if the current environment provides a color scheme preference. For example, applications might want to show a separate appearance switcher if it's set to `FALSE`. whether the system supports color schemes a style manager Sets the requested application color scheme. The effective appearance will be decided based on the application color scheme and the system preferred color scheme. The [property@StyleManager:dark] property can be used to query the current effective appearance. The `ADW_COLOR_SCHEME_PREFER_LIGHT` color scheme results in the application using light appearance unless the system prefers dark colors. This is the default value. The `ADW_COLOR_SCHEME_PREFER_DARK` color scheme results in the application using dark appearance, but can still switch to the light appearance if the system can prefers it, for example, when the high contrast preference is enabled. The `ADW_COLOR_SCHEME_FORCE_LIGHT` and `ADW_COLOR_SCHEME_FORCE_DARK` values ignore the system preference entirely. They are useful if the application wants to match its UI to its content or to provide a separate color scheme switcher. If a per-[class@Gdk.Display] style manager has its color scheme set to `ADW_COLOR_SCHEME_DEFAULT`, it will inherit the color scheme from the default style manager. For the default style manager, `ADW_COLOR_SCHEME_DEFAULT` is equivalent to `ADW_COLOR_SCHEME_PREFER_LIGHT`. The [property@StyleManager:system-supports-color-schemes] property can be used to check if the current environment provides a color scheme preference. a style manager the color scheme The current system accent color. See also [property@StyleManager:accent-color-rgba]. The current system accent color as a `GdkRGBA`. Equivalent to calling [func@AccentColor.to_rgba] on the value of [property@StyleManager:accent-color]. This is a background color. The matching foreground color is white. The requested application color scheme. The effective appearance will be decided based on the application color scheme and the system preferred color scheme. The [property@StyleManager:dark] property can be used to query the current effective appearance. The `ADW_COLOR_SCHEME_PREFER_LIGHT` color scheme results in the application using light appearance unless the system prefers dark colors. This is the default value. The `ADW_COLOR_SCHEME_PREFER_DARK` color scheme results in the application using dark appearance, but can still switch to the light appearance if the system can prefers it, for example, when the high contrast preference is enabled. The `ADW_COLOR_SCHEME_FORCE_LIGHT` and `ADW_COLOR_SCHEME_FORCE_DARK` values ignore the system preference entirely. They are useful if the application wants to match its UI to its content or to provide a separate color scheme switcher. If a per-[class@Gdk.Display] style manager has its color scheme set to `ADW_COLOR_SCHEME_DEFAULT`, it will inherit the color scheme from the default style manager. For the default style manager, `ADW_COLOR_SCHEME_DEFAULT` is equivalent to `ADW_COLOR_SCHEME_PREFER_LIGHT`. The [property@StyleManager:system-supports-color-schemes] property can be used to check if the current environment provides a color scheme preference. Whether the application is using dark appearance. This property can be used to query the current appearance, as requested via [property@StyleManager:color-scheme]. The display the style manager is associated with. The display will be `NULL` for the style manager returned by [func@StyleManager.get_default]. Whether the application is using high contrast appearance. This cannot be overridden by applications. Whether the system supports accent colors. This property can be used to check if the current environment provides an accent color preference. For example, applications might want to show a preference for choosing accent color if it's set to `FALSE`. See [property@StyleManager:accent-color]. Whether the system supports color schemes. This property can be used to check if the current environment provides a color scheme preference. For example, applications might want to show a separate appearance switcher if it's set to `FALSE`. See [property@StyleManager:color-scheme]. A swipe tracker used in [class@Carousel], [class@NavigationView] and [class@OverlaySplitView]. The `AdwSwipeTracker` object can be used for implementing widgets with swipe gestures. It supports touch-based swipes, pointer dragging, and touchpad scrolling. The widgets will probably want to expose the [property@SwipeTracker:enabled] property. If they expect to use horizontal orientation, [property@SwipeTracker:reversed] can be used for supporting RTL text direction. Creates a new `AdwSwipeTracker` for @widget. the newly created `AdwSwipeTracker` a widget to add the tracker on Gets whether to allow swiping for more than one snap point at a time. whether long swipes are allowed a swipe tracker Gets whether @self can be dragged with mouse pointer. whether mouse dragging is allowed a swipe tracker Gets whether to allow touchscreen swiping from `GtkWindowHandle`. whether swiping from window handles is allowed a swipe tracker Gets whether @self is enabled. whether @self is enabled a swipe tracker Gets whether to allow swiping past the first available snap point. whether to allow swiping past the first available snap point a swipe tracker Gets whether @self is reversing the swipe direction. whether the direction is reversed a swipe tracker Get the widget @self is attached to. the swipeable widget a swipe tracker Gets whether to allow swiping past the last available snap point. whether to allow swiping past the last available snap point a swipe tracker Sets whether to allow swiping for more than one snap point at a time. If the value is `FALSE`, each swipe can only move to the adjacent snap points. a swipe tracker whether to allow long swipes Sets whether @self can be dragged with mouse pointer. a swipe tracker whether to allow mouse dragging Sets whether to allow touchscreen swiping from `GtkWindowHandle`. Setting it to `TRUE` will make dragging the window impossible. a swipe tracker whether to allow swiping from window handles Sets whether @self is enabled. When it's not enabled, no events will be processed. Usually widgets will want to expose this via a property. a swipe tracker whether @self is enabled Sets whether to allow swiping past the first available snap point. a swipe tracker whether to allow swiping past the first available snap point Sets whether to reverse the swipe direction. If the swipe tracker is horizontal, it can be used for supporting RTL text direction. a swipe tracker whether to reverse the swipe direction Sets whether to allow swiping past the last available snap point. a swipe tracker whether to allow swiping past the last available snap point Moves the current progress value by @delta. This can be used to adjust the current position if snap points move during the gesture. a swipe tracker the position delta Whether to allow swiping for more than one snap point at a time. If the value is `FALSE`, each swipe can only move to the adjacent snap points. Whether to allow dragging with mouse pointer. Whether to allow touchscreen swiping from `GtkWindowHandle`. This will make dragging the window impossible. Whether the swipe tracker is enabled. When it's not enabled, no events will be processed. Usually widgets will want to expose this via a property. Whether to allow swiping past the first available snap point. Whether to reverse the swipe direction. If the swipe tracker is horizontal, it can be used for supporting RTL text direction. The widget the swipe tracker is attached to. Whether to allow swiping past the last available snap point. This signal is emitted right before a swipe will be started, after the drag threshold has been passed. This signal is emitted as soon as the gesture has stopped. The user is expected to animate the deceleration from the current progress value to @to with an animation using @velocity as the initial velocity, provided in pixels per second. [class@SpringAnimation] is usually a good fit for this. the velocity of the swipe the progress value to animate to This signal is emitted when a possible swipe is detected. The @direction value can be used to restrict the swipe to a certain direction. the direction of the swipe This signal is emitted every time the progress value changes. the current animation progress value An interface for swipeable widgets. The `AdwSwipeable` interface is implemented by all swipeable widgets. See [class@SwipeTracker] for details about implementing it. Gets the progress @self will snap back to after the gesture is canceled. the cancel progress, unitless a swipeable Gets the swipe distance of @self. This corresponds to how many pixels 1 unit represents. the swipe distance in pixels a swipeable Gets the current progress of @self. the current progress, unitless a swipeable Gets the snap points of @self. Each snap point represents a progress value that is considered acceptable to end the swipe on. the snap points a swipeable location to return the number of the snap points Gets the area @self can start a swipe from for the given direction and gesture type. This can be used to restrict swipes to only be possible from a certain area, for example, to only allow edge swipes, or to have a draggable element and ignore swipes elsewhere. If not implemented, the default implementation returns the allocation of @self, allowing swipes from anywhere. a swipeable the direction of the swipe whether the swipe is caused by a dragging gesture a pointer to a rectangle to store the swipe area Gets the progress @self will snap back to after the gesture is canceled. the cancel progress, unitless a swipeable Gets the swipe distance of @self. This corresponds to how many pixels 1 unit represents. the swipe distance in pixels a swipeable Gets the current progress of @self. the current progress, unitless a swipeable Gets the snap points of @self. Each snap point represents a progress value that is considered acceptable to end the swipe on. the snap points a swipeable location to return the number of the snap points Gets the area @self can start a swipe from for the given direction and gesture type. This can be used to restrict swipes to only be possible from a certain area, for example, to only allow edge swipes, or to have a draggable element and ignore swipes elsewhere. If not implemented, the default implementation returns the allocation of @self, allowing swipes from anywhere. a swipeable the direction of the swipe whether the swipe is caused by a dragging gesture a pointer to a rectangle to store the swipe area An interface for swipeable widgets. The parent interface. Gets the swipe distance. the swipe distance in pixels a swipeable Gets the snap points. the snap points a swipeable location to return the number of the snap points Gets the current progress. the current progress, unitless a swipeable Gets the cancel progress. the cancel progress, unitless a swipeable Gets the swipeable rectangle. a swipeable the direction of the swipe whether the swipe is caused by a dragging gesture a pointer to a rectangle to store the swipe area A [class@Gtk.ListBoxRow] used to represent two states. <picture> <source srcset="switch-row-dark.png" media="(prefers-color-scheme: dark)"> <img src="switch-row.png" alt="switch-row"> </picture> The `AdwSwitchRow` widget contains a [class@Gtk.Switch] that allows the user to select between two states: "on" or "off". When activated, the row will invert its active state. The user can control the switch by activating the row or by dragging on the switch handle. See [class@Gtk.Switch] for details. Example of an `AdwSwitchRow` UI definition: ```xml <object class="AdwSwitchRow"> <property name="title" translatable="yes">Switch Row</property> <signal name="notify::active" handler="switch_row_notify_active_cb"/> </object> ``` The [property@SwitchRow:active] property should be connected to in order to monitor changes to the active state. ## Accessibility `AdwSwitchRow` uses the `GTK_ACCESSIBLE_ROLE_SWITCH` role. Creates a new `AdwSwitchRow`. the newly created `AdwSwitchRow` Gets whether @self is in its "on" or "off" position. whether @self is active or not a switch row Sets whether @self is in its "on" or "off" position a switch row whether @self should be active Whether the switch row is in the "on" or "off" position. A tab bar for [class@TabView]. <picture> <source srcset="tab-bar-dark.png" media="(prefers-color-scheme: dark)"> <img src="tab-bar.png" alt="tab-bar"> </picture> The `AdwTabBar` widget is a tab bar that can be used with conjunction with `AdwTabView`. It is typically used as a top bar within [class@ToolbarView]. `AdwTabBar` can autohide and can optionally contain action widgets on both sides of the tabs. When there's not enough space to show all the tabs, `AdwTabBar` will scroll them. Pinned tabs always stay visible and aren't a part of the scrollable area. ## CSS nodes `AdwTabBar` has a single CSS node with name `tabbar`. Creates a new `AdwTabBar`. the newly created `AdwTabBar` Gets whether the tabs automatically hide. whether the tabs automatically hide a tab bar Gets the widget shown after the tabs. the widget shown after the tabs a tab bar Gets whether tabs expand to full width. whether tabs expand to full width. a tab bar Gets the current action during a drop on the extra_drop_target. the drag action of the current drop. a tab bar Gets whether drop data should be preloaded on hover. whether drop data should be preloaded on hover a tab bar Gets whether tabs use inverted layout. whether tabs use inverted layout a tab bar Gets whether @self is overflowing. If `TRUE`, all tabs cannot be displayed at once and require scrolling. whether @self is overflowing a tab bar Gets the widget shown before the tabs. the widget shown before the tabs a tab bar Gets whether the tabs are currently revealed. See [property@TabBar:autohide]. whether the tabs are currently revealed a tab bar Gets the tab view @self controls. the view @self controls a tab bar Sets whether the tabs automatically hide. If set to `TRUE`, the tab bar disappears when [property@TabBar:view] has 0 or 1 tab, no pinned tabs, and no tab is being transferred. See [property@TabBar:tabs-revealed]. a tab bar whether the tabs automatically hide Sets the widget to show after the tabs. a tab bar the widget to show after the tabs Sets whether tabs expand to full width. If set to `TRUE`, the tabs will always vary width filling the whole width when possible, otherwise tabs will always have the minimum possible size. a tab bar whether to expand tabs Sets whether drop data should be preloaded on hover. See [property@Gtk.DropTarget:preload]. a tab bar whether to preload drop data Sets whether tabs tabs use inverted layout. If set to `TRUE`, non-pinned tabs will have the close button at the beginning and the indicator at the end rather than the opposite. a tab bar whether tabs use inverted layout Sets the widget to show before the tabs. a tab bar the widget to show before the tabs Sets the tab view @self controls. a tab bar a tab view Sets the supported types for this drop target. Sets up an extra drop target on tabs. This allows to drag arbitrary content onto tabs, for example URLs in a web browser. If a tab is hovered for a certain period of time while dragging the content, it will be automatically selected. The [signal@TabBar::extra-drag-drop] signal can be used to handle the drop. a tab bar the supported actions all supported `GType`s that can be dropped number of @types Whether the tabs automatically hide. If set to `TRUE`, the tab bar disappears when [property@TabBar:view] has 0 or 1 tab, no pinned tabs, and no tab is being transferred. See [property@TabBar:tabs-revealed]. The widget shown after the tabs. Whether tabs expand to full width. If set to `TRUE`, the tabs will always vary width filling the whole width when possible, otherwise tabs will always have the minimum possible size. The unique action on the `current-drop` of the [signal@TabBar::extra-drag-drop]. This property should only be used during a [signal@TabBar::extra-drag-drop] and is always a subset of what was originally passed to [method@TabBar.setup_extra_drop_target]. Whether the drop data should be preloaded on hover. See [property@Gtk.DropTarget:preload]. Whether tabs use inverted layout. If set to `TRUE`, non-pinned tabs will have the close button at the beginning and the indicator at the end rather than the opposite. Whether the tab bar is overflowing. If `TRUE`, all tabs cannot be displayed at once and require scrolling. The widget shown before the tabs. Whether the tabs are currently revealed. See [property@TabBar:autohide]. The tab view the tab bar controls. This signal is emitted when content is dropped onto a tab. The content must be of one of the types set up via [method@TabBar.setup_extra_drop_target]. See [signal@Gtk.DropTarget::drop]. whether the drop was accepted for @page the page matching the tab the content was dropped onto the `GValue` being dropped This signal is emitted when the dropped content is preloaded. In order for data to be preloaded, [property@TabBar:extra-drag-preload] must be set to `TRUE`. The content must be of one of the types set up via [method@TabBar.setup_extra_drop_target]. See [property@Gtk.DropTarget:value]. the preferred action for the drop on @page the page matching the tab the content was dropped onto the `GValue` being dropped A button that displays the number of [class@TabView] pages. <picture> <source srcset="tab-button-dark.png" media="(prefers-color-scheme: dark)"> <img src="tab-button.png" alt="tab-button"> </picture> `AdwTabButton` is a button that displays the number of pages in a given `AdwTabView`, as well as whether one of the inactive pages needs attention. It's intended to be used as a visible indicator when there's no visible tab bar, typically opening an [class@TabOverview] on click, e.g. via the `overview.open` action name: ```xml <object class="AdwTabButton"> <property name="view">view</property> <property name="action-name">overview.open</property> </object> ``` ## CSS nodes `AdwTabButton` has a main CSS node with name `tabbutton`. # Accessibility `AdwTabButton` uses the `GTK_ACCESSIBLE_ROLE_BUTTON` role. Creates a new `AdwTabButton`. the newly created `AdwTabButton` Gets the tab view @self displays. the tab view a tab button Sets the tab view to display. a tab button a tab view The view the tab button displays. Emitted to animate press then release. This is an action signal. Applications should never connect to this signal, but use the [signal@TabButton::clicked] signal. Emitted when the button has been activated (pressed and released). A tab overview for [class@TabView]. <picture> <source srcset="tab-overview-dark.png" media="(prefers-color-scheme: dark)"> <img src="tab-overview.png" alt="tab-overview"> </picture> `AdwTabOverview` is a widget that can display tabs from an `AdwTabView` in a grid. `AdwTabOverview` shows a thumbnail for each tab. By default thumbnails are static for all pages except the selected one. They can be made always live by setting [property@TabPage:live-thumbnail] to `TRUE`, or refreshed with [method@TabPage.invalidate_thumbnail] or [method@TabView.invalidate_thumbnails] otherwise. If the pages are too tall or too wide, the thumbnails will be cropped; use [property@TabPage:thumbnail-xalign] and [property@TabPage:thumbnail-yalign] to control which part of the page should be visible in this case. Pinned tabs are shown as smaller cards without thumbnails above the other tabs. Unlike in [class@TabBar], they still have titles, as well as an unpin button. `AdwTabOverview` provides search in open tabs. It searches in tab titles and tooltips, as well as [property@TabPage:keyword]. If [property@TabOverview:enable-new-tab] is set to `TRUE`, a new tab button will be shown. Connect to the [signal@TabOverview::create-tab] signal to use it. [property@TabOverview:secondary-menu] can be used to provide a secondary menu for the overview. Use it to add extra actions, e.g. to open a new window or undo closed tab. `AdwTabOverview` is intended to be used as the direct child of the window, with the rest of the window contents set as the [property@TabOverview:child]. The child is expected to contain an [class@TabView]. `AdwTabOverview` shows window buttons by default. They can be disabled by setting [property@TabOverview:show-start-title-buttons] and/or [property@TabOverview:show-start-title-buttons] and/or [property@TabOverview:show-end-title-buttons] to `FALSE`. If search and window buttons are disabled, and secondary menu is not set, the header bar will be hidden. ## Actions `AdwTabOverview` defines the `overview.open` and `overview.close` actions for opening and closing itself. They can be convenient when used together with [class@TabButton]. ## CSS nodes `AdwTabOverview` has a single CSS node with name `taboverview`. Creates a new `AdwTabOverview`. the newly created `AdwTabOverview` Gets the child widget of @self. the child widget of @self a tab overview Gets whether to new tab button is enabled for @self. whether new tab button is enabled a tab overview Gets whether search in tabs is enabled for @self. whether search is enabled a tab overview Gets the current action during a drop on the extra_drop_target. the drag action of the current drop. a tab overview Gets whether drop data should be preloaded on hover. whether drop data should be preloaded on hover a tab overview Gets whether thumbnails use inverted layout. whether thumbnails use inverted layout a tab overview Gets whether @self is open. whether the overview is open a tab overview Gets whether search is currently active for @self. See [property@TabOverview:enable-search]. whether search is active a tab overview Gets the secondary menu model for @self. the secondary menu model a tab overview Gets whether end title buttons are shown in @self's header bar. whether end title buttons are shown a tab overview Gets whether start title buttons are shown in @self's header bar. whether start title buttons are shown a tab overview Gets the tab view @self controls. the tab view a tab overview Sets the child widget of @self. a tab overview the child widget Sets whether to enable new tab button for @self. Connect to the [signal@TabOverview::create-tab] signal to use it. a tab overview whether to enable new tab button Sets whether to enable search in tabs for @self. Search matches tab titles and tooltips, as well as keywords, set via [property@TabPage:keyword]. Use keywords to search in e.g. page URLs in a web browser. During search, tab reordering and drag-n-drop are disabled. Use [property@TabOverview:search-active] to check out if search is currently active. a tab overview whether to enable search Sets whether drop data should be preloaded on hover. See [property@Gtk.DropTarget:preload]. a tab overview whether to preload drop data Sets whether thumbnails use inverted layout. If set to `TRUE`, thumbnails will have the close or unpin button at the beginning and the indicator at the end rather than the other way around. a tab overview whether thumbnails use inverted layout Sets whether the to open @self. a tab overview whether the overview is open Sets the secondary menu model for @self. Use it to add extra actions, e.g. to open a new window or undo closed tab. a tab overview a menu model Sets whether to show end title buttons in @self's header bar. See [property@HeaderBar:show-start-title-buttons] for the other side. a tab overview whether to show end title buttons Sets whether to show start title buttons in @self's header bar. See [property@HeaderBar:show-end-title-buttons] for the other side. a tab overview whether to show start title buttons Sets the tab view to control. The view must be inside @self, see [property@TabOverview:child]. a tab overview a tab view Sets the supported types for this drop target. Sets up an extra drop target on tabs. This allows to drag arbitrary content onto tabs, for example URLs in a web browser. If a tab is hovered for a certain period of time while dragging the content, it will be automatically selected. The [signal@TabOverview::extra-drag-drop] signal can be used to handle the drop. a tab overview the supported actions all supported `GType`s that can be dropped number of @types The child widget. Whether to enable new tab button. Connect to the [signal@TabOverview::create-tab] signal to use it. Whether to enable search in tabs. Search matches tab titles and tooltips, as well as keywords, set via [property@TabPage:keyword]. Use keywords to search in e.g. page URLs in a web browser. During search, tab reordering and drag-n-drop are disabled. Use [property@TabOverview:search-active] to check out if search is currently active. The unique action on the `current-drop` of the [signal@TabOverview::extra-drag-drop]. This property should only be used during a [signal@TabOverview::extra-drag-drop] and is always a subset of what was originally passed to [method@TabOverview.setup_extra_drop_target]. Whether the drop data should be preloaded on hover. See [property@Gtk.DropTarget:preload]. Whether thumbnails use inverted layout. If set to `TRUE`, thumbnails will have the close or unpin buttons at the beginning and the indicator at the end rather than the other way around. Whether the overview is open. Whether search is currently active. See [property@TabOverview:enable-search]. The secondary menu model. Use it to add extra actions, e.g. to open a new window or undo closed tab. Whether to show end title buttons in the overview's header bar. See [property@HeaderBar:show-start-title-buttons] for the other side. Whether to show start title buttons in the overview's header bar. See [property@HeaderBar:show-end-title-buttons] for the other side. The tab view the overview controls. The view must be inside the tab overview, see [property@TabOverview:child]. Emitted when a tab needs to be created; This can happen after the new tab button has been pressed, see [property@TabOverview:enable-new-tab]. The signal handler is expected to create a new page in the corresponding [class@TabView] and return it. the newly created page This signal is emitted when content is dropped onto a tab. The content must be of one of the types set up via [method@TabOverview.setup_extra_drop_target]. See [signal@Gtk.DropTarget::drop]. whether the drop was accepted for @page the page matching the tab the content was dropped onto the `GValue` being dropped This signal is emitted when the dropped content is preloaded. In order for data to be preloaded, [property@TabOverview:extra-drag-preload] must be set to `TRUE`. The content must be of one of the types set up via [method@TabOverview.setup_extra_drop_target]. See [property@Gtk.DropTarget:value]. the preferred action for the drop on @page the page matching the tab the content was dropped onto the `GValue` being dropped An auxiliary class used by [class@TabView]. Gets the child of @self. the child of @self a tab page Gets the icon of @self. the icon of @self a tab page Gets whether the indicator of @self is activatable. whether the indicator is activatable a tab page Gets the indicator icon of @self. the indicator icon of @self a tab page Gets the tooltip of the indicator icon of @self. the indicator tooltip of @self a tab page Gets the search keyword of @self. the search keyword of @self a tab page Gets whether to live thumbnail is enabled @self. whether live thumbnail is enabled a tab overview Gets whether @self is loading. whether @self is loading a tab page Gets whether @self needs attention. whether @self needs attention a tab page Gets the parent page of @self. See [method@TabView.add_page] and [method@TabView.close_page]. the parent page a tab page Gets whether @self is pinned. See [method@TabView.set_page_pinned]. whether @self is pinned a tab page Gets whether @self is selected. whether @self is selected a tab page Gets the horizontal alignment of the thumbnail for @self. the horizontal alignment a tab page Gets the vertical alignment of the thumbnail for @self. the vertical alignment a tab overview Gets the title of @self. the title of @self a tab page Gets the tooltip of @self. the tooltip of @self a tab page Invalidates thumbnail for @self. If an [class@TabOverview] is open, the thumbnail representing @self will be immediately updated. Otherwise it will be update when opening the overview. Does nothing if [property@TabPage:live-thumbnail] is set to `TRUE`. See also [method@TabView.invalidate_thumbnails]. a tab page Sets the icon of @self. [class@TabBar] and [class@TabOverview] display the icon next to the title, unless [property@TabPage:loading] is set to `TRUE`. `AdwTabBar` also won't show the icon if the page is pinned and [propertyTabPage:indicator-icon] is set. a tab page the icon of @self Sets whether the indicator of @self is activatable. If set to `TRUE`, [signal@TabView::indicator-activated] will be emitted when the indicator icon is clicked. If [property@TabPage:indicator-icon] is not set, does nothing. a tab page whether the indicator is activatable Sets the indicator icon of @self. A common use case is an audio or camera indicator in a web browser. [class@TabBar] will show it at the beginning of the tab, alongside icon representing [property@TabPage:icon] or loading spinner. If the page is pinned, the indicator will be shown instead of icon or spinner. [class@TabOverview] will show it at the at the top part of the thumbnail. [property@TabPage:indicator-tooltip] can be used to set the tooltip on the indicator icon. If [property@TabPage:indicator-activatable] is set to `TRUE`, the indicator icon can act as a button. a tab page the indicator icon of @self Sets the tooltip of the indicator icon of @self. The tooltip can be marked up with the Pango text markup language. See [property@TabPage:indicator-icon]. a tab page the indicator tooltip of @self Sets the search keyword for @self. [class@TabOverview] can search pages by their keywords in addition to their titles and tooltips. Keywords allow to include e.g. page URLs into tab search in a web browser. a tab page the search keyword Sets whether to enable live thumbnail for @self. When set to `TRUE`, @self's thumbnail in [class@TabOverview] will update immediately when @self is redrawn or resized. If it's set to `FALSE`, the thumbnail will only be live when the @self is selected, and otherwise it will be static and will only update when [method@TabPage.invalidate_thumbnail] or [method@TabView.invalidate_thumbnails] is called. a tab page whether to enable live thumbnail Sets whether @self is loading. If set to `TRUE`, [class@TabBar] and [class@TabOverview] will display a spinner in place of icon. If the page is pinned and [property@TabPage:indicator-icon] is set, loading status will not be visible with `AdwTabBar`. a tab page whether @self is loading Sets whether @self needs attention. [class@TabBar] will display a line under the tab representing the page if set to `TRUE`. If the tab is not visible, the corresponding edge of the tab bar will be highlighted. [class@TabOverview] will display a dot in the corner of the thumbnail if set to `TRUE`. [class@TabButton] will display a dot if any of the pages that aren't selected have [property@TabPage:needs-attention] set to `TRUE`. a tab page whether @self needs attention Sets the horizontal alignment of the thumbnail for @self. If the page is so wide that [class@TabOverview] can't display it completely and has to crop it, horizontal alignment will determine which part of the page will be visible. For example, 0.5 means the center of the page will be visible, 0 means the start edge will be visible and 1 means the end edge will be visible. The default horizontal alignment is 0. a tab page the new value Sets the vertical alignment of the thumbnail for @self. If the page is so tall that [class@TabOverview] can't display it completely and has to crop it, vertical alignment will determine which part of the page will be visible. For example, 0.5 means the center of the page will be visible, 0 means the top edge will be visible and 1 means the bottom edge will be visible. The default vertical alignment is 0. a tab page the new value [class@TabBar] will display it in the center of the tab unless it's pinned, and will use it as a tooltip unless [property@TabPage:tooltip] is set. [class@TabOverview] will display it below the thumbnail unless it's pinned, or inside the card otherwise, and will use it as a tooltip unless [property@TabPage:tooltip] is set. Sets the title of @self. a tab page the title of @self Sets the tooltip of @self. The tooltip can be marked up with the Pango text markup language. If not set, [class@TabBar] and [class@TabOverview] will use [property@TabPage:title] as a tooltip instead. a tab page the tooltip of @self The child of the page. The icon of the page. [class@TabBar] and [class@TabOverview] display the icon next to the title, unless [property@TabPage:loading] is set to `TRUE`. `AdwTabBar` also won't show the icon if the page is pinned and [propertyTabPage:indicator-icon] is set. Whether the indicator icon is activatable. If set to `TRUE`, [signal@TabView::indicator-activated] will be emitted when the indicator icon is clicked. If [property@TabPage:indicator-icon] is not set, does nothing. An indicator icon for the page. A common use case is an audio or camera indicator in a web browser. [class@TabBar] will show it at the beginning of the tab, alongside icon representing [property@TabPage:icon] or loading spinner. If the page is pinned, the indicator will be shown instead of icon or spinner. [class@TabOverview] will show it at the at the top part of the thumbnail. [property@TabPage:indicator-tooltip] can be used to set the tooltip on the indicator icon. If [property@TabPage:indicator-activatable] is set to `TRUE`, the indicator icon can act as a button. The tooltip of the indicator icon. The tooltip can be marked up with the Pango text markup language. See [property@TabPage:indicator-icon]. The search keyboard of the page. [class@TabOverview] can search pages by their keywords in addition to their titles and tooltips. Keywords allow to include e.g. page URLs into tab search in a web browser. Whether to enable live thumbnail for this page. When set to `TRUE`, the page's thumbnail in [class@TabOverview] will update immediately when the page is redrawn or resized. If it's set to `FALSE`, the thumbnail will only be live when the page is selected, and otherwise it will be static and will only update when [method@TabPage.invalidate_thumbnail] or [method@TabView.invalidate_thumbnails] is called. Whether the page is loading. If set to `TRUE`, [class@TabBar] and [class@TabOverview] will display a spinner in place of icon. If the page is pinned and [property@TabPage:indicator-icon] is set, loading status will not be visible with `AdwTabBar`. Whether the page needs attention. [class@TabBar] will display a line under the tab representing the page if set to `TRUE`. If the tab is not visible, the corresponding edge of the tab bar will be highlighted. [class@TabOverview] will display a dot in the corner of the thumbnail if set to `TRUE`. [class@TabButton] will display a dot if any of the pages that aren't selected have this property set to `TRUE`. The parent page of the page. See [method@TabView.add_page] and [method@TabView.close_page]. Whether the page is pinned. See [method@TabView.set_page_pinned]. Whether the page is selected. The horizontal alignment of the page thumbnail. If the page is so wide that [class@TabOverview] can't display it completely and has to crop it, horizontal alignment will determine which part of the page will be visible. For example, 0.5 means the center of the page will be visible, 0 means the start edge will be visible and 1 means the end edge will be visible. The default horizontal alignment is 0. The vertical alignment of the page thumbnail. If the page is so tall that [class@TabOverview] can't display it completely and has to crop it, vertical alignment will determine which part of the page will be visible. For example, 0.5 means the center of the page will be visible, 0 means the top edge will be visible and 1 means the bottom edge will be visible. The default vertical alignment is 0. The title of the page. [class@TabBar] will display it in the center of the tab unless it's pinned, and will use it as a tooltip unless [property@TabPage:tooltip] is set. [class@TabOverview] will display it below the thumbnail unless it's pinned, or inside the card otherwise, and will use it as a tooltip unless [property@TabPage:tooltip] is set. The tooltip of the page. The tooltip can be marked up with the Pango text markup language. If not set, [class@TabBar] and [class@TabOverview] will use [property@TabPage:title] as a tooltip instead. A dynamic tabbed container. `AdwTabView` is a container which shows one child at a time. While it provides keyboard shortcuts for switching between pages, it does not provide a visible tab switcher and relies on external widgets for that, such as [class@TabBar], [class@TabOverview] and [class@TabButton]. `AdwTabView` maintains a [class@TabPage] object for each page, which holds additional per-page properties. You can obtain the `AdwTabPage` for a page with [method@TabView.get_page], and as the return value for [method@TabView.append] and other functions for adding children. `AdwTabView` only aims to be useful for dynamic tabs in multi-window document-based applications, such as web browsers, file managers, text editors or terminals. It does not aim to replace [class@Gtk.Notebook] for use cases such as tabbed dialogs. As such, it does not support disabling page reordering or detaching. `AdwTabView` adds a number of global page switching and reordering shortcuts. The [property@TabView:shortcuts] property can be used to manage them. See [flags@TabViewShortcuts] for the list of the available shortcuts. All of the shortcuts are enabled by default. [method@TabView.add_shortcuts] and [method@TabView.remove_shortcuts] can be used to manage shortcuts in a convenient way, for example: ```c adw_tab_view_remove_shortcuts (view, ADW_TAB_VIEW_SHORTCUT_CONTROL_HOME | ADW_TAB_VIEW_SHORTCUT_CONTROL_END); ``` ## CSS nodes `AdwTabView` has a main CSS node with the name `tabview`. ## Accessibility `AdwTabView` uses the `GTK_ACCESSIBLE_ROLE_TAB_PANEL` for the tab pages which are the accessible parent objects of the child widgets. Creates a new `AdwTabView`. the newly created `AdwTabView` Adds @child to @self with @parent as the parent. This function can be used to automatically position new pages, and to select the correct page when this page is closed while being selected (see [method@TabView.close_page]). If @parent is `NULL`, this function is equivalent to [method@TabView.append]. the page object representing @child a tab view a widget to add a parent page for @child Adds @shortcuts for @self. See [property@TabView:shortcuts] for details. a tab view the shortcuts to add Inserts @child as the last non-pinned page. the page object representing @child a tab view a widget to add Inserts @child as the last pinned page. the page object representing @child a tab view a widget to add Requests to close all pages other than @page. a tab view a page of @self Requests to close @page. Calling this function will result in the [signal@TabView::close-page] signal being emitted for @page. Closing the page can then be confirmed or denied via [method@TabView.close_page_finish]. If the page is waiting for a [method@TabView.close_page_finish] call, this function will do nothing. The default handler for [signal@TabView::close-page] will immediately confirm closing the page if it's non-pinned, or reject it if it's pinned. This behavior can be changed by registering your own handler for that signal. If @page was selected, another page will be selected instead: If the [property@TabPage:parent] value is `NULL`, the next page will be selected when possible, or if the page was already last, the previous page will be selected instead. If it's not `NULL`, the previous page will be selected if it's a descendant (possibly indirect) of the parent. If both the previous page and the parent are pinned, the parent will be selected instead. a tab view a page of @self Completes a [method@TabView.close_page] call for @page. If @confirm is `TRUE`, @page will be closed. If it's `FALSE`, it will be reverted to its previous state and [method@TabView.close_page] can be called for it again. This function should not be called unless a custom handler for [signal@TabView::close-page] is used. a tab view a page of @self whether to confirm or deny closing @page Requests to close all pages after @page. a tab view a page of @self Requests to close all pages before @page. a tab view a page of @self Gets the default icon of @self. the default icon of @self. a tab view Whether a page is being transferred. The corresponding property will be set to `TRUE` when a drag-n-drop tab transfer starts on any `AdwTabView`, and to `FALSE` after it ends. During the transfer, children cannot receive pointer input and a tab can be safely dropped on the tab view. whether a page is being transferred a tab view Gets the tab context menu model for @self. the tab context menu model for @self a tab view Gets the number of pages in @self. the number of pages in @self a tab view Gets the number of pinned pages in @self. See [method@TabView.set_page_pinned]. the number of pinned pages in @self a tab view Gets the [class@TabPage] representing the child at @position. the page object at @position a tab view the index of the page in @self, starting from 0 Gets the [class@TabPage] object representing @child. the page object for @child a tab view a child in @self Finds the position of @page in @self, starting from 0. the position of @page in @self a tab view a page of @self Returns a [iface@Gio.ListModel] that contains the pages of @self. 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 change the selected page. a `GtkSelectionModel` for the pages of @self a tab view Gets the currently selected page in @self. the selected page a tab view Gets the enabled shortcuts for @self. the shortcut mask a tab view Inserts a non-pinned page at @position. It's an error to try to insert a page before a pinned page, in that case [method@TabView.insert_pinned] should be used instead. the page object representing @child a tab view a widget to add the position to add @child at, starting from 0 Inserts a pinned page at @position. It's an error to try to insert a pinned page after a non-pinned page, in that case [method@TabView.insert] should be used instead. the page object representing @child a tab view a widget to add the position to add @child at, starting from 0 Invalidates thumbnails for all pages in @self. This is a convenience method, equivalent to calling [method@TabPage.invalidate_thumbnail] on each page. a tab view Inserts @child as the first non-pinned page. the page object representing @child a tab view a widget to add Inserts @child as the first pinned page. the page object representing @child a tab view a widget to add Removes @shortcuts from @self. See [property@TabView:shortcuts] for details. a tab view the shortcuts to reomve Reorders @page to before its previous page if possible. whether @page was moved a tab view a page of @self Reorders @page to the first possible position. whether @page was moved a tab view a page of @self Reorders @page to after its next page if possible. whether @page was moved a tab view a page of @self Reorders @page to the last possible position. whether @page was moved a tab view a page of @self Reorders @page to @position. It's a programmer error to try to reorder a pinned page after a non-pinned one, or a non-pinned page before a pinned one. whether @page was moved a tab view a page of @self the position to insert the page at, starting at 0 Selects the page after the currently selected page. If the last page was already selected, this function does nothing. whether the selected page was changed a tab view Selects the page before the currently selected page. If the first page was already selected, this function does nothing. whether the selected page was changed a tab view Sets the default page icon for @self. If a page doesn't provide its own icon via [property@TabPage:icon], a default icon may be used instead for contexts where having an icon is necessary. [class@TabBar] will use default icon for pinned tabs in case the page is not loading, doesn't have an icon and an indicator. Default icon is never used for tabs that aren't pinned. [class@TabOverview] will use default icon for pages with missing thumbnails. By default, the `adw-tab-icon-missing-symbolic` icon is used. a tab view the default icon Sets the tab context menu model for @self. When a context menu is shown for a tab, it will be constructed from the provided menu model. Use the [signal@TabView::setup-menu] signal to set up the menu actions for the particular tab. a tab view a menu model Pins or unpins @page. Pinned pages are guaranteed to be placed before all non-pinned pages; at any given moment the first [property@TabView:n-pinned-pages] pages in @self are guaranteed to be pinned. When a page is pinned or unpinned, it's automatically reordered: pinning a page moves it after other pinned pages; unpinning a page moves it before other non-pinned pages. Pinned pages can still be reordered between each other. [class@TabBar] will display pinned pages in a compact form, never showing the title or close button, and only showing a single icon, selected in the following order: 1. [property@TabPage:indicator-icon] 2. A spinner if [property@TabPage:loading] is `TRUE` 3. [property@TabPage:icon] 4. [property@TabView:default-icon] [class@TabOverview] will not show a thumbnail for pinned pages, and replace the close button with an unpin button. Unlike `AdwTabBar`, it will still display the page's title, icon and indicator separately. Pinned pages cannot be closed by default, see [signal@TabView::close-page] for how to override that behavior. Changes the value of the [property@TabPage:pinned] property. a tab view a page of @self whether @page should be pinned Sets the currently selected page in @self. a tab view a page in @self Sets the enabled shortcuts for @self. See [flags@TabViewShortcuts] for the list of the available shortcuts. All of the shortcuts are enabled by default. [method@TabView.add_shortcuts] and [method@TabView.remove_shortcuts] provide a convenient way to manage individual shortcuts. a tab view the new shortcuts Transfers @page from @self to @other_view. The @page object will be reused. It's a programmer error to try to insert a pinned page after a non-pinned one, or a non-pinned page before a pinned one. a tab view a page of @self the tab view to transfer the page to the position to insert the page at, starting at 0 Default page icon. If a page doesn't provide its own icon via [property@TabPage:icon], a default icon may be used instead for contexts where having an icon is necessary. [class@TabBar] will use default icon for pinned tabs in case the page is not loading, doesn't have an icon and an indicator. Default icon is never used for tabs that aren't pinned. [class@TabOverview] will use default icon for pages with missing thumbnails. By default, the `adw-tab-icon-missing-symbolic` icon is used. Whether a page is being transferred. This property will be set to `TRUE` when a drag-n-drop tab transfer starts on any `AdwTabView`, and to `FALSE` after it ends. During the transfer, children cannot receive pointer input and a tab can be safely dropped on the tab view. Tab context menu model. When a context menu is shown for a tab, it will be constructed from the provided menu model. Use the [signal@TabView::setup-menu] signal to set up the menu actions for the particular tab. The number of pages in the tab view. The number of pinned pages in the tab view. See [method@TabView.set_page_pinned]. A selection model with the tab view's pages. 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 change the selected page. The currently selected page. The enabled shortcuts. See [flags@TabViewShortcuts] for the list of the available shortcuts. All of the shortcuts are enabled by default. [method@TabView.add_shortcuts] and [method@TabView.remove_shortcuts] provide a convenient way to manage individual shortcuts. Emitted after [method@TabView.close_page] has been called for @page. The handler is expected to call [method@TabView.close_page_finish] to confirm or reject the closing. The default handler will immediately confirm closing for non-pinned pages, or reject it for pinned pages, equivalent to the following example: ```c static gboolean close_page_cb (AdwTabView *view, AdwTabPage *page, gpointer user_data) { adw_tab_view_close_page_finish (view, page, !adw_tab_page_get_pinned (page)); return GDK_EVENT_STOP; } ``` The [method@TabView.close_page_finish] call doesn't have to happen inside the handler, so can be used to do asynchronous checks before confirming the closing. A typical reason to connect to this signal is to show a confirmation dialog for closing a tab. The signal handler should return `GDK_EVENT_STOP` to stop propagation or `GDK_EVENT_CONTINUE` to invoke the default handler. whether propagation should be stopped a page of @self Emitted when a tab should be transferred into a new window. This can happen after a tab has been dropped on desktop. The signal handler is expected to create a new window, position it as needed and return its `AdwTabView` that the page will be transferred into. the `AdwTabView` from the new window Emitted after the indicator icon on @page has been activated. See [property@TabPage:indicator-icon] and [property@TabPage:indicator-activatable]. a page of @self Emitted when a page has been created or transferred to @self. A typical reason to connect to this signal would be to connect to page signals for things such as updating window title. a page of @self the position of the page, starting from 0 Emitted when a page has been removed or transferred to another view. A typical reason to connect to this signal would be to disconnect signal handlers connected in the [signal@TabView::page-attached] handler. It is important not to try and destroy the page child in the handler of this function as the child might merely be moved to another window; use child dispose handler for that or do it in sync with your [method@TabView.close_page_finish] calls. a page of @self the position of the removed page, starting from 0 Emitted after @page has been reordered to @position. a page of @self the position @page was moved to, starting at 0 Emitted when a context menu is opened or closed for @page. If the menu has been closed, @page will be set to `NULL`. It can be used to set up menu actions before showing the menu, for example disable actions not applicable to @page. a page of @self Describes available shortcuts in an [class@TabView]. Shortcuts can be set with [property@TabView:shortcuts], or added/removed individually with [method@TabView.add_shortcuts] and [method@TabView.remove_shortcuts]. New values may be added to this enumeration over time. No shortcuts <kbd>Ctrl</kbd>+<kbd>Tab</kbd> - switch to the next page <kbd>Shift</kbd>+<kbd>Ctrl</kbd>+<kbd>Tab</kbd> - switch to the previous page <kbd>Ctrl</kbd>+<kbd>Page Up</kbd> - switch to the previous page <kbd>Ctrl</kbd>+<kbd>Page Down</kbd> - switch to the next page <kbd>Ctrl</kbd>+<kbd>Home</kbd> - switch to the first page <kbd>Ctrl</kbd>+<kbd>End</kbd> - switch to the last page <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Page Up</kbd> - move the selected page backward <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Page Down</kbd> - move the selected page forward <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>Home</kbd> - move the selected page at the start <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>End</kbd> - move the current page at the end <kbd>Alt</kbd>+<kbd>1</kbd>⋯<kbd>9</kbd> - switch to pages 1-9 <kbd>Alt</kbd>+<kbd>0</kbd> - switch to page 10 All of the shortcuts A time-based [class@Animation]. `AdwTimedAnimation` implements a simple animation interpolating the given value from [property@TimedAnimation:value-from] to [property@TimedAnimation:value-to] over [property@TimedAnimation:duration] milliseconds using the curve described by [property@TimedAnimation:easing]. If [property@TimedAnimation:reverse] is set to `TRUE`, `AdwTimedAnimation` will instead animate from [property@TimedAnimation:value-to] to [property@TimedAnimation:value-from], and the easing curve will be inverted. The animation can repeat a certain amount of times, or endlessly, depending on the [property@TimedAnimation:repeat-count] value. If [property@TimedAnimation:alternate] is set to `TRUE`, it will also change the direction every other iteration. Creates a new `AdwTimedAnimation` on @widget to animate @target from @from to @to. the newly created animation a widget to create animation on a value to animate from a value to animate to a duration for the animation a target value to animate Gets whether @self changes direction on every iteration. whether @self alternates a timed animation Gets the duration of @self. the duration of @self, in milliseconds a timed animation Gets the easing function @self uses. the easing function @self uses a timed animation Gets the number of times @self will play. the number of times @self will play a timed animation Gets whether @self plays backwards. whether @self plays backwards a timed animation Gets the value @self will animate from. the value to animate from a timed animation Gets the value @self will animate to. the value to animate to a timed animation Sets whether @self changes direction on every iteration. a timed animation whether @self alternates Sets the duration of @self. If the animation repeats more than once, sets the duration of one iteration. a timed animation the duration to use, in milliseconds Sets the easing function @self will use. See [enum@Easing] for the description of specific easing functions. a timed animation the easing function to use Sets the number of times @self will play. If set to 0, @self will repeat endlessly. a timed animation the number of times @self will play Sets whether @self plays backwards. a timed animation whether @self plays backwards Sets the value @self will animate from. The animation will start at this value and end at [property@TimedAnimation:value-to]. If [property@TimedAnimation:reverse] is `TRUE`, the animation will end at this value instead. a timed animation the value to animate from Sets the value @self will animate to. The animation will start at [property@TimedAnimation:value-from] and end at this value. If [property@TimedAnimation:reverse] is `TRUE`, the animation will start at this value instead. a timed animation the value to animate to Whether the animation changes direction on every iteration. Duration of the animation, in milliseconds. Describes how much time the animation will take. If the animation repeats more than once, describes the duration of one iteration. Easing function used in the animation. Describes the curve the value is interpolated on. See [enum@Easing] for the description of specific easing functions. Number of times the animation will play. If set to 0, the animation will repeat endlessly. Whether the animation plays backwards. The value to animate from. The animation will start at this value and end at [property@TimedAnimation:value-to]. If [property@TimedAnimation:reverse] is `TRUE`, the animation will end at this value instead. The value to animate to. The animation will start at [property@TimedAnimation:value-from] and end at this value. If [property@TimedAnimation:reverse] is `TRUE`, the animation will start at this value instead. A helper object for [class@ToastOverlay]. Toasts are meant to be passed into [method@ToastOverlay.add_toast] as follows: ```c adw_toast_overlay_add_toast (overlay, adw_toast_new (_("Simple Toast"))); ``` <picture> <source srcset="toast-simple-dark.png" media="(prefers-color-scheme: dark)"> <img src="toast-simple.png" alt="toast-simple"> </picture> Toasts always have a close button. They emit the [signal@Toast::dismissed] signal when disappearing. [property@Toast:timeout] determines how long the toast stays on screen, while [property@Toast:priority] determines how it behaves if another toast is already being displayed. Toast titles use Pango markup by default, set [property@Toast:use-markup] to `FALSE` if this is unwanted. [property@Toast:custom-title] can be used to replace the title label with a custom widget. ## Actions Toasts can have one button on them, with a label and an attached [iface@Gio.Action]. ```c AdwToast *toast = adw_toast_new (_("Toast with Action")); adw_toast_set_button_label (toast, _("_Example")); adw_toast_set_action_name (toast, "win.example"); adw_toast_overlay_add_toast (overlay, toast); ``` <picture> <source srcset="toast-action-dark.png" media="(prefers-color-scheme: dark)"> <img src="toast-action.png" alt="toast-action"> </picture> ## Modifying toasts Toasts can be modified after they have been shown. For this, an `AdwToast` reference must be kept around while the toast is visible. A common use case for this is using toasts as undo prompts that stack with each other, allowing to batch undo the last deleted items: ```c static void toast_undo_cb (GtkWidget *sender, const char *action, GVariant *param) { // Undo the deletion } static void dismissed_cb (MyWindow *self) { self->undo_toast = NULL; // Permanently delete the items } static void delete_item (MyWindow *self, MyItem *item) { g_autofree char *title = NULL; int n_items; // Mark the item as waiting for deletion n_items = ... // The number of waiting items if (!self->undo_toast) { self->undo_toast = adw_toast_new_format (_("‘%s’ deleted"), ...); adw_toast_set_priority (self->undo_toast, ADW_TOAST_PRIORITY_HIGH); adw_toast_set_button_label (self->undo_toast, _("_Undo")); adw_toast_set_action_name (self->undo_toast, "toast.undo"); g_signal_connect_swapped (self->undo_toast, "dismissed", G_CALLBACK (dismissed_cb), self); adw_toast_overlay_add_toast (self->toast_overlay, self->undo_toast); return; } title = g_strdup_printf (ngettext ("<span font_features='tnum=1'>%d</span> item deleted", "<span font_features='tnum=1'>%d</span> items deleted", n_items), n_items); adw_toast_set_title (self->undo_toast, title); // Bump the toast timeout adw_toast_overlay_add_toast (self->toast_overlay, g_object_ref (self->undo_toast)); } static void my_window_class_init (MyWindowClass *klass) { GtkWidgetClass *widget_class = GTK_WIDGET_CLASS (klass); gtk_widget_class_install_action (widget_class, "toast.undo", NULL, toast_undo_cb); } ``` <picture> <source srcset="toast-undo-dark.png" media="(prefers-color-scheme: dark)"> <img src="toast-undo.png" alt="toast-undo"> </picture> Creates a new `AdwToast`. The toast will use @title as its title. @title can be marked up with the Pango text markup language. the new created `AdwToast` the title to be displayed Creates a new `AdwToast`. The toast will use the format string as its title. See also: [ctor@Toast.new] the newly created toast object the formatted string for the toast title the parameters to insert into the format string Dismisses @self. Does nothing if @self has already been dismissed, or hasn't been added to an [class@ToastOverlay]. a toast Gets the name of the associated action. the action name a toast Gets the parameter for action invocations. the action target a toast Gets the label to show on the button. the button label a toast Gets the custom title widget of @self. the custom title widget a toast Gets priority for @self. the priority a toast Gets timeout for @self. the timeout a toast Gets the title that will be displayed on the toast. If a custom title has been set with [method@Adw.Toast.set_custom_title] the return value will be %NULL. the title a toast Gets whether to use Pango markup for the toast title. whether the toast uses markup a toast Sets the name of the associated action. It will be activated when clicking the button. See [property@Toast:action-target]. a toast the action name Sets the parameter for action invocations. This is a convenience function that calls [ctor@GLib.Variant.new] for @format_string and uses the result to call [method@Toast.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@Toast.set_detailed_action_name]. a toast a variant format string arguments appropriate for @target_format Sets the parameter for action invocations. If the @action_target variant has a floating reference this function will sink it. a toast the action target Sets the label to show on the button. Underlines in the button text can be used to indicate a mnemonic. If set to `NULL`, the button won't be shown. See [property@Toast:action-name]. a toast a button label Sets the custom title widget of @self. It will be displayed instead of the title if set. In this case, [property@Toast:title] is ignored. Setting a custom title will unset [property@Toast:title]. a toast the custom title widget Sets the action name and its parameter. @detailed_action_name is a string in the format accepted by [func@Gio.Action.parse_detailed_name]. a toast the detailed action name Sets priority for @self. Priority controls how the toast behaves when another toast is already being displayed. If @priority is `ADW_TOAST_PRIORITY_NORMAL`, the toast will be queued. If @priority is `ADW_TOAST_PRIORITY_HIGH`, the toast will be displayed immediately, pushing the previous toast into the queue instead. a toast the priority Sets timeout for @self. If @timeout is 0, the toast is displayed indefinitely until manually dismissed. Toasts cannot disappear while being hovered, pressed (on touchscreen), or have keyboard focus inside them. a toast the timeout Sets the title that will be displayed on the toast. The title can be marked up with the Pango text markup language. Setting a title will unset [property@Toast:custom-title]. If [property@Toast:custom-title] is set, it will be used instead. a toast a title Whether to use Pango markup for the toast title. See also [func@Pango.parse_markup]. a toast whether to use markup The name of the associated action. It will be activated when clicking the button. See [property@Toast:action-target]. The parameter for action invocations. The label to show on the button. Underlines in the button text can be used to indicate a mnemonic. If set to `NULL`, the button won't be shown. See [property@Toast:action-name]. The custom title widget. It will be displayed instead of the title if set. In this case, [property@Toast:title] is ignored. Setting a custom title will unset [property@Toast:title]. The priority of the toast. Priority controls how the toast behaves when another toast is already being displayed. If the priority is `ADW_TOAST_PRIORITY_NORMAL`, the toast will be queued. If the priority is `ADW_TOAST_PRIORITY_HIGH`, the toast will be displayed immediately, pushing the previous toast into the queue instead. The timeout of the toast, in seconds. If timeout is 0, the toast is displayed indefinitely until manually dismissed. Toasts cannot disappear while being hovered, pressed (on touchscreen), or have keyboard focus inside them. The title of the toast. The title can be marked up with the Pango text markup language. Setting a title will unset [property@Toast:custom-title]. If [property@Toast:custom-title] is set, it will be used instead. Whether to use Pango markup for the toast title. See also [func@Pango.parse_markup]. Emitted after the button has been clicked. It can be used as an alternative to setting an action. Emitted when the toast has been dismissed. A widget showing toasts above its content. <picture> <source srcset="toast-overlay-dark.png" media="(prefers-color-scheme: dark)"> <img src="toast-overlay.png" alt="toast-overlay"> </picture> Much like [class@Gtk.Overlay], `AdwToastOverlay` is a container with a single main child, on top of which it can display a [class@Toast], overlaid. Toasts can be shown with [method@ToastOverlay.add_toast]. See [class@Toast] for details. ## CSS nodes ``` toastoverlay ├── [child] ├── toast ┊ ├── widget ┊ │ ├── [label.heading] │ ╰── [custom title] ├── [button] ╰── button.circular.flat ``` `AdwToastOverlay`'s CSS node is called `toastoverlay`. It contains the child, as well as zero or more `toast` subnodes. Each of the `toast` nodes contains a `widget` subnode, optionally a `button` subnode, and another `button` subnode with `.circular` and `.flat` style classes. The `widget` subnode contains a `label` subnode with the `.heading` style class, or a custom widget provided by the application. ## Accessibility `AdwToastOverlay` uses the `GTK_ACCESSIBLE_ROLE_TAB_GROUP` role. Creates a new `AdwToastOverlay`. the new created `AdwToastOverlay` Displays @toast. Only one toast can be shown at a time; if a toast is already being displayed, either @toast or the original toast will be placed in a queue, depending on the priority of @toast. See [property@Toast:priority]. If called on a toast that's already displayed, its timeout will be reset. If called on a toast currently in the queue, the toast will be bumped forward to be shown as soon as possible. a toast overlay a toast Gets the child widget of @self. the child widget of @self a toast overlay Sets the child widget of @self. a toast overlay the child widget The child widget. [class@Toast] behavior when another toast is already displayed. the toast will be queued if another toast is already displayed. the toast will be displayed immediately, pushing the previous toast into the queue instead. Describes the possible top or bottom bar styles in an [class@ToolbarView] widget. `ADW_TOOLBAR_FLAT` is suitable for simple content, such as [class@StatusPage] or [class@PreferencesPage], where the background at the top and bottom parts of the page is uniform. Additionally, windows with sidebars should always use this style. <picture style="min-width: 33%; display: inline-block;"> <source srcset="toolbar-view-flat-1-dark.png" media="(prefers-color-scheme: dark)"> <img src="toolbar-view-flat-1.png" alt="toolbar-view-flat-1"> </picture> <picture style="min-width: 33%; display: inline-block;"> <source srcset="toolbar-view-flat-2-dark.png" media="(prefers-color-scheme: dark)"> <img src="toolbar-view-flat-2.png" alt="toolbar-view-flat-2"> </picture> `ADW_TOOLBAR_RAISED` style is suitable for content such as [utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), where some elements are directly adjacent to the top/bottom bars, or [class@TabView], where each page can have a different background. `ADW_TOOLBAR_RAISED_BORDER` style is similar to `ADW_TOOLBAR_RAISED`, but with the shadow replaced with a more subtle border. It's intended to be used in applications like image viewers, where a shadow over the content might be undesired. <picture style="min-width: 33%; display: inline-block;"> <source srcset="toolbar-view-raised-dark.png" media="(prefers-color-scheme: dark)"> <img src="toolbar-view-raised.png" alt="toolbar-view-raised"> </picture> <picture style="min-width: 33%; display: inline-block;"> <source srcset="toolbar-view-raised-border-dark.png" media="(prefers-color-scheme: dark)"> <img src="toolbar-view-raised-border.png" alt="toolbar-view-raised-border"> </picture> See [property@ToolbarView:top-bar-style] and [property@ToolbarView:bottom-bar-style]. New values may be added to this enumeration over time. No background, shadow only for scrolled content Opaque background with a persistent shadow Opaque background with a persistent border A widget containing a page, as well as top and/or bottom bars. <picture> <source srcset="toolbar-view-dark.png" media="(prefers-color-scheme: dark)"> <img src="toolbar-view.png" alt="toolbar-view"> </picture> `AdwToolbarView` has a single content widget and one or multiple top and bottom bars, shown at the top and bottom sides respectively. Example of an `AdwToolbarView` UI definition: ```xml <object class="AdwToolbarView"> <child type="top"> <object class="AdwHeaderBar"/> </child> <property name="content"> <object class="AdwPreferencesPage"> <!-- ... --> </object> </property> </object> ``` The following kinds of top and bottom bars are supported: - [class@HeaderBar] - [class@TabBar] - [class@ViewSwitcherBar] - [class@Gtk.ActionBar] - [class@Gtk.HeaderBar] - [class@Gtk.PopoverMenuBar] - [class@Gtk.SearchBar] - Any [class@Gtk.Box] or a similar widget with the [`.toolbar`](style-classes.html#toolbars) style class By default, top and bottom bars are flat and scrolling content has a subtle undershoot shadow, same as when using the [`.undershoot-top`](style-classes.html#undershoot-indicators) and [`.undershoot-bottom`](style-classes.html#undershoot-indicators) style classes. This works well in most cases, e.g. with [class@StatusPage] or [class@PreferencesPage], where the background at the top and bottom parts of the page is uniform. Additionally, windows with sidebars should always use this style. [property@ToolbarView:top-bar-style] and [property@ToolbarView:bottom-bar-style] properties can be used add an opaque background and a persistent shadow to top and bottom bars, this can be useful for content such as [utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), where some elements are adjacent to the top/bottom bars, or [class@TabView], where each page can have a different background. <picture style="min-width: 33%; display: inline-block;"> <source srcset="toolbar-view-flat-1-dark.png" media="(prefers-color-scheme: dark)"> <img src="toolbar-view-flat-1.png" alt="toolbar-view-flat-1"> </picture> <picture style="min-width: 33%; display: inline-block;"> <source srcset="toolbar-view-flat-2-dark.png" media="(prefers-color-scheme: dark)"> <img src="toolbar-view-flat-2.png" alt="toolbar-view-flat-2"> </picture> <picture style="min-width: 33%; display: inline-block;"> <source srcset="toolbar-view-raised-dark.png" media="(prefers-color-scheme: dark)"> <img src="toolbar-view-raised.png" alt="toolbar-view-raised"> </picture> `AdwToolbarView` ensures the top and bottom bars have consistent backdrop styles and vertical spacing. For comparison: <picture style="min-width: 40%; display: inline-block;"> <source srcset="toolbar-view-spacing-dark.png" media="(prefers-color-scheme: dark)"> <img src="toolbar-view-spacing.png" alt="toolbar-view-spacing"> </picture> <picture style="min-width: 40%; display: inline-block;"> <source srcset="toolbar-view-spacing-box-dark.png" media="(prefers-color-scheme: dark)"> <img src="toolbar-view-spacing-box.png" alt="toolbar-view-spacing-box"> </picture> Any top and bottom bars can also be dragged to move the window, equivalent to putting them into a [class@Gtk.WindowHandle]. Content is typically place between top and bottom bars, but can also extend behind them. This is controlled with the [property@ToolbarView:extend-content-to-top-edge] and [property@ToolbarView:extend-content-to-bottom-edge] properties. Top and bottom bars can be hidden and revealed with an animation using the [property@ToolbarView:reveal-top-bars] and [property@ToolbarView:reveal-bottom-bars] properties. ## `AdwToolbarView` as `GtkBuildable` The `AdwToolbarView` implementation of the [iface@Gtk.Buildable] interface supports adding a top bar by specifying “top” as the “type” attribute of a `<child>` element, or adding a bottom bar by specifying “bottom”. ## Accessibility `AdwToolbarView` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. Creates a new `AdwToolbarView`. the newly created `AdwToolbarView` Adds a bottom bar to @self. a toolbar view a widget Adds a top bar to @self. a toolbar view a widget Gets the current bottom bar height for @self. Bottom bar height does change depending on [property@ToolbarView:reveal-bottom-bars], including during the transition. See [method@ToolbarView.get_top_bar_height]. the current bottom bar height a toolbar view Gets appearance of the botom bars for @self. bottom bar style a toolbar view Gets the content widget for @self. the content widget a toolbar view Gets whether the content widget can extend behind bottom bars. whether content extends behind bottom bars a toolbar view Gets whether the content widget can extend behind top bars. whether content extends behind top bars a toolbar view Gets whether bottom bars are revealed for @self. whether bottom bars are revealed a toolbar view Gets whether top bars are revealed for @self. whether top bars are revealed a toolbar view Gets the current top bar height for @self. Top bar height does change depending on [property@ToolbarView:reveal-top-bars], including during the transition. See [method@ToolbarView.get_bottom_bar_height]. the current top bar height a toolbar view Gets appearance of the top bars for @self. top bar style a toolbar view Removes a child from @self. a toolbar view the child to be removed Sets appearance of the bottom bars for @self. If set to `ADW_TOOLBAR_FLAT`, bottom bars are flat and scrolling content has a subtle undershoot shadow when touching them, same as the [`.undershoot-bottom`](style-classes.html#undershoot-indicators) style class. This works well for simple content, e.g. [class@StatusPage] or [class@PreferencesPage], where the background at the bottom of the page is uniform. Additionally, windows with sidebars should always use this style. Undershoot shadow is only present if a bottom bar is actually present and visible. It is also never present if [property@ToolbarView:extend-content-to-bottom-edge] is set to `TRUE`. If set to `ADW_TOOLBAR_RAISED`, bottom bars have an opaque background and a persistent shadow, this is suitable for content such as [utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), where some elements are directly adjacent to the bottom bars, or [class@TabView], where each page can have a different background. `ADW_TOOLBAR_RAISED_BORDER` is similar to `ADW_TOOLBAR_RAISED`, but the shadow is replaced with a more subtle border. This can be useful for applications like image viewers. See also [method@ToolbarView.set_top_bar_style]. a toolbar view bottom bar style Sets the content widget for @self. a toolbar view the content widget Sets whether the content widget can extend behind bottom bars. This can be used in combination with [property@ToolbarView:reveal-bottom-bars] to show and hide toolbars in fullscreen. See [method@ToolbarView.set_extend_content_to_top_edge]. a toolbar view whether content extends behind bottom bars Sets whether the content widget can extend behind top bars. This can be used in combination with [property@ToolbarView:reveal-top-bars] to show and hide toolbars in fullscreen. See [method@ToolbarView.set_extend_content_to_bottom_edge]. a toolbar view whether content extends behind top bars Sets whether bottom bars are revealed for @self. The transition will be animated. This can be used in combination with [property@ToolbarView:extend-content-to-bottom-edge] to show and hide toolbars in fullscreen. See [method@ToolbarView.set_reveal_top_bars]. a toolbar view whether to reveal bottom bars Sets whether top bars are revealed for @self. The transition will be animated. This can be used in combination with [property@ToolbarView:extend-content-to-top-edge] to show and hide toolbars in fullscreen. See [method@ToolbarView.set_reveal_bottom_bars]. a toolbar view whether to reveal top bars Sets appearance of the top bars for @self. If set to `ADW_TOOLBAR_FLAT`, top bars are flat and scrolling content has a subtle undershoot shadow when touching them, same as the [`.undershoot-top`](style-classes.html#undershoot-indicators) style class. This works well for simple content, e.g. [class@StatusPage] or [class@PreferencesPage], where the background at the top of the page is uniform. Additionally, windows with sidebars should always use this style. Undershoot shadow is only present if a top bar is actually present and visible. It is also never present if [property@ToolbarView:extend-content-to-top-edge] is set to `TRUE`. If set to `ADW_TOOLBAR_RAISED`, top bars have an opaque background and a persistent shadow, this is suitable for content such as [utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), where some elements are directly adjacent to the top bars, or [class@TabView], where each page can have a different background. `ADW_TOOLBAR_RAISED_BORDER` is similar to `ADW_TOOLBAR_RAISED`, but the shadow is replaced with a more subtle border. This can be useful for applications like image viewers. See also [method@ToolbarView.set_bottom_bar_style]. a toolbar view top bar style The current bottom bar height. Bottom bar height does change depending on [property@ToolbarView:reveal-bottom-bars], including during the transition. See [property@ToolbarView:top-bar-height]. Appearance of the bottom bars. If set to `ADW_TOOLBAR_FLAT`, bottom bars are flat and scrolling content has a subtle undershoot shadow when touching them, same as the [`.undershoot-bottom`](style-classes.html#undershoot-indicators) style class. This works well for simple content, e.g. [class@StatusPage] or [class@PreferencesPage], where the background at the bottom of the page is uniform. Additionally, windows with sidebars should always use this style. Undershoot shadow is only present if a bottom bar is actually present and visible. It is also never present if [property@ToolbarView:extend-content-to-bottom-edge] is set to `TRUE`. If set to `ADW_TOOLBAR_RAISED`, bottom bars have an opaque background and a persistent shadow, this is suitable for content such as [utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), where some elements are directly adjacent to the bottom bars, or [class@TabView], where each page can have a different background. `ADW_TOOLBAR_RAISED_BORDER` is similar to `ADW_TOOLBAR_RAISED`, but the shadow is replaced with a more subtle border. This can be useful for applications like image viewers. See also [property@ToolbarView:top-bar-style]. The content widget. Whether the content widget can extend behind bottom bars. This can be used in combination with [property@ToolbarView:reveal-bottom-bars] to show and hide toolbars in fullscreen. See [property@ToolbarView:extend-content-to-top-edge]. Whether the content widget can extend behind top bars. This can be used in combination with [property@ToolbarView:reveal-top-bars] to show and hide toolbars in fullscreen. See [property@ToolbarView:extend-content-to-bottom-edge]. Whether bottom bars are visible. The transition will be animated. This can be used in combination with [property@ToolbarView:extend-content-to-bottom-edge] to show and hide toolbars in fullscreen. See [property@ToolbarView:reveal-top-bars]. Whether top bars are revealed. The transition will be animated. This can be used in combination with [property@ToolbarView:extend-content-to-top-edge] to show and hide toolbars in fullscreen. See [property@ToolbarView:reveal-bottom-bars]. The current top bar height. Top bar height does change depending [property@ToolbarView:reveal-top-bars], including during the transition. See [property@ToolbarView:bottom-bar-height]. Appearance of the top bars. If set to `ADW_TOOLBAR_FLAT`, top bars are flat and scrolling content has a subtle undershoot shadow when touching them, same as the [`.undershoot-top`](style-classes.html#undershoot-indicators) style class. This works well for simple content, e.g. [class@StatusPage] or [class@PreferencesPage], where the background at the top of the page is uniform. Additionally, windows with sidebars should always use this style. Undershoot shadow is only present if a top bar is actually present and visible. It is also never present if [property@ToolbarView:extend-content-to-top-edge] is set to `TRUE`. If set to `ADW_TOOLBAR_RAISED`, top bars have an opaque background and a persistent shadow, this is suitable for content such as [utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), where some elements are directly adjacent to the top bars, or [class@TabView], where each page can have a different background. `ADW_TOOLBAR_RAISED_BORDER` is similar to `ADW_TOOLBAR_RAISED`, but the shadow is replaced with a more subtle border. This can be useful for applications like image viewers. See also [property@ToolbarView:bottom-bar-style]. Adwaita version, encoded as a string, useful for printing and concatenation. A view container for [class@ViewSwitcher]. `AdwViewStack` is a container which only shows one page at a time. It is typically used to hold an application's main views. It doesn't provide a way to transition between pages. Instead, a separate widget such as [class@ViewSwitcher] can be used with `AdwViewStack` to provide this functionality. `AdwViewStack` pages can have a title, an icon, an attention request, and a numbered badge that [class@ViewSwitcher] will use to let users identify which page is which. Set them using the [property@ViewStackPage:title], [property@ViewStackPage:icon-name], [property@ViewStackPage:needs-attention], and [property@ViewStackPage:badge-number] properties. Unlike [class@Gtk.Stack], transitions between views are not animated. `AdwViewStack` maintains a [class@ViewStackPage] object for each added child, which holds additional per-child properties. You obtain the [class@ViewStackPage] for a child with [method@ViewStack.get_page] and you can obtain a [iface@Gtk.SelectionModel] containing all the pages with [method@ViewStack.get_pages]. ## AdwViewStack as GtkBuildable To set child-specific properties in a .ui file, create [class@ViewStackPage] objects explicitly, and set the child widget as a property on it: ```xml <object class="AdwViewStack" id="stack"> <child> <object class="AdwViewStackPage"> <property name="name">overview</property> <property name="title">Overview</property> <property name="child"> <object class="AdwStatusPage"> <property name="title">Welcome!</property> </object> </property> </object> </child> </object> ``` ## CSS nodes `AdwViewStack` has a single CSS node named `stack`. ## Accessibility `AdwViewStack` uses the `GTK_ACCESSIBLE_ROLE_TAB_PANEL` for the stack pages which are the accessible parent objects of the child widgets. Creates a new `AdwViewStack`. the newly created `AdwViewStack` Adds a child to @self. the [class@ViewStackPage] for @child a view stack the widget to add Adds a child to @self. The child is identified by the @name. the `AdwViewStackPage` for @child a view stack the widget to add the name for @child Adds a child to @self. The child is identified by the @name. The @title will be used by [class@ViewSwitcher] to represent @child, so it should be short. the `AdwViewStackPage` for @child a view stack the widget to add the name for @child a human-readable title for @child Adds a child to @self. The child is identified by the @name. The @title and @icon_name will be used by [class@ViewSwitcher] to represent @child. the `AdwViewStackPage` for @child a view stack the widget to add the name for @child a human-readable title for @child an icon name for @child Finds the child with @name in @self. the requested child a view stack the name of the child to find Gets whether @self is horizontally homogeneous. whether @self is horizontally homogeneous a view stack Gets the [class@ViewStackPage] object for @child. the page object for @child a view stack a child of @self Returns a [iface@Gio.ListModel] 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 change the visible page. a `GtkSelectionModel` for the stack's children a view stack Gets whether @self is vertically homogeneous. whether @self is vertically homogeneous a view stack Gets the currently visible child of @self. the visible child a view stack Returns the name of the currently visible child of @self. the name of the visible child a view stack Removes a child widget from @self. a view stack the child to remove Sets @self to be horizontally homogeneous or not. If the stack is horizontally homogeneous, it allocates the same width for all children. If it's `FALSE`, the stack may change width when a different child becomes visible. a view stack whether to make @self horizontally homogeneous Sets @self to be vertically homogeneous or not. If the stack is vertically homogeneous, it allocates the same height for all children. If it's `FALSE`, the stack may change height when a different child becomes visible. a view stack whether to make @self vertically homogeneous Makes @child the visible child of @self. a view stack a child of @self Makes the child with @name visible. See [property@ViewStack:visible-child]. a view stack the name of the child Whether the stack is horizontally homogeneous. If the stack is horizontally homogeneous, it allocates the same width for all children. If it's `FALSE`, the stack may change width when a different child becomes visible. A selection model with the stack's pages. 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 change the visible page. Whether the stack is vertically homogeneous. If the stack is vertically homogeneous, it allocates the same height for all children. If it's `FALSE`, the stack may change height when a different child becomes visible. The widget currently visible in the stack. The name of the widget currently visible in the stack. See [property@ViewStack:visible-child]. An auxiliary class used by [class@ViewStack]. Gets the badge number for this page. the badge number for this page a view stack page Gets the stack child to which @self belongs. the child to which @self belongs a view stack page Gets the icon name of the page. the icon name of the page a view stack page Gets the name of the page. the name of the page a view stack page Gets whether the page requires the user attention. whether the page needs attention a view stack page Gets the page title. the page title a view stack page Gets whether underlines in the page title indicate mnemonics. whether underlines in the page title indicate mnemonics a view stack page Gets whether @self is visible in its `AdwViewStack`. This is independent from the [property@Gtk.Widget:visible] property of its widget. whether @self is visible a view stack page Sets the badge number for this page. [class@ViewSwitcher] can display it as a badge next to the page icon. It is commonly used to display a number of unread items within the page. It can be used together with [property@ViewStack{age}:needs-attention]. a view stack page the new value to set Sets the icon name of the page. a view stack page the icon name Sets the name of the page. a view stack page the page name Sets whether the page requires the user attention. [class@ViewSwitcher] will display it as a dot next to the page icon. a view stack page the new value to set Sets the page title. a view stack page the page title Sets whether underlines in the page title indicate mnemonics. a view stack page the new value to set Sets whether @page is visible in its `AdwViewStack`. This is independent from the [property@Gtk.Widget:visible] property of [property@ViewStackPage:child]. a view stack page whether @self is visible The badge number for this page. [class@ViewSwitcher] can display it as a badge next to the page icon. It is commonly used to display a number of unread items within the page. It can be used together with [property@ViewStack{age}:needs-attention]. The stack child to which the page belongs. The icon name of the child page. The name of the child page. Whether the page requires the user attention. [class@ViewSwitcher] will display it as a dot next to the page icon. The title of the child page. Whether an embedded underline in the title indicates a mnemonic. Whether this page is visible. This is independent from the [property@Gtk.Widget:visible] property of [property@ViewStackPage:child]. An auxiliary class used by [class@ViewStack]. See [property@ViewStack:pages]. Gets the [class@ViewStackPage] for the visible child of a view stack Gets the [class@ViewStackPage] for the visible child of the associated stack. Returns `NULL` if there's no selected page. the stack page a [class@ViewStackPages] Sets the visible child in the associated [class@ViewStack]. See [property@ViewStack:visible-child]. a [class@ViewStackPages] a stack page within the associated stack The selected [class@ViewStackPage] within the [class@ViewStackPages]. This can be used to keep an up-to-date view of the [class@ViewStackPage] for The visible [class@ViewStackPage] within the associated [class@ViewStackPages]. This can be used to keep an up-to-date view of the visible child. An adaptive view switcher. <picture> <source srcset="view-switcher-dark.png" media="(prefers-color-scheme: dark)"> <img src="view-switcher.png" alt="view-switcher"> </picture> An adaptive view switcher designed to switch between multiple views contained in a [class@ViewStack] in a similar fashion to [class@Gtk.StackSwitcher]. `AdwViewSwitcher` buttons always have an icon and a label. They can be displayed side by side, or icon on top of the label. This can be controlled via the [property@ViewSwitcher:policy] property. `AdwViewSwitcher` is intended to be used in a header bar together with [class@ViewSwitcherBar] at the bottom of the window, and a [class@Breakpoint] showing the view switcher bar on narrow sizes, while removing the view switcher from the header bar, as follows: ```xml <object class="AdwWindow"> <child> <object class="AdwBreakpoint"> <condition>max-width: 550sp</condition> <setter object="switcher_bar" property="reveal">True</setter> <setter object="header_bar" property="title-widget"/> </object> </child> <property name="content"> <object class="AdwToolbarView"> <child type="top"> <object class="AdwHeaderBar" id="header_bar"> <property name="title-widget"> <object class="AdwViewSwitcher"> <property name="stack">stack</property> <property name="policy">wide</property> </object> </property> </object> </child> <property name="content"> <object class="AdwViewStack" id="stack"/> </property> <child type="bottom"> <object class="AdwViewSwitcherBar" id="switcher_bar"> <property name="stack">stack</property> </object> </child> </object> </property> </object> ``` It's recommended to set [property@ViewSwitcher:policy] to `ADW_VIEW_SWITCHER_POLICY_WIDE` in this case. You may have to adjust the breakpoint condition for your specific pages. ## CSS nodes `AdwViewSwitcher` has a single CSS node with name `viewswitcher`. It can have the style classes `.wide` and `.narrow`, matching its policy. ## Accessibility `AdwViewSwitcher` uses the `GTK_ACCESSIBLE_ROLE_TAB_LIST` role and uses the `GTK_ACCESSIBLE_ROLE_TAB` for its buttons. Creates a new `AdwViewSwitcher`. the newly created `AdwViewSwitcher` Gets the policy of @self. the policy of @self a view switcher Gets the stack controlled by @self. the stack a view switcher Sets the policy of @self. a view switcher the new policy Sets the stack controlled by @self. a view switcher a stack The policy to determine which mode to use. The stack the view switcher controls. A view switcher action bar. <picture> <source srcset="view-switcher-bar-dark.png" media="(prefers-color-scheme: dark)"> <img src="view-switcher-bar.png" alt="view-switcher-bar"> </picture> An action bar letting you switch between multiple views contained in a [class@ViewStack], via an [class@ViewSwitcher]. It is designed to be put at the bottom of a window and to be revealed only on really narrow windows, e.g. on mobile phones. It can't be revealed if there are less than two pages. `AdwViewSwitcherBar` is intended to be used together with `AdwViewSwitcher` in a header bar, and a [class@Breakpoint] showing the view switcher bar on narrow sizes, while removing the view switcher from the header bar, as follows: ```xml <object class="AdwWindow"> <child> <object class="AdwBreakpoint"> <condition>max-width: 550sp</condition> <setter object="switcher_bar" property="reveal">True</setter> <setter object="header_bar" property="title-widget"/> </object> </child> <property name="content"> <object class="AdwToolbarView"> <child type="top"> <object class="AdwHeaderBar" id="header_bar"> <property name="title-widget"> <object class="AdwViewSwitcher"> <property name="stack">stack</property> <property name="policy">wide</property> </object> </property> </object> </child> <property name="content"> <object class="AdwViewStack" id="stack"/> </property> <child type="bottom"> <object class="AdwViewSwitcherBar" id="switcher_bar"> <property name="stack">stack</property> </object> </child> </object> </property> </object> ``` It's recommended to set [property@ViewSwitcher:policy] to `ADW_VIEW_SWITCHER_POLICY_WIDE` in this case. You may have to adjust the breakpoint condition for your specific pages. ## CSS nodes `AdwViewSwitcherBar` has a single CSS node with name` viewswitcherbar`. Creates a new `AdwViewSwitcherBar`. the newly created `AdwViewSwitcherBar` Gets whether @self should be revealed or hidden. whether @self is revealed a view switcher bar Gets the stack controlled by @self. the stack a view switcher bar Sets whether @self should be revealed or hidden. a view switcher bar whether to reveal @self Sets the stack controlled by @self. a view switcher bar a stack Whether the bar should be revealed or hidden. The stack the view switcher controls. Describes the adaptive modes of [class@ViewSwitcher]. Force the narrow mode Force the wide mode A view switcher title. <picture> <source srcset="view-switcher-title-dark.png" media="(prefers-color-scheme: dark)"> <img src="view-switcher-title.png" alt="view-switcher-title"> </picture> A widget letting you switch between multiple views contained by a [class@ViewStack] via an [class@ViewSwitcher]. It is designed to be used as the title widget of a [class@HeaderBar], and will display the window's title when the window is too narrow to fit the view switcher e.g. on mobile phones, or if there are less than two views. In order to center the title in narrow windows, the header bar should have [property@HeaderBar:centering-policy] set to `ADW_CENTERING_POLICY_STRICT`. `AdwViewSwitcherTitle` is intended to be used together with [class@ViewSwitcherBar]. A common use case is to bind the [property@ViewSwitcherBar:reveal] property to [property@ViewSwitcherTitle:title-visible] to automatically reveal the view switcher bar when the title label is displayed in place of the view switcher, as follows: ```xml <object class="AdwWindow"> <property name="content"> <object class="AdwToolbarView"> <child type="top"> <object class="AdwHeaderBar"> <property name="centering-policy">strict</property> <property name="title-widget"> <object class="AdwViewSwitcherTitle" id="title"> <property name="stack">stack</property> </object> </property> </object> </child> <property name="content"> <object class="AdwViewStack" id="stack"/> </property> <child type="bottom"> <object class="AdwViewSwitcherBar"> <property name="stack">stack</property> <binding name="reveal"> <lookup name="title-visible">title</lookup> </binding> </object> </child> </object> </property> </object> ``` ## CSS nodes `AdwViewSwitcherTitle` has a single CSS node with name `viewswitchertitle`. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) Creates a new `AdwViewSwitcherTitle`. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) the newly created `AdwViewSwitcherTitle` Gets the stack controlled by @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) the stack a view switcher title Gets the subtitle of @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) the subtitle a view switcher title Gets the title of @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) the title a view switcher title Gets whether the title of @self is currently visible. If the title is visible, it means the view switcher is hidden an it may be wanted to show an alternative switcher, e.g. a [class@ViewSwitcherBar]. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) whether the title of @self is currently visible a view switcher title Gets whether @self's view switcher is enabled. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) whether the view switcher is enabled a view switcher title Sets the stack controlled by @self. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) a view switcher title a stack Sets the subtitle of @self. The subtitle should give the user additional details. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) a view switcher title a subtitle Sets the title of @self. The title typically identifies the current view or content item, and generally does not use the application name. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) a view switcher title a title Sets whether @self's view switcher is enabled. If it is disabled, the title will be displayed instead. This allows to programmatically hide the view switcher even if it fits in the available space. This can be used e.g. to ensure the view switcher is hidden below a certain window width, or any other constraint you find suitable. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) a view switcher title whether the view switcher is enabled The stack the view switcher controls. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) The subtitle to display. The subtitle should give the user additional details. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) The title to display. The title typically identifies the current view or content item, and generally does not use the application name. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) Whether the title is currently visible. If the title is visible, it means the view switcher is hidden an it may be wanted to show an alternative switcher, e.g. a [class@ViewSwitcherBar]. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) Whether the view switcher is enabled. If it is disabled, the title will be displayed instead. This allows to programmatically hide the view switcher even if it fits in the available space. This can be used e.g. to ensure the view switcher is hidden below a certain window width, or any other constraint you find suitable. See [the migration guide](migrating-to-breakpoints.html#replace-adwviewswitchertitle) A freeform window. <picture> <source srcset="window-dark.png" media="(prefers-color-scheme: dark)"> <img src="window.png" alt="window"> </picture> The `AdwWindow` widget is a subclass of [class@Gtk.Window] which has no titlebar area. Instead, [class@ToolbarView] can be used together with [class@HeaderBar] or [class@Gtk.HeaderBar] as follows: ```xml <object class="AdwWindow"> <property name="content"> <object class="AdwToolbarView"> <child type="top"> <object class="AdwHeaderBar"/> </child> <property name="content"> <!-- ... --> </property> </object> </property> </object> ``` Using [property@Gtk.Window:titlebar] or [property@Gtk.Window:child] is not supported and will result in a crash. Use [property@Window:content] instead. ## Dialogs `AdwWindow` can contain [class@Dialog]. Use [method@Dialog.present] with the window or a widget within a window to show a dialog. ## Breakpoints `AdwWindow` can be used with [class@Breakpoint] the same way as [class@BreakpointBin]. Refer to that widget's documentation for details. Example: ```xml <object class="AdwWindow"> <property name="content"> <object class="AdwToolbarView"> <child type="top"> <object class="AdwHeaderBar"/> </child> <property name="content"> <!-- ... --> </property> <child type="bottom"> <object class="GtkActionBar" id="bottom_bar"> <property name="revealed">True</property> <property name="visible">False</property> </object> </child> </object> </property> <child> <object class="AdwBreakpoint"> <condition>max-width: 500px</condition> <setter object="bottom_bar" property="visible">True</setter> </object> </child> </object> ``` When breakpoints are used, the minimum size must be larger than the smallest UI state. `AdwWindow` defaults to the minimum size of 360×200 px. If that's too small, set the [property@Gtk.Widget:width-request] and [property@Gtk.Widget:height-request] properties manually. Creates a new `AdwWindow`. the newly created `AdwWindow` Adds @breakpoint to @self. a window the breakpoint to add Gets the content widget of @self. This method should always be used instead of [method@Gtk.Window.get_child]. the content widget of @self a window Gets the current breakpoint. the current breakpoint a window Returns a [iface@Gio.ListModel] that contains the open dialogs of @self. This can be used to keep an up-to-date view. a list model for the dialogs of @self a window Returns the currently visible dialog in @self, if there's one. the visible dialog a window Sets the content widget of @self. This method should always be used instead of [method@Gtk.Window.set_child]. a window the content widget The content widget. This property should always be used instead of [property@Gtk.Window:child]. The current breakpoint. The open dialogs. The currently visible dialog A helper widget for setting a window's title and subtitle. <picture> <source srcset="window-title-dark.png" media="(prefers-color-scheme: dark)"> <img src="window-title.png" alt="window-title"> </picture> `AdwWindowTitle` shows a title and subtitle. It's intended to be used as the title child of [class@Gtk.HeaderBar] or [class@HeaderBar]. ## CSS nodes `AdwWindowTitle` has a single CSS node with name `windowtitle`. Creates a new `AdwWindowTitle`. the newly created `AdwWindowTitle` a title a subtitle Gets the subtitle of @self. the subtitle a window title Gets the title of @self. the title a window title Sets the subtitle of @self. The subtitle should give the user additional details. a window title a subtitle Sets the title of @self. The title typically identifies the current view or content item, and generally does not use the application name. a window title a title The subtitle to display. The subtitle should give the user additional details. The title to display. The title typically identifies the current view or content item, and generally does not use the application name. Converts @self to a `GdkRGBA` representing its background color. The matching foreground color is white. an accent color return location for the color Converts @self to a `GdkRGBA` representing its standalone color. It will typically be darker for light background, and lighter for dark background, ensuring contrast. an accent color Whether to calculate standalone color for light or dark background return location for the color Parses a condition from a string. Length conditions are specified as `<type>: <value>[<unit>]`, where: - `<type>` can be `min-width`, `max-width`, `min-height` or `max-height` - `<value>` is a fractional number - `<unit>` can be `px`, `pt` or `sp` If the unit is omitted, `px` is assumed. See [ctor@BreakpointCondition.new_length]. Examples: - `min-width: 500px` - `min-height: 400pt` - `max-width: 100sp` - `max-height: 500` Ratio conditions are specified as `<type>: <width>[/<height>]`, where: - `<type>` can be `min-aspect-ratio` or `max-aspect-ratio` - `<width>` and `<height>` are integer numbers See [ctor@BreakpointCondition.new_ratio]. The ratio is represented as `<width>` divided by `<height>`. If `<height>` is omitted, it's assumed to be 1. Examples: - `min-aspect-ratio: 4/3` - `max-aspect-ratio: 1` The logical operators `and`, `or` can be used to compose a complex condition as follows: - `<condition> and <condition>`: the condition is true when both `<condition>`s are true, same as when using [ctor@BreakpointCondition.new_and] - `<condition> or <condition>`: the condition is true when either of the `<condition>`s is true, same as when using [ctor@BreakpointCondition.new_or] Examples: - `min-width: 400px and max-aspect-ratio: 4/3` - `max-width: 360sp or max-width: 360px` Conditions can be further nested using parentheses, for example: - `min-width: 400px and (max-aspect-ratio: 4/3 or max-height: 400px)` If parentheses are omitted, the first operator takes priority. the parsed condition the string specifying the condition Computes easing with @easing for @value. @value should generally be in the [0, 1] range. the easing for @value an easing value a value to ease Checks whether animations are enabled for @widget. This should be used when implementing an animated widget to know whether to animate it or not. whether animations are enabled for @widget a `GtkWidget` Returns the major version number of the Adwaita library. For example, in libadwaita version 1.2.3 this is 1. This function is in the library, so it represents the libadwaita library your code is running against. Contrast with the [const@MAJOR_VERSION] constant, which represents the major version of the libadwaita headers you have included when compiling your code. the major version number of the Adwaita library Returns the micro version number of the Adwaita library. For example, in libadwaita version 1.2.3 this is 3. This function is in the library, so it represents the libadwaita library your code is running against. Contrast with the [const@MAJOR_VERSION] constant, which represents the micro version of the libadwaita headers you have included when compiling your code. the micro version number of the Adwaita library Returns the minor version number of the Adwaita library. For example, in libadwaita version 1.2.3 this is 2. This function is in the library, so it represents the libadwaita library your code is running against. Contrast with the [const@MAJOR_VERSION] constant, which represents the minor version of the libadwaita headers you have included when compiling your code. the minor version number of the Adwaita library Initializes Libadwaita. This function can be used instead of [func@Gtk.init] as it initializes GTK implicitly. There's no need to call this function if you're using [class@Application]. If Libadwaita has already been initialized, the function will simply return. This makes sure translations, types, themes, and icons for the Adwaita library are set up properly. Use this function to check if libadwaita has been initialized with [func@init]. the initialization status Converts @value from pixels to @unit. the length in @unit a length unit a value in pixels settings to use, or `NULL` for default settings Converts @value from @unit to pixels. the length in pixels a length unit a value in @unit settings to use, or `NULL` for default settings Computes the linear interpolation between @a and @b for @t. the computed value the start the end the interpolation rate Adjusts @rgba to be suitable as a standalone color. It will typically be darker for light background, and lighter for dark background, ensuring contrast. a background color Whether to calculate standalone color for light or dark background return location for the standalone color A convenience function for showing an application’s about dialog. the parent widget the name of the first property value of first property, followed by more pairs of property name and value, `NULL`-terminated A convenience function for showing an application’s about dialog from AppStream metadata. See [ctor@AboutDialog.new_from_appdata] for details. the parent widget The resource to use The version to retrieve release notes for the name of the first property value of first property, followed by more pairs of property name and value, `NULL`-terminated A convenience function for showing an application’s about window. Use [func@show_about_dialog]. 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 A convenience function for showing an application’s about window from AppStream metadata. See [ctor@AboutWindow.new_from_appdata] for details. Use [func@show_about_dialog_from_appdata]. the parent top-level window The resource to use The version to retrieve release notes for the name of the first property value of first property, followed by more pairs of property name and value, `NULL`-terminated