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 class@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 property@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], class@HeaderBar will automatically display a back button that can be used to go back to the previous page when possible. The button also has a context menu, allowing to pop multiple pages at once, potentially across multiple navigation views.

Set property@HeaderBar:show-back-button to FALSE to disable this behavior in rare scenarios where it's unwanted.

[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 property@NavigationView:pop-on-escape is set to

FALSE)

• <kbd>Alt</kbd>+<kbd>←</kbd>
• Back mouse button

Additionally, it supports interactive gestures:

• One-finger swipe towards the right on touchscreens
• Scrolling towards the right on touchpads (usually two-finger swipe)

These gestures have transitions enabled regardless of the property@NavigationView:animate-transitions value.

Applications can also enable shortcuts for pushing another page onto the navigation stack via connecting to the signal@NavigationView::get-next-page signal, in that case the following shortcuts are supported:

• <kbd>Alt</kbd>+<kbd>→</kbd>
• Forward mouse button
• Swipe/scrolling towards the left

For right-to-left locales, the gestures and shortcuts are reversed.

property@NavigationPage:can-pop can be used to disable them, along with the header bar back buttons.

Actions

[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 for [adw.navigation_view.NavigationView]