Adw.NavigationView¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Widget (181), GObject.Object (37), Gtk.Accessible (15), Gtk.Buildable (1), Adw.Swipeable (5)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` ()
	`add` (page)
	`find_page` (tag)
	`get_animate_transitions` ()
	`get_navigation_stack` ()
	`get_pop_on_escape` ()
	`get_previous_page` (page)
	`get_visible_page` ()
	`pop` ()
	`pop_to_page` (page)
	`pop_to_tag` (tag)
	`push` (page)
	`push_by_tag` (tag)
	`remove` (page)
	`replace` (pages)
	`replace_with_tags` (tags)
	`set_animate_transitions` (animate_transitions)
	`set_pop_on_escape` (pop_on_escape)

Virtual Methods¶

Inherited:: Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9), Adw.Swipeable (5)

Properties¶

Inherited:: Gtk.Widget (34), Gtk.Accessible (1)

Name	Type	Flags
`animate-transitions`	`bool`	r/w/en
`navigation-stack`	`Gio.ListModel`	r
`pop-on-escape`	`bool`	r/w/en
`visible-page`	`Adw.NavigationPage`	r

Signals¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Name	Short Description
`get-next-page`	Emitted when a push shortcut or a gesture is triggered.
`popped`	Emitted after page has been popped from the navigation stack.
`pushed`	Emitted after a page has been pushed to the navigation stack.
`replaced`	Emitted after the navigation stack has been replaced.

Fields¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Class Details¶

class Adw.NavigationView(**kwargs)¶

Bases:: Gtk.Widget, Adw.Swipeable
Abstract:: No
Structure:: Adw.NavigationViewClass

A page-based navigation container.

AdwNavigationView presents one child at a time, similar to [class`Gtk`.Stack].

AdwNavigationView can only contain [class`NavigationPage`] children.

It maintains a navigation stack that can be controlled with [method`NavigationView`.push] and [method`NavigationView`.pop]. The whole navigation stack can also be replaced using [method`NavigationView`.replace].

AdwNavigationView allows to manage pages statically or dynamically.

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

Tags

Static pages, as well as any pages in the navigation stack, can be accessed by their [property`NavigationPage`:py:data::tag<Adw.NavigationView.props.tag>]. For example, [method`NavigationView`.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, [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`:py:data::show-back-button<Adw.NavigationView.props.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:

<kbd>Escape</kbd> (unless [property`NavigationView`:py:data::pop-on-escape<Adw.NavigationView.props.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`:py:data::animate-transitions<Adw.NavigationView.props.animate_transitions>] value.

Applications can also enable shortcuts for pushing another page onto the navigation stack via connecting to the [signal`NavigationView`:py:func:::get-next-page<Adw.NavigationView.signals.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`:py:data::can-pop<Adw.NavigationView.props.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 [method`NavigationView`.push_by_tag].
navigation.pop doesn’t take any parameters and pops the current page from the navigation stack, equivalent to calling [method`NavigationView`.pop].

Adw.NavigationView as Gtk.Buildable

AdwNavigationView allows to add pages as children, equivalent to using the [method`NavigationView`.add] method.

Example of an AdwNavigationView UI definition:

``xml <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.

New in version 1.4.

classmethod new()¶

Returns:: the new created AdwNavigationView
Return type:: Gtk.Widget

Creates a new AdwNavigationView.

New in version 1.4.

add(page)¶

Parameters:: page (Adw.NavigationPage) – the page to add

Permanently adds page to self.

Any page that has been added will stay in self 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 [method`NavigationView`.remove].

New in version 1.4.

find_page(tag)¶

Parameters:: tag (str) – a page tag
Returns:: the page with the given tag
Return type:: Adw.NavigationPage or None

Finds a page in self by its tag.

See [property`NavigationPage`:py:data::tag<Adw.NavigationView.props.tag>].

New in version 1.4.

get_animate_transitions()¶

Returns:: whether to animate page transitions
Return type:: bool

Gets whether self animates page transitions.

New in version 1.4.

get_navigation_stack()¶

Returns:: a list model for the navigation stack
Return type:: Gio.ListModel

Returns a [iface`Gio`.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.

New in version 1.4.

get_pop_on_escape()¶

Returns:: whether to pop the current page
Return type:: bool

Gets whether pressing Escape pops the current page on self.

New in version 1.4.

get_previous_page(page)¶

Parameters:: page (Adw.NavigationPage) – a page in self
Returns:: the previous page
Return type:: Adw.NavigationPage or None

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.

New in version 1.4.

get_visible_page()¶

Returns:: the currently visible page
Return type:: Adw.NavigationPage or None

Gets the currently visible page in self.

New in version 1.4.

pop()¶

Returns:: TRUE if a page has been popped
Return type:: bool

Pops the visible page from the navigation stack.

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

If [method`NavigationView`.add] hasn’t been called, the page is automatically removed.

[signal`NavigationView`:py:func:::popped<Adw.NavigationView.signals.popped>] will be emitted for the current visible page.

See [method`NavigationView`.pop_to_page] and [method`NavigationView`.pop_to_tag].

New in version 1.4.

pop_to_page(page)¶

Parameters:: page (Adw.NavigationPage) – the page to pop to
Returns:: TRUE if any pages have been popped
Return type:: bool

Pops pages from the navigation stack until page is visible.

page must be in the navigation stack.

If [method`NavigationView`.add] hasn’t been called for any of the popped pages, they are automatically removed.

[signal`NavigationView`:py:func:::popped<Adw.NavigationView.signals.popped>] will be be emitted for each of the popped pages.

See [method`NavigationView`.pop] and [method`NavigationView`.pop_to_tag].

New in version 1.4.

pop_to_tag(tag)¶

Parameters:: tag (str) – a page tag
Returns:: TRUE if any pages have been popped
Return type:: bool

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

The page must be in the navigation stack.

If [method`NavigationView`.add] hasn’t been called for any of the popped pages, they are automatically removed.

[signal`NavigationView`:py:func:::popped<Adw.NavigationView.signals.popped>] will be emitted for each of the popped pages.

See [method`NavigationView`.pop_to_page] and [property`NavigationPage`:py:data::tag<Adw.NavigationView.props.tag>].

New in version 1.4.

push(page)¶

Parameters:: page (Adw.NavigationPage) – the page to push

Pushes page onto the navigation stack.

If [method`NavigationView`.add] hasn’t been called, the page is automatically removed once it’s popped.

[signal`NavigationView`:py:func:::pushed<Adw.NavigationView.signals.pushed>] will be emitted for page.

See [method`NavigationView`.push_by_tag].

New in version 1.4.

push_by_tag(tag)¶

Parameters:: tag (str) – the page tag

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

If [method`NavigationView`.add] hasn’t been called, the page is automatically removed once it’s popped.

[signal`NavigationView`:py:func:::pushed<Adw.NavigationView.signals.pushed>] will be emitted for the page.

See [method`NavigationView`.push] and [property`NavigationPage`:py:data::tag<Adw.NavigationView.props.tag>].

New in version 1.4.

remove(page)¶

Parameters:: page (Adw.NavigationPage) – the page to remove

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 [method`NavigationView`.add].

New in version 1.4.

replace(pages)¶

Parameters:: pages ([Adw.NavigationPage]) – the new navigation stack

Replaces the current navigation stack with pages.

The last page becomes the visible page.

Replacing the navigation stack has no animation.

If [method`NavigationView`.add] hasn’t been called for any pages that are no longer in the navigation stack, they are automatically removed.

n_pages 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 [signal`NavigationView`:py:func:::replaced<Adw.NavigationView.signals.replaced>] signal will be emitted.

See [method`NavigationView`.replace_with_tags].

New in version 1.4.

replace_with_tags(tags)¶

Parameters:: tags ([str]) – tags of the pages in the navigation stack

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 [method`NavigationView`.add] hasn’t been called for any pages that are no longer in the navigation stack, they are automatically removed.

n_tags 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 [signal`NavigationView`:py:func:::replaced<Adw.NavigationView.signals.replaced>] signal will be emitted.

See [method`NavigationView`.replace] and [property`NavigationPage`:py:data::tag<Adw.NavigationView.props.tag>].

New in version 1.4.

set_animate_transitions(animate_transitions)¶

Parameters:: animate_transitions (bool) – whether to animate page transitions

Sets whether self should animate page transitions.

Gesture-based transitions are always animated.

New in version 1.4.

set_pop_on_escape(pop_on_escape)¶

Parameters:: pop_on_escape (bool) – whether to pop the current page when pressing Escape

Sets whether pressing Escape pops the current page on self.

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

New in version 1.4.

Signal Details¶

Adw.NavigationView.signals.get_next_page(navigation_view)¶

Signal Name:: get-next-page
Flags:: RUN_LAST
Parameters:: navigation_view (Adw.NavigationView) – The object which received the signal
Returns:: the page to push
Return type:: Adw.NavigationPage or None

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 [signal`NavigationView`:py:func:::pushed<Adw.NavigationView.signals.pushed>] handler.

New in version 1.4.

Adw.NavigationView.signals.popped(navigation_view, page)¶

Signal Name:

popped

Flags:

RUN_LAST

Parameters:

navigation_view (Adw.NavigationView) – The object which received the signal
page (Adw.NavigationPage) – the popped page

Emitted after page has been popped from the navigation stack.

See [method`NavigationView`.pop].

When using [method`NavigationView`.pop_to_page] or [method`NavigationView`.pop_to_tag], this signal is emitted for each of the popped pages.

New in version 1.4.

Adw.NavigationView.signals.pushed(navigation_view)¶

Signal Name:: pushed
Flags:: RUN_LAST
Parameters:: navigation_view (Adw.NavigationView) – The object which received the signal

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

See [method`NavigationView`.push].

New in version 1.4.

Adw.NavigationView.signals.replaced(navigation_view)¶

Signal Name:: replaced
Flags:: RUN_LAST
Parameters:: navigation_view (Adw.NavigationView) – The object which received the signal

Emitted after the navigation stack has been replaced.

See [method`NavigationView`.replace].

New in version 1.4.

Property Details¶

Adw.NavigationView.props.animate_transitions¶

Name:: animate-transitions
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether to animate page transitions.

Gesture-based transitions are always animated.

New in version 1.4.

Adw.NavigationView.props.navigation_stack¶

Name:: navigation-stack
Type:: Gio.ListModel
Default Value:: None
Flags:: READABLE

A list model 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.

New in version 1.4.

Adw.NavigationView.props.pop_on_escape¶

Name:: pop-on-escape
Type:: bool
Default Value:: True
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether pressing Escape pops the current page.

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

New in version 1.4.

Adw.NavigationView.props.visible_page¶

Name:: visible-page
Type:: Adw.NavigationPage
Default Value:: None
Flags:: READABLE

The currently visible page.

New in version 1.4.