Describes the possible states of an adw.animation.Animation.

The state can be controlled with adw.animation.Animation.play, adw.animation.Animation.pause, adw.animation.Animation.resume, adw.animation.Animation.reset and adw.animation.Animation.skip.

Describes length types for adw.breakpoint_condition.BreakpointCondition.

See adw.breakpoint_condition.BreakpointCondition.newLength.

New values may be added to this enumeration over time.

Describes ratio types for adw.breakpoint_condition.BreakpointCondition.

See adw.breakpoint_condition.BreakpointCondition.newRatio.

New values may be added to this enumeration over time.

Describes title centering behavior of a adw.header_bar.HeaderBar widget.

Application color schemes for adw.style_manager.StyleManager.colorScheme.

Describes the available presentation modes for adw.dialog.Dialog.

New values may be added to this enumeration over time.

See adw.dialog.Dialog.presentationMode.

Describes the available easing functions for use with adw.timed_animation.TimedAnimation.

New values may be added to this enumeration over time.

Describes the possible folding behavior of a adw.flap.Flap widget.

Describes transitions types of a adw.flap.Flap widget.

It determines the type of animation when transitioning between children in a adw.flap.Flap widget, as well as which areas can be swiped via adw.flap.Flap.swipeToOpen and adw.flap.Flap.swipeToClose.

Determines when adw.flap.Flap and adw.leaflet.Leaflet will fold.

Describes the possible transitions in a adw.leaflet.Leaflet widget.

New values may be added to this enumeration over time.

Describes length units.

New values may be added to this enumeration over time.

Describes the direction of a swipe navigation gesture.

Describes the possible styles of adw.alert_dialog.AlertDialog response buttons.

See adw.alert_dialog.AlertDialog.setResponseAppearance.

Describes the possible transitions in a adw.squeezer.Squeezer widget.

Describes available shortcuts in an adw.tab_view.TabView.

Shortcuts can be set with adw.tab_view.TabView.shortcuts, or added/removed individually with adw.tab_view.TabView.addShortcuts and adw.tab_view.TabView.removeShortcuts.

New values may be added to this enumeration over time.

adw.toast.Toast behavior when another toast is already displayed.

Describes the possible top or bottom bar styles in an adw.toolbar_view.ToolbarView widget.

adw.types.ToolbarStyle.Flat is suitable for simple content, such as adw.status_page.StatusPage or adw.preferences_page.PreferencesPage, where the background at the top and bottom parts of the page is uniform. Additionally, windows with sidebars should always use this style.

adw.types.ToolbarStyle.Raised style is suitable for content such as utility panes, where some elements are directly adjacent to the top/bottom bars, or adw.tab_view.TabView, where each page can have a different background.

adw.types.ToolbarStyle.RaisedBorder style is similar to adw.types.ToolbarStyle.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.

See adw.toolbar_view.ToolbarView.topBarStyle and adw.toolbar_view.ToolbarView.bottomBarStyle.

New values may be added to this enumeration over time.

Describes the adaptive modes of adw.view_switcher.ViewSwitcher.

A dialog showing information about the application.

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

adw.about_dialog.AboutDialog prominently displays the application's icon, name, developer name and version. They can be set with the adw.about_dialog.AboutDialog.applicationIcon, adw.about_dialog.AboutDialog.applicationName, adw.about_dialog.AboutDialog.developerName and adw.about_dialog.AboutDialog.version_ respectively.

What's New

adw.about_dialog.AboutDialog provides a way for applications to display their release notes, set with the adw.about_dialog.AboutDialog.releaseNotes property.

Release notes are formatted the same way as AppStream descriptions.

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 adw.about_dialog.AboutDialog.version_. Use adw.about_dialog.AboutDialog.releaseNotesVersion to override it.

Details

The Details page displays the application comments and links.

The comments can be set with the adw.about_dialog.AboutDialog.comments property. Unlike gtk.about_dialog.AboutDialog.comments, this string can be long and detailed. It can also contain links and Pango markup.

To set the application website, use adw.about_dialog.AboutDialog.website. To add extra links below the website, use adw.about_dialog.AboutDialog.addLink.

If the Details page doesn't have any other content besides website, the website will be displayed on the main page instead.

Troubleshooting

adw.about_dialog.AboutDialog displays the following two links on the main page:

• Support Questions, set with the adw.about_dialog.AboutDialog.supportUrl property,
• Report an Issue, set with the adw.about_dialog.AboutDialog.issueUrl property.

Additionally, applications can provide debugging information. It will be shown separately on the Troubleshooting page. Use the adw.about_dialog.AboutDialog.debugInfo 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.

adw.about_dialog.AboutDialog provides a quick way to save debug information to a file. When saving, adw.about_dialog.AboutDialog.debugInfoFilename would be used as the suggested filename.

Credits and Acknowledgements

The Credits page has the following default sections:

• Developers, set with the adw.about_dialog.AboutDialog.developers property,
• Designers, set with the adw.about_dialog.AboutDialog.designers property,
• Artists, set with the adw.about_dialog.AboutDialog.artists property,
• Documenters, set with the adw.about_dialog.AboutDialog.documenters property,
• Translators, set with the adw.about_dialog.AboutDialog.translatorCredits 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 adw.about_dialog.AboutDialog.addCreditSection to add them.

The Acknowledgements page can be used to acknowledge additional people and organizations for their non-development contributions. Use adw.about_dialog.AboutDialog.addAcknowledgementSection 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:

Legal

The Legal page displays the copyright and licensing information for the application and other modules.

The copyright string is set with the adw.about_dialog.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 adw.about_dialog.AboutDialog.licenseType property. If the application's license is not in the list, adw.about_dialog.AboutDialog.license can be used instead.

To add information about other modules, such as application dependencies or data, use adw.about_dialog.AboutDialog.addLegalSection.

Constructing

To make constructing an adw.about_dialog.AboutDialog as convenient as possible, you can use the function func@show_about_dialog which constructs and shows a dialog.

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/new",
                         "license-type", GTK_LICENSE_GPL_3_0,
                         "developers", developers,
                         "designers", designers,
                         "translator-credits", _("translator-credits"),
                         NULL);
}

CSS nodes

adw.about_dialog.AboutDialog has a main CSS node with the name dialog and the style class .about.

A window showing information about the application.

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

adw.about_window.AboutWindow prominently displays the application's icon, name, developer name and version. They can be set with the adw.about_window.AboutWindow.applicationIcon, adw.about_window.AboutWindow.applicationName, adw.about_window.AboutWindow.developerName and adw.about_window.AboutWindow.version_ respectively.

What's New

adw.about_window.AboutWindow provides a way for applications to display their release notes, set with the adw.about_window.AboutWindow.releaseNotes property.

Release notes are formatted the same way as AppStream descriptions.

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 adw.about_window.AboutWindow.version_. Use adw.about_window.AboutWindow.releaseNotesVersion to override it.

Details

The Details page displays the application comments and links.

The comments can be set with the adw.about_window.AboutWindow.comments property. Unlike gtk.about_dialog.AboutDialog.comments, this string can be long and detailed. It can also contain links and Pango markup.

To set the application website, use adw.about_window.AboutWindow.website. To add extra links below the website, use adw.about_window.AboutWindow.addLink.

If the Details page doesn't have any other content besides website, the website will be displayed on the main page instead.

Troubleshooting

adw.about_window.AboutWindow displays the following two links on the main page:

• Support Questions, set with the adw.about_window.AboutWindow.supportUrl property,
• Report an Issue, set with the adw.about_window.AboutWindow.issueUrl property.

Additionally, applications can provide debugging information. It will be shown separately on the Troubleshooting page. Use the adw.about_window.AboutWindow.debugInfo 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.

adw.about_window.AboutWindow provides a quick way to save debug information to a file. When saving, adw.about_window.AboutWindow.debugInfoFilename would be used as the suggested filename.

Credits and Acknowledgements

The Credits page has the following default sections:

• Developers, set with the adw.about_window.AboutWindow.developers property,
• Designers, set with the adw.about_window.AboutWindow.designers property,
• Artists, set with the adw.about_window.AboutWindow.artists property,
• Documenters, set with the adw.about_window.AboutWindow.documenters property,
• Translators, set with the adw.about_window.AboutWindow.translatorCredits 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 adw.about_window.AboutWindow.addCreditSection to add them.

The Acknowledgements page can be used to acknowledge additional people and organizations for their non-development contributions. Use adw.about_window.AboutWindow.addAcknowledgementSection 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:

Legal

The Legal page displays the copyright and licensing information for the application and other modules.

The copyright string is set with the adw.about_window.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 adw.about_window.AboutWindow.licenseType property. If the application's license is not in the list, adw.about_window.AboutWindow.license can be used instead.

To add information about other modules, such as application dependencies or data, use adw.about_window.AboutWindow.addLegalSection.

Constructing

To make constructing an adw.about_window.AboutWindow as convenient as possible, you can use the function func@show_about_window which constructs and shows a window.

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/new",
                         "license-type", GTK_LICENSE_GPL_3_0,
                         "developers", developers,
                         "designers", designers,
                         "translator-credits", _("translator-credits"),
                         NULL);
}

CSS nodes

adw.about_window.AboutWindow has a main CSS node with the name window and the style class .about.

A gtk.list_box_row.ListBoxRow used to present actions.

The adw.action_row.ActionRow 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.

adw.action_row.ActionRow 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 adw.action_row.ActionRow implementation of the gtk.buildable.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

adw.action_row.ActionRow 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.

adw.action_row.ActionRow can use the .property style class to emphasize the row subtitle instead of the row title, which is useful for displaying read-only properties.

A dialog presenting a message or a question.

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 adw.alert_dialog.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 adw.alert_dialog.AlertDialog.closeResponse 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, adw.alert_dialog.AlertDialog is closed automatically.

An example of using an alert dialog:

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

adw.alert_dialog.AlertDialog can also be used via the adw.alert_dialog.AlertDialog.choose method. This API follows the GIO async pattern, and the result can be obtained by calling adw.alert_dialog.AlertDialog.chooseFinish, for example:

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

adw.alert_dialog.AlertDialog 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 adw.alert_dialog.AlertDialog.setResponseEnabled and adw.alert_dialog.AlertDialog.setResponseAppearance for details.

Example of an adw.alert_dialog.AlertDialog UI definition:

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

A base class for animations.

adw.animation.Animation 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: adw.timed_animation.TimedAnimation and adw.spring_animation.SpringAnimation.

adw.animation.Animation will automatically skip the animation if adw.animation.Animation.widget is unmapped, or if gtk.settings.Settings.gtkEnableAnimations is FALSE.

The adw.animation.Animation.done signal can be used to perform an action after the animation ends, for example hiding a widget after animating its gtk.widget.Widget.opacity to 0.

adw.animation.Animation 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:

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 adw.animation.Animation object can be reused.

Represents a value adw.animation.Animation can animate.

A base class for Adwaita applications.

adw.application.Application handles library initialization by calling func@init in the default gio.application.Application.startup signal handler, in turn chaining up as required by gtk.application.Application. Therefore, any subclass of adw.application.Application should always chain up its startup handler before using any Adwaita or GTK API.

Automatic Resources

adw.application.Application will automatically load stylesheets located in the application's resource base path (see gio.application.Application.setResourceBasePath, 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 adw.style_manager.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 adw.style_manager.StyleManager.dark is TRUE.

A freeform application window.

adw.application_window.ApplicationWindow is a gtk.application_window.ApplicationWindow subclass providing the same features as adw.window.Window.

See adw.window.Window for details.

Example of an adw.application_window.ApplicationWindow UI definition:

<object class="AdwApplicationWindow">
  <property name="content">
    <object class="AdwToolbarView">
      <child type="top">
        <object class="AdwHeaderBar"/>
      </child>
      <property name="content">
        <!-- ... -->
      </property>
    </object>
  </property>
</object>

Using gtk.application.Application.menubar is not supported and may result in visual glitches.

A widget displaying an image, with a generated fallback.

adw.avatar.Avatar is a widget that shows a round avatar.

adw.avatar.Avatar generates an avatar with the initials of the adw.avatar.Avatar.text on top of a colored background.

The color is picked based on the hash of the adw.avatar.Avatar.text.

If adw.avatar.Avatar.showInitials is set to FALSE, adw.avatar.Avatar.iconName or avatar-default-symbolic is shown instead of the initials.

Use adw.avatar.Avatar.customImage to set a custom image.

CSS nodes

adw.avatar.Avatar has a single CSS node with name avatar.

A bar with contextual information.

Banners are hidden by default, use adw.banner.Banner.revealed to show them.

Banners have a title, set with adw.banner.Banner.title. Titles can be marked up with Pango markup, use adw.banner.Banner.useMarkup 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 adw.banner.Banner.buttonLabel. The button can be used with a gio.action.Action, or with the adw.banner.Banner.buttonClicked signal.

CSS nodes

adw.banner.Banner has a main CSS node with the name banner.

A widget with one child.

The adw.bin.Bin widget has only one child, set with the adw.bin.Bin.child property.

It is useful for deriving subclasses, since it provides common code needed for handling a single child widget.

Describes a breakpoint for adw.window.Window or adw.dialog.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, adw.breakpoint.Breakpoint.apply and adw.breakpoint.Breakpoint.unapply can be used instead.

Breakpoints can be used within adw.window.Window, adw.application_window.ApplicationWindow, adw.dialog.Dialog or adw.breakpoint_bin.BreakpointBin.

adw.breakpoint.Breakpoint as gtk.buildable.Buildable:

adw.breakpoint.Breakpoint supports specifying its condition via the <condition> element. The contents of the element must be a string in a format accepted by adw.breakpoint_condition.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 adw.breakpoint.Breakpoint UI definition:

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

A widget that changes layout based on available size.

adw.breakpoint_bin.BreakpointBin provides a way to use breakpoints without adw.window.Window, adw.application_window.ApplicationWindow or adw.dialog.Dialog. It can be useful for limiting breakpoints to a single page and similar purposes. Most applications shouldn't need it.

adw.breakpoint_bin.BreakpointBin is similar to adw.bin.Bin. It has one child, set via the adw.breakpoint_bin.BreakpointBin.child property.

When adw.breakpoint_bin.BreakpointBin is resized, its child widget can rearrange its layout at specific thresholds.

The thresholds and layout changes are defined via adw.breakpoint.Breakpoint objects. They can be added using adw.breakpoint_bin.BreakpointBin.addBreakpoint.

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 adw.breakpoint.Breakpoint.apply and adw.breakpoint.Breakpoint.unapply can be used instead for more complex scenarios.

Breakpoints are only allowed to modify widgets inside the adw.breakpoint_bin.BreakpointBin, but not on the adw.breakpoint_bin.BreakpointBin 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 adw.breakpoint_bin.BreakpointBin.currentBreakpoint 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 adw.breakpoint_bin.BreakpointBin will result in it having no minimum size. The gtk.widget.Widget.widthRequest and gtk.widget.Widget.heightRequest 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 gtk.label.Label this can be done via gtk.label.Label.ellipsize, or via gtk.label.Label.wrap together with gtk.label.Label.wrapMode.

For buttons, use gtk.button.Button.canShrink, gtk.menu_button.MenuButton.canShrink, adw.split_button.SplitButton.canShrink, or adw.button_content.ButtonContent.canShrink.

Example

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

adw.breakpoint_bin.BreakpointBin as gtk.buildable.Buildable

adw.breakpoint_bin.BreakpointBin allows adding adw.breakpoint.Breakpoint objects as children.

Example of an adw.breakpoint_bin.BreakpointBin UI definition:

<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 adw.breakpoint.Breakpoint documentation for details.

Describes condition for an adw.breakpoint.Breakpoint.

A helper widget for creating buttons.

adw.button_content.ButtonContent is a box-like widget with an icon and a label.

It's intended to be used as a direct child of gtk.button.Button, gtk.menu_button.MenuButton or adw.split_button.SplitButton, when they need to have both an icon and a label, as follows:

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

adw.button_content.ButtonContent handles style classes and connecting the mnemonic to the button automatically.

CSS nodes

buttoncontent
╰── box
    ├── image
    ╰── label

adw.button_content.ButtonContent'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 gtk.button.Button or adw.split_button.SplitButton, the button will receive the .image-text-button style class. When inside a gtk.menu_button.MenuButton, the internal gtk.button.Button will receive it instead.

Accessibility

adw.button_content.ButtonContent uses the gtk.types.AccessibleRole.Group role.

An adw.animation_target.AnimationTarget that calls a given callback during the animation.

A paginated scrolling widget.

The adw.carousel.Carousel widget can be used to display a set of pages with swipe-based navigation between them.

adw.carousel_indicator_dots.CarouselIndicatorDots and adw.carousel_indicator_lines.CarouselIndicatorLines can be used to provide page indicators for adw.carousel.Carousel.

CSS nodes

adw.carousel.Carousel has a single CSS node with name carousel.

A dots indicator for adw.carousel.Carousel.

The adw.carousel_indicator_dots.CarouselIndicatorDots widget shows a set of dots for each page of a given adw.carousel.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 adw.carousel_indicator_lines.CarouselIndicatorLines.

CSS nodes

adw.carousel_indicator_dots.CarouselIndicatorDots has a single CSS node with name carouselindicatordots.

A lines indicator for adw.carousel.Carousel.

The adw.carousel_indicator_lines.CarouselIndicatorLines widget shows a set of lines for each page of a given adw.carousel.Carousel. The carousel's active page is shown as another line that moves between them to match the carousel's position.

See also adw.carousel_indicator_dots.CarouselIndicatorDots.

CSS nodes

adw.carousel_indicator_lines.CarouselIndicatorLines has a single CSS node with name carouselindicatorlines.

A widget constraining its child to a given size.

The adw.clamp.Clamp 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.

adw.clamp.Clamp can scale with the text scale factor, use the adw.clamp.Clamp.unit property to enable that behavior.

See also: adw.clamp_layout.ClampLayout, adw.clamp_scrollable.ClampScrollable.

CSS nodes

adw.clamp.Clamp has a single CSS node with name clamp.

A layout manager constraining its children to a given size.

adw.clamp_layout.ClampLayout 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.

adw.clamp_layout.ClampLayout can scale with the text scale factor, use the adw.clamp_layout.ClampLayout.unit property to enable that behavior.

See also: adw.clamp.Clamp, adw.clamp_scrollable.ClampScrollable.

A scrollable adw.clamp.Clamp.

adw.clamp_scrollable.ClampScrollable is a variant of adw.clamp.Clamp that implements the gtk.scrollable.Scrollable interface.

The primary use case for adw.clamp_scrollable.ClampScrollable is clamping gtk.list_view.ListView.

See also: adw.clamp_layout.ClampLayout.

A gtk.list_box_row.ListBoxRow used to choose from a list of items.

The adw.combo_row.ComboRow 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 adw.combo_row.ComboRow UI definition:

<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 adw.combo_row.ComboRow.selected and adw.combo_row.ComboRow.selectedItem properties can be used to keep track of the selected item and react to their changes.

adw.combo_row.ComboRow mirrors gtk.drop_down.DropDown, see that widget for details.

adw.combo_row.ComboRow is gtk.list_box_row.ListBoxRow.activatable if a model is set.

CSS nodes

adw.combo_row.ComboRow 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 gtk.scrolled_window.ScrolledWindow, which in turn contains a gtk.list_view.ListView, both are accessible via their regular nodes.

Accessibility

adw.combo_row.ComboRow uses the gtk.types.AccessibleRole.ComboBox role.

An adaptive dialog container.

adw.dialog.Dialog is similar to a window, but is shown within another window. It can be used with adw.window.Window and adw.application_window.ApplicationWindow, use adw.dialog.Dialog.present to show it.

adw.dialog.Dialog is not resizable. Use the adw.dialog.Dialog.contentWidth and adw.dialog.Dialog.contentHeight properties to set its size, or set adw.dialog.Dialog.followsContentSize to TRUE to make the dialog track the content's size as it changes. adw.dialog.Dialog can never be larger than its parent window.

adw.dialog.Dialog can be presented as a centered floating window or a bottom sheet. By default it's automatic depending on the available size. adw.dialog.Dialog.presentationMode can be used to change that.

adw.dialog.Dialog can be closed via adw.dialog.Dialog.close.

When presented as a bottom sheet, adw.dialog.Dialog can also be closed via swiping it down.

The adw.dialog.Dialog.canClose can be used to prevent closing. In that case, adw.dialog.Dialog.closeAttempt gets emitted instead.

Use adw.dialog.Dialog.forceClose to close the dialog even when can-close is set to FALSE.

Header Bar Integration

When placed inside an adw.dialog.Dialog, adw.header_bar.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 adw.header_bar.HeaderBar.showStartTitleButtons and adw.header_bar.HeaderBar.showEndTitleButtons to FALSE to remove it if it's unwanted.

Breakpoints

adw.dialog.Dialog can be used with adw.breakpoint.Breakpoint the same way as adw.breakpoint_bin.BreakpointBin. Refer to that widget's documentation for details.

Like adw.breakpoint_bin.BreakpointBin, if breakpoints are used, adw.dialog.Dialog doesn't have a minimum size, and gtk.widget.Widget.widthRequest and gtk.widget.Widget.heightRequest properties must be set manually.

A gtk.list_box_row.ListBoxRow with an embedded text entry.

adw.entry_row.EntryRow 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 adw.entry_row.EntryRow.showApplyButton is set to TRUE, adw.entry_row.EntryRow 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.

adw.entry_row.EntryRow provides only minimal API and should be used with the gtk.editable.Editable API.

See also adw.password_entry_row.PasswordEntryRow.

AdwEntryRow as GtkBuildable

The adw.entry_row.EntryRow implementation of the gtk.buildable.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

adw.entry_row.EntryRow has a single CSS node with name row and the .entry style class.

adw.enum_list_item.EnumListItem is the type of items in a adw.enum_list_model.EnumListModel.

A gio.list_model.ListModel representing values of a given enum.

adw.enum_list_model.EnumListModel contains objects of type adw.enum_list_item.EnumListItem.

A gtk.list_box_row.ListBoxRow used to reveal widgets.

The adw.expander_row.ExpanderRow 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 adw.expander_row.ExpanderRow implementation of the gtk.buildable.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

adw.expander_row.ExpanderRow 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.

An adaptive container acting like a box or an overlay.

The adw.flap.Flap widget can display its children like a gtk.box.Box does or like a gtk.overlay.Overlay does, according to the adw.flap.Flap.foldPolicy value.

adw.flap.Flap has at most three children: adw.flap.Flap.content, adw.flap.Flap.flap and adw.flap.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 adw.flap.Flap.revealFlap value, as well as via swipe gestures if adw.flap.Flap.swipeToOpen and/or adw.flap.Flap.swipeToClose 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.

adw.flap.Flap.flap is transparent by default; add the .background style class to it if this is unwanted.

If adw.flap.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 adw.flap.Flap.flapPosition value.

Folding the flap will automatically hide the flap widget, and unfolding it will automatically reveal it. If this behavior is not desired, the adw.flap.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 adw.flap.Flap implementation of the gtk.buildable.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

adw.flap.Flap 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.

A title bar widget.

adw.header_bar.HeaderBar is similar to gtk.header_bar.HeaderBar, but provides additional features compared to it. Refer to gtk.header_bar.HeaderBar for details. It is typically used as a top bar within adw.toolbar_view.ToolbarView.

Dialog Integration

When placed inside an adw.dialog.Dialog, adw.header_bar.HeaderBar 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 adw.header_bar.HeaderBar.showStartTitleButtons and adw.header_bar.HeaderBar.showEndTitleButtons to FALSE to remove it if it's unwanted.

Navigation View Integration

When placed inside an adw.navigation_page.NavigationPage, adw.header_bar.HeaderBar will display the page title instead of window title.

When used together with adw.navigation_view.NavigationView or adw.navigation_split_view.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 adw.header_bar.HeaderBar.showBackButton to FALSE to disable this behavior in rare scenarios where it's unwanted.

Split View Integration

When placed inside adw.navigation_split_view.NavigationSplitView or adw.overlay_split_view.OverlaySplitView, adw.header_bar.HeaderBar will automatically hide the title buttons other than at the edges of the window.

Centering Policy

adw.header_bar.HeaderBar.centeringPolicy allows to enforce strict centering of the title widget. This can be useful for entries inside adw.clamp.Clamp.

Title Buttons

Unlike gtk.header_bar.HeaderBar, adw.header_bar.HeaderBar allows to toggle title button visibility for each side individually, using the adw.header_bar.HeaderBar.showStartTitleButtons and adw.header_bar.HeaderBar.showEndTitleButtons 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

adw.header_bar.HeaderBar'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 gtk.window_controls.WindowControls for details, as well as other children.

When adw.header_bar.HeaderBar.showBackButton 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

adw.header_bar.HeaderBar uses the gtk.types.AccessibleRole.Group role.

An adaptive container acting like a box or a stack.

The adw.leaflet.Leaflet widget can display its children like a gtk.box.Box does or like a gtk.stack.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

adw.leaflet.Leaflet 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.

An auxiliary class used by adw.leaflet.Leaflet.

A dialog presenting a message or a question.

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 adw.message_dialog.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 adw.message_dialog.MessageDialog.closeResponse 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, adw.message_dialog.MessageDialog is closed automatically.

An example of using a message dialog:

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

adw.message_dialog.MessageDialog can also be used via the adw.message_dialog.MessageDialog.choose method. This API follows the GIO async pattern, and the result can be obtained by calling adw.message_dialog.MessageDialog.chooseFinish, for example:

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

adw.message_dialog.MessageDialog 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 adw.message_dialog.MessageDialog.setResponseEnabled and adw.message_dialog.MessageDialog.setResponseAppearance for details.

Example of an adw.message_dialog.MessageDialog UI definition:

<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

adw.message_dialog.MessageDialog uses the gtk.types.AccessibleRole.Dialog role.

A page within adw.navigation_view.NavigationView or adw.navigation_split_view.NavigationSplitView.

Each page has a child widget, a title and optionally a tag.

The adw.navigation_page.NavigationPage.showing, adw.navigation_page.NavigationPage.shown, adw.navigation_page.NavigationPage.hiding and adw.navigation_page.NavigationPage.hidden signals can be used to track the page's visibility within its adw.navigation_view.NavigationView.

Header Bar Integration

When placed inside adw.navigation_page.NavigationPage, adw.header_bar.HeaderBar will display the page title instead of window title.

When used together with adw.navigation_view.NavigationView, it will also display a back button that can be used to go back to the previous page. Set adw.header_bar.HeaderBar.showBackButton to FALSE to disable that behavior if it's unwanted.

CSS Nodes

adw.navigation_page.NavigationPage has a single CSS node with name navigation-view-page.

Accessibility

adw.navigation_page.NavigationPage uses the gtk.types.AccessibleRole.Group role.

A widget presenting sidebar and content side by side or as a navigation view.

adw.navigation_split_view.NavigationSplitView has two adw.navigation_page.NavigationPage children: sidebar and content, and displays them side by side.

When adw.navigation_split_view.NavigationSplitView.collapsed is set to TRUE, it instead puts both children inside an adw.navigation_view.NavigationView. The adw.navigation_split_view.NavigationSplitView.showContent controls which child is visible while collapsed.

See also adw.overlay_split_view.OverlaySplitView.

adw.navigation_split_view.NavigationSplitView is typically used together with an adw.breakpoint.Breakpoint setting the collapsed property to TRUE on small widths, as follows:

<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, adw.navigation_split_view.NavigationSplitView changes the sidebar width depending on its own width.

If possible, it tries to allocate a fraction of the total width, controlled with the adw.navigation_split_view.NavigationSplitView.sidebarWidthFraction property.

The sidebar also has minimum and maximum sizes, controlled with the adw.navigation_split_view.NavigationSplitView.minSidebarWidth and adw.navigation_split_view.NavigationSplitView.maxSidebarWidth properties.

The minimum and maximum sizes are using the length unit specified with the adw.navigation_split_view.NavigationSplitView.sidebarWidthUnit.

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 adw.navigation_split_view.NavigationSplitView, adw.header_bar.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 adw.navigation_view.NavigationView documentation for details.

Actions

adw.navigation_split_view.NavigationSplitView defines the same actions as adw.navigation_view.NavigationView, 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 adw.navigation_split_view.NavigationSplitView.showContent to TRUE.
• navigation.pop doesn't take any parameters and sets adw.navigation_split_view.NavigationSplitView.showContent to FALSE.

adw.navigation_split_view.NavigationSplitView as gtk.buildable.Buildable

The adw.navigation_split_view.NavigationSplitView implementation of the gtk.buildable.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

adw.navigation_split_view.NavigationSplitView 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

adw.navigation_split_view.NavigationSplitView uses the gtk.types.AccessibleRole.Group role.

A page-based navigation container.

adw.navigation_view.NavigationView presents one child at a time, similar to gtk.stack.Stack.

adw.navigation_view.NavigationView can only contain adw.navigation_page.NavigationPage children.

It maintains a navigation stack that can be controlled with adw.navigation_view.NavigationView.push and adw.navigation_view.NavigationView.pop. The whole navigation stack can also be replaced using adw.navigation_view.NavigationView.replace.

adw.navigation_view.NavigationView allows to manage pages statically or dynamically.

Static pages can be added using the adw.navigation_view.NavigationView.add method. The adw.navigation_view.NavigationView will keep a reference to these pages, but they aren't accessible to the user until adw.navigation_view.NavigationView.push is called (except for the first page, which is pushed automatically). Use the adw.navigation_view.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 adw.navigation_view.NavigationView.push method without calling adw.navigation_view.NavigationView.add first.

Tags

Static pages, as well as any pages in the navigation stack, can be accessed by their adw.navigation_page.NavigationPage.tag. For example, adw.navigation_view.NavigationView.pushByTag 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 adw.navigation_view.NavigationView, adw.header_bar.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 adw.header_bar.HeaderBar.showBackButton to FALSE to disable this behavior in rare scenarios where it's unwanted.

adw.header_bar.HeaderBar will also display the title of the adw.navigation_page.NavigationPage it's placed into, so most applications shouldn't need to customize it at all.

Shortcuts and Gestures

adw.navigation_view.NavigationView supports the following shortcuts for going to the previous page:

• <kbd>Escape</kbd> (unless adw.navigation_view.NavigationView.popOnEscape 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 adw.navigation_view.NavigationView.animateTransitions value.

Applications can also enable shortcuts for pushing another page onto the navigation stack via connecting to the adw.navigation_view.NavigationView.getNextPage 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.

adw.navigation_page.NavigationPage.canPop can be used to disable them, along with the header bar back buttons.

Actions

adw.navigation_view.NavigationView 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 adw.navigation_view.NavigationView.pushByTag.
• navigation.pop doesn't take any parameters and pops the current page from the navigation stack, equivalent to calling adw.navigation_view.NavigationView.pop.

adw.navigation_view.NavigationView as gtk.buildable.Buildable

adw.navigation_view.NavigationView allows to add pages as children, equivalent to using the adw.navigation_view.NavigationView.add method.

Example of an adw.navigation_view.NavigationView UI definition:

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

CSS nodes

adw.navigation_view.NavigationView has a single CSS node with the name navigation-view.

Accessibility

adw.navigation_view.NavigationView uses the gtk.types.AccessibleRole.Group role.

A widget presenting sidebar and content side by side or as an overlay.

adw.overlay_split_view.OverlaySplitView has two children: sidebar and content, and displays them side by side.

When adw.overlay_split_view.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 adw.overlay_split_view.OverlaySplitView.showSidebar property.

Sidebar can be displayed before or after the content, this can be controlled with the adw.overlay_split_view.OverlaySplitView.sidebarPosition property.

Collapsing the split view automatically hides the sidebar widget, and uncollapsing it shows the sidebar. If this behavior is not desired, the adw.overlay_split_view.OverlaySplitView.pinSidebar property can be used to override it.

adw.overlay_split_view.OverlaySplitView 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 adw.overlay_split_view.OverlaySplitView.enableShowGesture and adw.overlay_split_view.OverlaySplitView.enableHideGesture properties.

See also adw.navigation_split_view.NavigationSplitView.

adw.overlay_split_view.OverlaySplitView is typically used together with an adw.breakpoint.Breakpoint setting the collapsed property to TRUE on small widths, as follows:

<object class="AdwWindow">
  <property name="width-request">360</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="AdwOverlaySplitView" id="split_view">
      <property name="sidebar">
        <!-- ... -->
      </property>
      <property name="content">
        <!-- ... -->
      </property>
    </object>
  </property>
</object>

adw.overlay_split_view.OverlaySplitView is often used for implementing the utility pane pattern.

Sizing

When not collapsed, adw.overlay_split_view.OverlaySplitView changes the sidebar width depending on its own width.

If possible, it tries to allocate a fraction of the total width, controlled with the adw.overlay_split_view.OverlaySplitView.sidebarWidthFraction property.

The sidebar also has minimum and maximum sizes, controlled with the adw.overlay_split_view.OverlaySplitView.minSidebarWidth and adw.overlay_split_view.OverlaySplitView.maxSidebarWidth properties.

The minimum and maximum sizes are using the length unit specified with the adw.overlay_split_view.OverlaySplitView.sidebarWidthUnit.

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 adw.overlay_split_view.OverlaySplitView.maxSidebarWidth when possible.

Header Bar Integration

When used inside adw.overlay_split_view.OverlaySplitView, adw.header_bar.HeaderBar will automatically hide the window buttons in the middle.

adw.overlay_split_view.OverlaySplitView as gtk.buildable.Buildable

The adw.overlay_split_view.OverlaySplitView implementation of the gtk.buildable.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

adw.overlay_split_view.OverlaySplitView 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

adw.overlay_split_view.OverlaySplitView uses the gtk.types.AccessibleRole.Group role.

A adw.entry_row.EntryRow tailored for entering secrets.

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, adw.password_entry_row.PasswordEntryRow 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

adw.password_entry_row.PasswordEntryRow has a single CSS node with name row that carries .entry and .password style classes.

A dialog showing application's preferences.

The adw.preferences_dialog.PreferencesDialog widget presents an application's preferences gathered into pages and groups. The preferences are searchable by the user.

CSS nodes

adw.preferences_dialog.PreferencesDialog has a main CSS node with the name dialog and the style class .preferences.

A group of preference rows.

An adw.preferences_group.PreferencesGroup represents a group or tightly related preferences, which in turn are represented by adw.preferences_row.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 adw.preferences_dialog.PreferencesDialog to let the user look for a preference.

AdwPreferencesGroup as GtkBuildable

The adw.preferences_group.PreferencesGroup implementation of the gtk.buildable.Buildable interface supports adding adw.preferences_row.PreferencesRows to the list by omitting "type". If "type" is omitted and the widget isn't a adw.preferences_row.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

adw.preferences_group.PreferencesGroup has a single CSS node with name preferencesgroup.

Accessibility

adw.preferences_group.PreferencesGroup uses the gtk.types.AccessibleRole.Group role.

A page from adw.preferences_dialog.PreferencesDialog.

The adw.preferences_page.PreferencesPage widget gathers preferences groups into a single page of a preferences window.

CSS nodes

adw.preferences_page.PreferencesPage has a single CSS node with name preferencespage.

Accessibility

adw.preferences_page.PreferencesPage uses the gtk.types.AccessibleRole.Group role.

A gtk.list_box_row.ListBoxRow used to present preferences.

The adw.preferences_row.PreferencesRow widget has a title that adw.preferences_dialog.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.

adw.action_row.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.

A window to present an application's preferences.

The adw.preferences_window.PreferencesWindow widget presents an application's preferences gathered into pages and groups. The preferences are searchable by the user.

CSS nodes

adw.preferences_window.PreferencesWindow has a main CSS node with the name window and the style class .preferences.

An adw.animation_target.AnimationTarget changing the value of a property of a gobject.object.ObjectWrap instance.

An adw.action_row.ActionRow with an embedded spin button.

Example of an adw.spin_row.SpinRow UI definition:

<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 gtk.spin_button.SpinButton for details.

CSS nodes

adw.spin_row.SpinRow has the same structure as adw.action_row.ActionRow, as well as the .spin style class on the main node.

Accessibility

adw.spin_row.SpinRow uses an internal gtk.spin_button.SpinButton with the gtk.types.AccessibleRole.SpinButton role.

A combined button and dropdown widget.

adw.split_button.SplitButton 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 gtk.button.Button and gtk.menu_button.MenuButton, see their documentation for details.

CSS nodes

splitbutton[.image-button][.text-button]
├── button
│   ╰── <content>
├── separator
╰── menubutton
    ╰── button.toggle
        ╰── arrow

adw.split_button.SplitButton's CSS node is called splitbutton. It contains the css nodes: button, separator, menubutton. See gtk.menu_button.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

adw.split_button.SplitButton uses the gtk.types.AccessibleRole.Group role.

A spring-based adw.animation.Animation.

adw.spring_animation.SpringAnimation implements an animation driven by a physical model of a spring described by adw.spring_params.SpringParams, with a resting position in adw.spring_animation.SpringAnimation.valueTo, stretched to adw.spring_animation.SpringAnimation.valueFrom.

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 adw.spring_animation.SpringAnimation.epsilon, or immediately when it reaches adw.spring_animation.SpringAnimation.valueTo if adw.spring_animation.SpringAnimation.clamp is set to TRUE. The estimated duration can be obtained with adw.spring_animation.SpringAnimation.estimatedDuration.

Due to the nature of spring-driven motion the animation can overshoot adw.spring_animation.SpringAnimation.valueTo before coming to a rest. Whether the animation will overshoot or not depends on the damping ratio of the spring. See adw.spring_params.SpringParams for more information about specific damping ratio values.

If adw.spring_animation.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 adw.spring_animation.SpringAnimation.initialVelocity, 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.

Physical parameters of a spring for adw.spring_animation.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

A best fit container.

The adw.squeezer.Squeezer 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 adw.squeezer.Squeezer.transitionType.

CSS nodes

adw.squeezer.Squeezer has a single CSS node with name squeezer.

An auxiliary class used by adw.squeezer.Squeezer.

A page used for empty/error states and similar use-cases.

The adw.status_page.StatusPage widget can have an icon, a title, a description and a custom widget which is displayed below them.

CSS nodes

adw.status_page.StatusPage has a main CSS node with name statuspage.

adw.status_page.StatusPage can use the .compact style class for when it needs to fit into a small space such a sidebar or a popover.

A class for managing application-wide styling.

adw.style_manager.StyleManager provides a way to query and influence the application styles, such as whether to use dark or high contrast appearance.

It allows to set the color scheme via the adw.style_manager.StyleManager.colorScheme property, and to query the current appearance, as well as whether a system-wide color scheme preference exists.

A swipe tracker used in adw.carousel.Carousel, adw.navigation_view.NavigationView and adw.overlay_split_view.OverlaySplitView.

The adw.swipe_tracker.SwipeTracker 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 adw.swipe_tracker.SwipeTracker.enabled property. If they expect to use horizontal orientation, adw.swipe_tracker.SwipeTracker.reversed can be used for supporting RTL text direction.

An interface for swipeable widgets.

The adw.swipeable.Swipeable interface is implemented by all swipeable widgets.

See adw.swipe_tracker.SwipeTracker for details about implementing it.

An interface for swipeable widgets.

A gtk.list_box_row.ListBoxRow used to represent two states.

The adw.switch_row.SwitchRow widget contains a gtk.switch_.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 gtk.switch_.Switch for details.

Example of an adw.switch_row.SwitchRow UI definition:

<object class="AdwSwitchRow">
  <property name="title" translatable="yes">Switch Row</property>
  <signal name="notify::active" handler="switch_row_notify_active_cb"/>
</object>

The adw.switch_row.SwitchRow.active property should be connected to in order to monitor changes to the active state.

Accessibility

adw.switch_row.SwitchRow uses the gtk.types.AccessibleRole.Switch role.

A tab bar for adw.tab_view.TabView.

The adw.tab_bar.TabBar widget is a tab bar that can be used with conjunction with adw.tab_view.TabView. It is typically used as a top bar within adw.toolbar_view.ToolbarView.

adw.tab_bar.TabBar 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, adw.tab_bar.TabBar will scroll them. Pinned tabs always stay visible and aren't a part of the scrollable area.

CSS nodes

adw.tab_bar.TabBar has a single CSS node with name tabbar.

A button that displays the number of adw.tab_view.TabView pages.

adw.tab_button.TabButton is a button that displays the number of pages in a given adw.tab_view.TabView, 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 adw.tab_overview.TabOverview on click, e.g. via the overview.open action name:

<object class="AdwTabButton">
  <property name="view">view</property>
  <property name="action-name">overview.open</property>
</object>

CSS nodes

adw.tab_button.TabButton has a main CSS node with name tabbutton.

Accessibility

adw.tab_button.TabButton uses the gtk.types.AccessibleRole.Button role.

A tab overview for adw.tab_view.TabView.

adw.tab_overview.TabOverview is a widget that can display tabs from an adw.tab_view.TabView in a grid.

adw.tab_overview.TabOverview 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 adw.tab_page.TabPage.liveThumbnail to TRUE, or refreshed with adw.tab_page.TabPage.invalidateThumbnail or adw.tab_view.TabView.invalidateThumbnails otherwise.

If the pages are too tall or too wide, the thumbnails will be cropped; use adw.tab_page.TabPage.thumbnailXalign and adw.tab_page.TabPage.thumbnailYalign 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 adw.tab_bar.TabBar, they still have titles, as well as an unpin button.

adw.tab_overview.TabOverview provides search in open tabs. It searches in tab titles and tooltips, as well as adw.tab_page.TabPage.keyword.

If adw.tab_overview.TabOverview.enableNewTab is set to TRUE, a new tab button will be shown. Connect to the adw.tab_overview.TabOverview.createTab signal to use it.

adw.tab_overview.TabOverview.secondaryMenu 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.

adw.tab_overview.TabOverview is intended to be used as the direct child of the window, with the rest of the window contents set as the adw.tab_overview.TabOverview.child. The child is expected to contain an adw.tab_view.TabView.

adw.tab_overview.TabOverview shows window buttons by default. They can be disabled by setting adw.tab_overview.TabOverview.showStartTitleButtons and/or adw.tab_overview.TabOverview.showStartTitleButtons and/or adw.tab_overview.TabOverview.showEndTitleButtons to FALSE.

If search and window buttons are disabled, and secondary menu is not set, the header bar will be hidden.

Actions

adw.tab_overview.TabOverview defines the overview.open and overview.close actions for opening and closing itself. They can be convenient when used together with adw.tab_button.TabButton.

CSS nodes

adw.tab_overview.TabOverview has a single CSS node with name taboverview.

An auxiliary class used by adw.tab_view.TabView.

A dynamic tabbed container.

adw.tab_view.TabView 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 adw.tab_bar.TabBar, adw.tab_overview.TabOverview and adw.tab_button.TabButton.

adw.tab_view.TabView maintains a adw.tab_page.TabPage object for each page, which holds additional per-page properties. You can obtain the adw.tab_page.TabPage for a page with adw.tab_view.TabView.getPage, and as the return value for adw.tab_view.TabView.append and other functions for adding children.

adw.tab_view.TabView 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 gtk.notebook.Notebook for use cases such as tabbed dialogs.

As such, it does not support disabling page reordering or detaching.

adw.tab_view.TabView adds a number of global page switching and reordering shortcuts. The adw.tab_view.TabView.shortcuts property can be used to manage them.

See adw.types.TabViewShortcuts for the list of the available shortcuts. All of the shortcuts are enabled by default.

adw.tab_view.TabView.addShortcuts and adw.tab_view.TabView.removeShortcuts can be used to manage shortcuts in a convenient way, for example:

adw_tab_view_remove_shortcuts (view, ADW_TAB_VIEW_SHORTCUT_CONTROL_HOME |
                                     ADW_TAB_VIEW_SHORTCUT_CONTROL_END);

CSS nodes

adw.tab_view.TabView has a main CSS node with the name tabview.

Accessibility

adw.tab_view.TabView uses the gtk.types.AccessibleRole.TabPanel for the tab pages which are the accessible parent objects of the child widgets.

A time-based adw.animation.Animation.

adw.timed_animation.TimedAnimation implements a simple animation interpolating the given value from adw.timed_animation.TimedAnimation.valueFrom to adw.timed_animation.TimedAnimation.valueTo over adw.timed_animation.TimedAnimation.duration milliseconds using the curve described by adw.timed_animation.TimedAnimation.easing.

If adw.timed_animation.TimedAnimation.reverse is set to TRUE, adw.timed_animation.TimedAnimation will instead animate from adw.timed_animation.TimedAnimation.valueTo to adw.timed_animation.TimedAnimation.valueFrom, and the easing curve will be inverted.

The animation can repeat a certain amount of times, or endlessly, depending on the adw.timed_animation.TimedAnimation.repeatCount value. If adw.timed_animation.TimedAnimation.alternate is set to TRUE, it will also change the direction every other iteration.

A helper object for adw.toast_overlay.ToastOverlay.

Toasts are meant to be passed into adw.toast_overlay.ToastOverlay.addToast as follows:

adw_toast_overlay_add_toast (overlay, adw_toast_new (_("Simple Toast")));

Toasts always have a close button. They emit the adw.toast.Toast.dismissed signal when disappearing.

adw.toast.Toast.timeout determines how long the toast stays on screen, while adw.toast.Toast.priority determines how it behaves if another toast is already being displayed.

Toast titles use Pango markup by default, set adw.toast.Toast.useMarkup to FALSE if this is unwanted.

adw.toast.Toast.customTitle 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 gio.action.Action.

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

Modifying toasts

Toasts can be modified after they have been shown. For this, an adw.toast.Toast 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:

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

A widget showing toasts above its content.

Much like gtk.overlay.Overlay, adw.toast_overlay.ToastOverlay is a container with a single main child, on top of which it can display a adw.toast.Toast, overlaid. Toasts can be shown with adw.toast_overlay.ToastOverlay.addToast.

See adw.toast.Toast for details.

CSS nodes

toastoverlay
├── [child]
├── toast
┊   ├── widget
┊   │   ├── [label.heading]
    │   ╰── [custom title]
    ├── [button]
    ╰── button.circular.flat

adw.toast_overlay.ToastOverlay'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

adw.toast_overlay.ToastOverlay uses the GTK_ACCESSIBLE_ROLE_TAB_GROUP role.

A widget containing a page, as well as top and/or bottom bars.

adw.toolbar_view.ToolbarView has a single content widget and one or multiple top and bottom bars, shown at the top and bottom sides respectively.

Example of an adw.toolbar_view.ToolbarView UI definition:

<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:

• adw.header_bar.HeaderBar
• adw.tab_bar.TabBar
• adw.view_switcher_bar.ViewSwitcherBar
• gtk.action_bar.ActionBar
• gtk.header_bar.HeaderBar
• gtk.popover_menu_bar.PopoverMenuBar
• gtk.search_bar.SearchBar
• Any gtk.box.Box or a similar widget with the .toolbar 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 and .undershoot-bottom style classes. This works well in most cases, e.g. with adw.status_page.StatusPage or adw.preferences_page.PreferencesPage, where the background at the top and bottom parts of the page is uniform. Additionally, windows with sidebars should always use this style.

adw.toolbar_view.ToolbarView.topBarStyle and adw.toolbar_view.ToolbarView.bottomBarStyle 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, where some elements are adjacent to the top/bottom bars, or adw.tab_view.TabView, where each page can have a different background.

adw.toolbar_view.ToolbarView ensures the top and bottom bars have consistent backdrop styles and vertical spacing. For comparison:

Any top and bottom bars can also be dragged to move the window, equivalent to putting them into a gtk.window_handle.WindowHandle.

Content is typically place between top and bottom bars, but can also extend behind them. This is controlled with the adw.toolbar_view.ToolbarView.extendContentToTopEdge and adw.toolbar_view.ToolbarView.extendContentToBottomEdge properties.

Top and bottom bars can be hidden and revealed with an animation using the adw.toolbar_view.ToolbarView.revealTopBars and adw.toolbar_view.ToolbarView.revealBottomBars properties.

adw.toolbar_view.ToolbarView as gtk.buildable.Buildable

The adw.toolbar_view.ToolbarView implementation of the gtk.buildable.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

adw.toolbar_view.ToolbarView uses the gtk.types.AccessibleRole.Group role.

A view container for adw.view_switcher.ViewSwitcher.

adw.view_stack.ViewStack 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 adw.view_switcher.ViewSwitcher can be used with adw.view_stack.ViewStack to provide this functionality.

adw.view_stack.ViewStack pages can have a title, an icon, an attention request, and a numbered badge that adw.view_switcher.ViewSwitcher will use to let users identify which page is which. Set them using the adw.view_stack_page.ViewStackPage.title, adw.view_stack_page.ViewStackPage.iconName, adw.view_stack_page.ViewStackPage.needsAttention, and adw.view_stack_page.ViewStackPage.badgeNumber properties.

Unlike gtk.stack.Stack, transitions between views are not animated.

adw.view_stack.ViewStack maintains a adw.view_stack_page.ViewStackPage object for each added child, which holds additional per-child properties. You obtain the adw.view_stack_page.ViewStackPage for a child with adw.view_stack.ViewStack.getPage and you can obtain a gtk.selection_model.SelectionModel containing all the pages with adw.view_stack.ViewStack.getPages.

AdwViewStack as GtkBuildable

To set child-specific properties in a .ui file, create adw.view_stack_page.ViewStackPage objects explicitly, and set the child widget as a property on it:

<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

adw.view_stack.ViewStack has a single CSS node named stack.

Accessibility

adw.view_stack.ViewStack uses the gtk.types.AccessibleRole.TabPanel for the stack pages which are the accessible parent objects of the child widgets.

An auxiliary class used by adw.view_stack.ViewStack.

An auxiliary class used by adw.view_stack.ViewStack.

See adw.view_stack.ViewStack.pages.

An adaptive view switcher.

An adaptive view switcher designed to switch between multiple views contained in a adw.view_stack.ViewStack in a similar fashion to gtk.stack_switcher.StackSwitcher.

adw.view_switcher.ViewSwitcher 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 adw.view_switcher.ViewSwitcher.policy property.

adw.view_switcher.ViewSwitcher is intended to be used in a header bar together with adw.view_switcher_bar.ViewSwitcherBar at the bottom of the window, and a adw.breakpoint.Breakpoint showing the view switcher bar on narrow sizes, while removing the view switcher from the header bar, as follows:

<object class="AdwWindow">
  <property name="width-request">360</property>
  <property name="height-request">200</property>
  <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 adw.view_switcher.ViewSwitcher.policy to adw.types.ViewSwitcherPolicy.Wide in this case.

You may have to adjust the breakpoint condition for your specific pages.

CSS nodes

adw.view_switcher.ViewSwitcher has a single CSS node with name viewswitcher. It can have the style classes .wide and .narrow, matching its policy.

Accessibility

adw.view_switcher.ViewSwitcher uses the gtk.types.AccessibleRole.TabList role and uses the gtk.types.AccessibleRole.Tab for its buttons.

A view switcher action bar.

An action bar letting you switch between multiple views contained in a adw.view_stack.ViewStack, via an adw.view_switcher.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.

adw.view_switcher_bar.ViewSwitcherBar is intended to be used together with adw.view_switcher.ViewSwitcher in a header bar, and a adw.breakpoint.Breakpoint showing the view switcher bar on narrow sizes, while removing the view switcher from the header bar, as follows:

<object class="AdwWindow">
  <property name="width-request">360</property>
  <property name="height-request">200</property>
  <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 adw.view_switcher.ViewSwitcher.policy to adw.types.ViewSwitcherPolicy.Wide in this case.

You may have to adjust the breakpoint condition for your specific pages.

CSS nodes

adw.view_switcher_bar.ViewSwitcherBar has a single CSS node with name viewswitcherbar.

A view switcher title.

A widget letting you switch between multiple views contained by a adw.view_stack.ViewStack via an adw.view_switcher.ViewSwitcher.

It is designed to be used as the title widget of a adw.header_bar.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 adw.header_bar.HeaderBar.centeringPolicy set to adw.types.CenteringPolicy.Strict.

adw.view_switcher_title.ViewSwitcherTitle is intended to be used together with adw.view_switcher_bar.ViewSwitcherBar.

A common use case is to bind the adw.view_switcher_bar.ViewSwitcherBar.reveal property to adw.view_switcher_title.ViewSwitcherTitle.titleVisible to automatically reveal the view switcher bar when the title label is displayed in place of the view switcher, as follows:

<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

adw.view_switcher_title.ViewSwitcherTitle has a single CSS node with name viewswitchertitle.

A freeform window.

The adw.window.Window widget is a subclass of gtk.window.Window which has no titlebar area. Instead, adw.toolbar_view.ToolbarView can be used together with adw.header_bar.HeaderBar or gtk.header_bar.HeaderBar as follows:

<object class="AdwWindow">
  <property name="content">
    <object class="AdwToolbarView">
      <child type="top">
        <object class="AdwHeaderBar"/>
      </child>
      <property name="content">
        <!-- ... -->
      </property>
    </object>
  </property>
</object>

Using gtk.window.Window.titlebar or gtk.window.Window.child is not supported and will result in a crash. Use adw.window.Window.content instead.

Dialogs

adw.window.Window can contain adw.dialog.Dialog. Use adw.dialog.Dialog.present with the window or a widget within a window to show a dialog.

Breakpoints

adw.window.Window can be used with adw.breakpoint.Breakpoint the same way as adw.breakpoint_bin.BreakpointBin. Refer to that widget's documentation for details.

Example:

<object class="AdwWindow">
  <property name="width-request">360</property>
  <property name="height-request">200</property>
  <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>

Like adw.breakpoint_bin.BreakpointBin, if breakpoints are used, adw.window.Window doesn't have a minimum size, and gtk.widget.Widget.widthRequest and gtk.widget.Widget.heightRequest properties must be set manually.

A helper widget for setting a window's title and subtitle.

adw.window_title.WindowTitle shows a title and subtitle. It's intended to be used as the title child of gtk.header_bar.HeaderBar or adw.header_bar.HeaderBar.

CSS nodes

adw.window_title.WindowTitle has a single CSS node with name windowtitle.