Class
AdwNavigationView
Description [src]
final class Adw.NavigationView : Gtk.Widget {
/* No available fields */
}
A page-based navigation container.
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:
- Escape (unless
AdwNavigationView:pop-on-escape
is set toFALSE
) - 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
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 callingadw_navigation_view_push_by_tag()
. -
navigation.pop
doesn’t take any parameters and pops the current page from the navigation stack, equivalent to callingadw_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>
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 |
Implements
- AdwSwipeable
- GtkAccessible
- GtkBuildable
- GtkConstraintTarget
Instance methods
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_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_by_tag
Pushes the page with the tag tag
onto the navigation stack.
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: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
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