adw.navigation_view

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.

Fluent builder implementation template for adw.navigation_view.NavigationView

Fluent builder for adw.navigation_view.NavigationView