Class

AdwNavigationView

Description [src]

final class Adw.NavigationView : Gtk.Widget {
  /* No available fields */
}

A page-based navigation container.

navigation-view

AdwNavigationView presents one child at a time, similar to GtkStack.

AdwNavigationView can only contain AdwNavigationPage children.

It maintains a navigation stack that can be controlled with adw_navigation_view_push() and adw_navigation_view_pop(). The whole navigation stack can also be replaced using adw_navigation_view_replace().

AdwNavigationView allows to manage pages statically or dynamically.

Static pages can be added using the adw_navigation_view_add() method. The AdwNavigationView will keep a reference to these pages, but they aren’t accessible to the user until adw_navigation_view_push() is called (except for the first page, which is pushed automatically). Use the adw_navigation_view_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_push() method without calling adw_navigation_view_add() first.

Tags

Static pages, as well as any pages in the navigation stack, can be accessed by their AdwNavigationPage:tag. For example, adw_navigation_view_push_by_tag() can be used to push a static page that’s not in the navigation stack without having to keep a reference to it manually.

Header Bar Integration

When used inside AdwNavigationView, AdwHeaderBar 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 AdwHeaderBar:show-back-button to FALSE to disable this behavior if it’s unwanted.

AdwHeaderBar will also display the title of the AdwNavigationPage it’s placed into, so most applications shouldn’t need to customize it at all.

Shortcuts and Gestures

AdwNavigationView supports the following shortcuts for going to the previous page:

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 AdwNavigationView:animate-transitions value.

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

  • Alt+
  • Forward mouse button
  • Swipe/scrolling towards the left

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

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

Actions

AdwNavigationView defines actions for controlling the navigation stack. actions for controlling the navigation stack:

  • navigation.push takes a string parameter specifying the tag of the page to push, and is equivalent to calling adw_navigation_view_push_by_tag().

  • navigation.pop doesn’t take any parameters and pops the current page from the navigation stack, equivalent to calling adw_navigation_view_pop().

AdwNavigationView as GtkBuildable

AdwNavigationView allows to add pages as children, equivalent to using the adw_navigation_view_add() method.

Example of an AdwNavigationView 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>

navigation-view-example

CSS nodes

AdwNavigationView has a single CSS node with the name navigation-view.

Accessibility

AdwNavigationView uses the GTK_ACCESSIBLE_ROLE_GROUP role.

Available since:1.4

Ancestors

  • GtkWidget
  • GInitiallyUnowned
  • GObject

Implements

  • AdwSwipeable
  • GtkAccessible
  • GtkBuildable
  • GtkConstraintTarget

Constructors

adw_navigation_view_new

Creates a new AdwNavigationView.

Available since: 1.4

Instance methods

adw_navigation_view_add

Permanently adds page to self.

Available since: 1.4

adw_navigation_view_find_page

Finds a page in self by its tag.

Available since: 1.4

adw_navigation_view_get_animate_transitions

Gets whether self animates page transitions.

Available since: 1.4

adw_navigation_view_get_navigation_stack

Returns a GListModel that contains the pages in navigation stack.

Available since: 1.4

adw_navigation_view_get_pop_on_escape

Gets whether pressing Escape pops the current page on self.

Available since: 1.4

adw_navigation_view_get_previous_page

Gets the previous page for page.

Available since: 1.4

adw_navigation_view_get_visible_page

Gets the currently visible page in self.

Available since: 1.4

adw_navigation_view_pop

Pops the visible page from the navigation stack.

Available since: 1.4

adw_navigation_view_pop_to_page

Pops pages from the navigation stack until page is visible.

Available since: 1.4

adw_navigation_view_pop_to_tag

Pops pages from the navigation stack until page with the tag tag is visible.

Available since: 1.4

adw_navigation_view_push

Pushes page onto the navigation stack.

Available since: 1.4

adw_navigation_view_push_by_tag

Pushes the page with the tag tag onto the navigation stack.

Available since: 1.4

adw_navigation_view_remove

Removes page from self.

Available since: 1.4

adw_navigation_view_replace

Replaces the current navigation stack with pages.

Available since: 1.4

adw_navigation_view_replace_with_tags

Replaces the current navigation stack with pages with the tags tags.

Available since: 1.4

adw_navigation_view_set_animate_transitions

Sets whether self should animate page transitions.

Available since: 1.4

adw_navigation_view_set_pop_on_escape

Sets whether pressing Escape pops the current page on self.

Available since: 1.4

Methods inherited from AdwSwipeable (5)
adw_swipeable_get_cancel_progress

Gets the progress self will snap back to after the gesture is canceled.

adw_swipeable_get_distance

Gets the swipe distance of self.

adw_swipeable_get_progress

Gets the current progress of self.

adw_swipeable_get_snap_points

Gets the snap points of self.

adw_swipeable_get_swipe_area

Gets the area self can start a swipe from for the given direction and gesture type.

Properties

Adw.NavigationView:animate-transitions

Whether to animate page transitions.

Available since: 1.4

Adw.NavigationView:navigation-stack

A list model that contains the pages in navigation stack.

Available since: 1.4

Adw.NavigationView:pop-on-escape

Whether pressing Escape pops the current page.

Available since: 1.4

Adw.NavigationView:visible-page

The currently visible page.

Available since: 1.4

Signals

Adw.NavigationView::get-next-page

Emitted when a push shortcut or a gesture is triggered.

Available since: 1.4

Adw.NavigationView::popped

Emitted after page has been popped from the navigation stack.

Available since: 1.4

Adw.NavigationView::pushed

Emitted after a page has been pushed to the navigation stack.

Available since: 1.4

Adw.NavigationView::replaced

Emitted after the navigation stack has been replaced.

Available since: 1.4

Class structure

struct AdwNavigationViewClass {
  GtkWidgetClass parent_class;
  
}
Class members
parent_class
GtkWidgetClass
  No description available.