NavigationView

Added in version 1.4.

class NavigationView(**properties: Any)

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Swipeable, Accessible, Buildable, ConstraintTarget

Constructors:

NavigationView(**properties)
new() -> Gtk.Widget

Constructors

class NavigationView

classmethod new() → Widget

Creates a new AdwNavigationView.

Added in version 1.4.

Methods

class NavigationView

add(page: NavigationPage) → None

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 remove.

Added in version 1.4.

Parameters:

page – the page to add

find_page(tag: str) → NavigationPage | None

Finds a page in self by its tag.

See tag.

Added in version 1.4.

Parameters:

tag – a page tag

get_animate_transitions() → bool

Gets whether self animates page transitions.

Added in version 1.4.

get_navigation_stack() → ListModel

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.

Added in version 1.4.

get_pop_on_escape() → bool

Gets whether pressing Escape pops the current page on self.

Added in version 1.4.

get_previous_page(page: NavigationPage) → NavigationPage | 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.

Added in version 1.4.

Parameters:

page – a page in self

get_visible_page() → NavigationPage | None

Gets the currently visible page in self.

Added in version 1.4.

pop() → bool

Pops the visible page from the navigation stack.

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

If add hasn’t been called, the page is automatically removed.

popped will be emitted for the current visible page.

See pop_to_page and pop_to_tag.

Added in version 1.4.

pop_to_page(page: NavigationPage) → bool

Pops pages from the navigation stack until page is visible.

page must be in the navigation stack.

If add hasn’t been called for any of the popped pages, they are automatically removed.

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

See pop and pop_to_tag.

Added in version 1.4.

Parameters:

page – the page to pop to

pop_to_tag(tag: str) → bool

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

The page must be in the navigation stack.

If add hasn’t been called for any of the popped pages, they are automatically removed.

popped will be emitted for each of the popped pages.

See pop_to_page and tag.

Added in version 1.4.

Parameters:

tag – a page tag

push(page: NavigationPage) → None

Pushes page onto the navigation stack.

If add hasn’t been called, the page is automatically removed once it’s popped.

pushed will be emitted for page.

See push_by_tag.

Added in version 1.4.

Parameters:

page – the page to push

push_by_tag(tag: str) → None

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

If add hasn’t been called, the page is automatically removed once it’s popped.

pushed will be emitted for the page.

See push and tag.

Added in version 1.4.

Parameters:

tag – the page tag

remove(page: NavigationPage) → None

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.

Added in version 1.4.

Parameters:

page – the page to remove

replace(pages: Sequence[NavigationPage]) → None

Replaces the current navigation stack with pages.

The last page becomes the visible page.

Replacing the navigation stack has no animation.

If 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 replaced signal will be emitted.

See replace_with_tags.

Added in version 1.4.

Parameters:

pages – the new navigation stack

replace_with_tags(tags: Sequence[str]) → None

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 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 replaced signal will be emitted.

See replace and tag.

Added in version 1.4.

Parameters:

tags – tags of the pages in the navigation stack

set_animate_transitions(animate_transitions: bool) → None

Sets whether self should animate page transitions.

Gesture-based transitions are always animated.

Added in version 1.4.

Parameters:

animate_transitions – whether to animate page transitions

set_pop_on_escape(pop_on_escape: bool) → None

Sets whether pressing Escape pops the current page on self.

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

Added in version 1.4.

Parameters:

pop_on_escape – whether to pop the current page when pressing Escape

Properties

class NavigationView

props.animate_transitions: bool

Whether to animate page transitions.

Gesture-based transitions are always animated.

Added in version 1.4.

props.navigation_stack: ListModel

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.

Added in version 1.4.

props.pop_on_escape: bool

Whether pressing Escape pops the current page.

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

Added in version 1.4.

props.visible_page: NavigationPage

The currently visible page.

Added in version 1.4.

Signals

class NavigationView.signals

get_next_page() → NavigationPage | 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 pushed handler.

Added in version 1.4.

popped(page: NavigationPage) → None

Emitted after page has been popped from the navigation stack.

See pop.

When using pop_to_page or pop_to_tag, this signal is emitted for each of the popped pages.

Added in version 1.4.

Parameters:

page – the popped page

pushed() → None

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

See push.

Added in version 1.4.

replaced() → None

Emitted after the navigation stack has been replaced.

See replace.

Added in version 1.4.