Class NavigationView

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.adw.NavigationView
All Implemented Interfaces:
Swipeable, Accessible, Buildable, ConstraintTarget, Proxy
@Generated("org.javagi.JavaGI") public final class NavigationView extends Widget implements Swipeable, Accessible, Buildable, ConstraintTarget

A page-based navigation container.

navigation-view

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

AdwNavigationView can only contain NavigationPage children.

It maintains a navigation stack that can be controlled with push(NavigationPage) and pop(). The whole navigation stack can also be replaced using replace(NavigationPage[]).

AdwNavigationView allows to manage pages statically or dynamically.

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

Tags

Static pages, as well as any pages in the navigation stack, can be accessed by their NavigationPage:tag. For example, pushByTag(String) 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, 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 HeaderBar:show-back-button to FALSE to disable this behavior in rare scenarios where it's unwanted.

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

Shortcuts and Gestures

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

  • Escape (unless NavigationView:pop-on-escape is set to FALSE)
  • Alt+←
  • 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 NavigationView:animate-transitions value.

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

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

Actions

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

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

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

AdwNavigationView as GtkBuildable

AdwNavigationView allows to add pages as children, equivalent to using the add(NavigationPage) 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.AccessibleRole.group role.

Since:
1.4

  • Constructor Details

    • NavigationView

      public NavigationView(MemorySegment address)
      Create a NavigationView instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • NavigationView

      public NavigationView()
      Create a new NavigationView.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the NavigationView class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected NavigationView asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class Widget
      Returns:
      the instance as if it were its parent type

    • add

      public void add(NavigationPage page)

      Permanently adds page to self.

      Any page that has been added will stay in this NavigationView even after being popped from the navigation stack.

      Adding a page while no page is visible will automatically push it to the navigation stack.

      See remove(NavigationPage).

      Parameters:
      page - the page to add
      Since:
      1.4

    • findPage

      public @Nullable NavigationPage findPage(String tag)

      Finds a page in this NavigationView by its tag.

      See NavigationPage:tag.

      Parameters:
      tag - a page tag
      Returns:
      the page with the given tag
      Since:
      1.4

    • getAnimateTransitions

      public boolean getAnimateTransitions()
      Gets whether this NavigationView animates page transitions.
      Returns:
      whether to animate page transitions
      Since:
      1.4

    • getHhomogeneous

      public boolean getHhomogeneous()
      Gets whether this NavigationView is horizontally homogeneous.
      Returns:
      whether this NavigationView is horizontally homogeneous
      Since:
      1.7

    • getNavigationStack

      public ListModel getNavigationStack()

      Returns a ListModel that contains the pages in navigation stack.

      The pages are sorted from root page to visible page.

      This can be used to keep an up-to-date view.

      Returns:
      a list model for the navigation stack
      Since:
      1.4

    • getPopOnEscape

      public boolean getPopOnEscape()
      Gets whether pressing Escape pops the current page on self.
      Returns:
      whether to pop the current page
      Since:
      1.4

    • getPreviousPage

      public @Nullable NavigationPage getPreviousPage(NavigationPage page)

      Gets the previous page for page.

      If page is in the navigation stack, returns the page popping page will reveal.

      If page is the root page or is not in the navigation stack, returns NULL.

      Parameters:
      page - a page in this NavigationView
      Returns:
      the previous page
      Since:
      1.4

    • getVhomogeneous

      public boolean getVhomogeneous()
      Gets whether this NavigationView is vertically homogeneous.
      Returns:
      whether this NavigationView is vertically homogeneous
      Since:
      1.7

    • getVisiblePage

      public @Nullable NavigationPage getVisiblePage()
      Gets the currently visible page in self.
      Returns:
      the currently visible page
      Since:
      1.4

    • getVisiblePageTag

      public @Nullable String getVisiblePageTag()
      Gets the tag of the currently visible page in self.
      Returns:
      the tag of the currently visible page
      Since:
      1.7

    • pop

      public boolean pop()

      Pops the visible page from the navigation stack.

      Does nothing if the navigation stack contains less than two pages.

      If add(NavigationPage) hasn't been called, the page is automatically removed.

      NavigationView::popped will be emitted for the current visible page.

      See popToPage(NavigationPage) and popToTag(String).

      Returns:
      TRUE if a page has been popped
      Since:
      1.4

    • popToPage

      public boolean popToPage(NavigationPage page)

      Pops pages from the navigation stack until page is visible.

      page must be in the navigation stack.

      If add(NavigationPage) hasn't been called for any of the popped pages, they are automatically removed.

      NavigationView::popped will be be emitted for each of the popped pages.

      See pop() and popToTag(String).

      Parameters:
      page - the page to pop to
      Returns:
      TRUE if any pages have been popped
      Since:
      1.4

    • popToTag

      public boolean popToTag(String tag)

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

      The page must be in the navigation stack.

      If add(NavigationPage) hasn't been called for any of the popped pages, they are automatically removed.

      NavigationView::popped will be emitted for each of the popped pages.

      See popToPage(NavigationPage) and NavigationPage:tag.

      Parameters:
      tag - a page tag
      Returns:
      TRUE if any pages have been popped
      Since:
      1.4

    • push

      public void push(NavigationPage page)

      Pushes page onto the navigation stack.

      If add(NavigationPage) hasn't been called, the page is automatically removed once it's popped.

      NavigationView::pushed will be emitted for page.

      See pushByTag(String).

      Parameters:
      page - the page to push
      Since:
      1.4

    • pushByTag

      public void pushByTag(String tag)

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

      If add(NavigationPage) hasn't been called, the page is automatically removed once it's popped.

      NavigationView::pushed will be emitted for the page.

      See push(NavigationPage) and NavigationPage:tag.

      Parameters:
      tag - the page tag
      Since:
      1.4

    • remove

      public void remove(NavigationPage page)

      Removes page from self.

      If page is currently in the navigation stack, it will be removed once it's popped. Otherwise, it's removed immediately.

      See add(NavigationPage).

      Parameters:
      page - the page to remove
      Since:
      1.4

    • replace

      public void replace(@Nullable NavigationPage @Nullable [] pages)

      Replaces the current navigation stack with pages.

      The last page becomes the visible page.

      Replacing the navigation stack has no animation.

      If add(NavigationPage) hasn't been called for any pages that are no longer in the navigation stack, they are automatically removed.

      nPages can be 0, in that case no page will be visible after calling this method. This can be useful for removing all pages from self.

      The NavigationView::replaced signal will be emitted.

      See replaceWithTags(String[]).

      Parameters:
      pages - the new navigation stack
      Since:
      1.4

    • replaceWithTags

      public void replaceWithTags(@Nullable String @Nullable [] tags)

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

      The last page becomes the visible page.

      Replacing the navigation stack has no animation.

      If add(NavigationPage) hasn't been called for any pages that are no longer in the navigation stack, they are automatically removed.

      nTags can be 0, in that case no page will be visible after calling this method. This can be useful for removing all pages from self.

      The NavigationView::replaced signal will be emitted.

      See replace(NavigationPage[]) and NavigationPage:tag.

      Parameters:
      tags - tags of the pages in the navigation stack
      Since:
      1.4

    • setAnimateTransitions

      public void setAnimateTransitions(boolean animateTransitions)

      Sets whether this NavigationView should animate page transitions.

      Gesture-based transitions are always animated.

      Parameters:
      animateTransitions - whether to animate page transitions
      Since:
      1.4

    • setHhomogeneous

      public void setHhomogeneous(boolean hhomogeneous)

      Sets this NavigationView to be horizontally homogeneous or not.

      If the view is horizontally homogeneous, it allocates the same width for all pages.

      If it's not, the view may change width when a different page becomes visible.

      Parameters:
      hhomogeneous - whether to make this NavigationView horizontally homogeneous
      Since:
      1.7

    • setPopOnEscape

      public void setPopOnEscape(boolean popOnEscape)

      Sets whether pressing Escape pops the current page on self.

      Applications using AdwNavigationView to implement a browser may want to disable it.

      Parameters:
      popOnEscape - whether to pop the current page when pressing Escape
      Since:
      1.4

    • setVhomogeneous

      public void setVhomogeneous(boolean vhomogeneous)

      Sets this NavigationView to be vertically homogeneous or not.

      If the view is vertically homogeneous, it allocates the same height for all pages.

      If it's not, the view may change height when a different page becomes visible.

      Parameters:
      vhomogeneous - whether to make this NavigationView vertically homogeneous
      Since:
      1.7

    • onGetNextPage

      public SignalConnection<NavigationView.GetNextPageCallback> onGetNextPage(NavigationView.GetNextPageCallback handler)

      Emitted when a push shortcut or a gesture is triggered.

      To support the push shortcuts and gestures, the application is expected to return the page to push in the handler.

      This signal can be emitted multiple times for the gestures, for example when the gesture is cancelled by the user. As such, the application must not make any irreversible changes in the handler, such as removing the page from a forward stack.

      Instead, it should be done in the NavigationView::pushed handler.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      1.4
      See Also:

    • emitGetNextPage

      public NavigationPage emitGetNextPage()
      Emits the "get-next-page" signal. See onGetNextPage(NavigationView.GetNextPageCallback).

    • onPopped

      public SignalConnection<NavigationView.PoppedCallback> onPopped(NavigationView.PoppedCallback handler)

      Emitted after page has been popped from the navigation stack.

      See pop().

      When using popToPage(NavigationPage) or popToTag(String), this signal is emitted for each of the popped pages.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      1.4
      See Also:

    • emitPopped

      public void emitPopped(@Nullable NavigationPage page)
      Emits the "popped" signal. See onPopped(NavigationView.PoppedCallback).

    • onPushed

      public SignalConnection<NavigationView.PushedCallback> onPushed(NavigationView.PushedCallback handler)

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

      See push(NavigationPage).

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      1.4
      See Also:

    • emitPushed

      public void emitPushed()
      Emits the "pushed" signal. See onPushed(NavigationView.PushedCallback).

    • onReplaced

      public SignalConnection<NavigationView.ReplacedCallback> onReplaced(NavigationView.ReplacedCallback handler)

      Emitted after the navigation stack has been replaced.

      See replace(NavigationPage[]).

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      1.4
      See Also:

    • emitReplaced

      public void emitReplaced()
      Emits the "replaced" signal. See onReplaced(NavigationView.ReplacedCallback).

    • builder

      public static NavigationView.Builder<? extends NavigationView.Builder> builder()
      A NavigationView.Builder object constructs a NavigationView with the specified properties. Use the various set...() methods to set properties, and finish construction with NavigationView.Builder.build().
      Returns:
      the builder object