:right-sidebar: True NavigationView =================================================================== .. currentmodule:: gi.repository.Adw .. versionadded:: 1.4 .. class:: NavigationView(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Adw.Swipeable`, :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget` A page-based navigation container. .. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/navigation-view.png ``AdwNavigationView`` presents one child at a time, similar to :obj:`~gi.repository.Gtk.Stack`\. ``AdwNavigationView`` can only contain :obj:`~gi.repository.Adw.NavigationPage` children. It maintains a navigation stack that can be controlled with :obj:`~gi.repository.NavigationView.push` and :obj:`~gi.repository.NavigationView.pop`\. The whole navigation stack can also be replaced using :obj:`~gi.repository.NavigationView.replace`\. ``AdwNavigationView`` allows to manage pages statically or dynamically. Static pages can be added using the :obj:`~gi.repository.NavigationView.add` method. The ``AdwNavigationView`` will keep a reference to these pages, but they aren't accessible to the user until :obj:`~gi.repository.NavigationView.push` is called (except for the first page, which is pushed automatically). Use the :obj:`~gi.repository.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 :obj:`~gi.repository.NavigationView.push` method without calling :obj:`~gi.repository.NavigationView.add` first. Tags -------------------------------------------------------------------------------- Static pages, as well as any pages in the navigation stack, can be accessed by their :obj:`~gi.repository.Adw.NavigationPage.props.tag`\. For example, :obj:`~gi.repository.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``\, :obj:`~gi.repository.Adw.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 :obj:`~gi.repository.Adw.HeaderBar.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` (unless :obj:`~gi.repository.Adw.NavigationView.props.pop_on_escape` is set to ``FALSE``\) - :kbd:`Alt`\+: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 :obj:`~gi.repository.Adw.NavigationView.props.animate_transitions` value. Applications can also enable shortcuts for pushing another page onto the navigation stack via connecting to the :obj:`~gi.repository.Adw.NavigationView.signals.get_next_page` signal, in that case the following shortcuts are supported: - :kbd:`Alt`\+:kbd:`→` - Forward mouse button - Swipe/scrolling towards the left For right-to-left locales, the gestures and shortcuts are reversed. :obj:`~gi.repository.Adw.NavigationPage.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 :obj:`~gi.repository.NavigationView.push_by_tag`\. - ``navigation.pop`` doesn't take any parameters and pops the current page from the navigation stack, equivalent to calling :obj:`~gi.repository.NavigationView.pop`\. -------------------------------------------------------------------------------- ``AdwNavigationView`` allows to add pages as children, equivalent to using the :obj:`~gi.repository.NavigationView.add` method. Example of an ``AdwNavigationView`` UI definition: .. code-block:: xml :dedent: Page 1 Open Page 2 center center navigation.push 'page-2' Page 2 page-2 .. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/navigation-view-example.png CSS nodes -------------------------------------------------------------------------------- ``AdwNavigationView`` has a single CSS node with the name ``navigation-view``\. Accessibility -------------------------------------------------------------------------------- ``AdwNavigationView`` uses the ``GTK_ACCESSIBLE_ROLE_GROUP`` role. Constructors ------------ .. rst-class:: interim-class .. class:: NavigationView :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Widget Creates a new ``AdwNavigationView``\. .. versionadded:: 1.4 Methods ------- .. rst-class:: interim-class .. class:: NavigationView :no-index: .. method:: add(page: ~gi.repository.Adw.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 :obj:`~gi.repository.NavigationView.remove`\. .. versionadded:: 1.4 :param page: the page to add .. method:: find_page(tag: str) -> ~gi.repository.Adw.NavigationPage | None Finds a page in ``self`` by its tag. See :obj:`~gi.repository.Adw.NavigationPage.props.tag`\. .. versionadded:: 1.4 :param tag: a page tag .. method:: get_animate_transitions() -> bool Gets whether ``self`` animates page transitions. .. versionadded:: 1.4 .. method:: get_navigation_stack() -> ~gi.repository.Gio.ListModel Returns a :obj:`~gi.repository.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. .. versionadded:: 1.4 .. method:: get_pop_on_escape() -> bool Gets whether pressing Escape pops the current page on ``self``\. .. versionadded:: 1.4 .. method:: get_previous_page(page: ~gi.repository.Adw.NavigationPage) -> ~gi.repository.Adw.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``\. .. versionadded:: 1.4 :param page: a page in ``self`` .. method:: get_visible_page() -> ~gi.repository.Adw.NavigationPage | None Gets the currently visible page in ``self``\. .. versionadded:: 1.4 .. method:: pop() -> bool Pops the visible page from the navigation stack. Does nothing if the navigation stack contains less than two pages. If :obj:`~gi.repository.NavigationView.add` hasn't been called, the page is automatically removed. :obj:`~gi.repository.Adw.NavigationView.signals.popped` will be emitted for the current visible page. See :obj:`~gi.repository.NavigationView.pop_to_page` and :obj:`~gi.repository.NavigationView.pop_to_tag`\. .. versionadded:: 1.4 .. method:: pop_to_page(page: ~gi.repository.Adw.NavigationPage) -> bool Pops pages from the navigation stack until ``page`` is visible. ``page`` must be in the navigation stack. If :obj:`~gi.repository.NavigationView.add` hasn't been called for any of the popped pages, they are automatically removed. :obj:`~gi.repository.Adw.NavigationView.signals.popped` will be be emitted for each of the popped pages. See :obj:`~gi.repository.NavigationView.pop` and :obj:`~gi.repository.NavigationView.pop_to_tag`\. .. versionadded:: 1.4 :param page: the page to pop to .. method:: 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 :obj:`~gi.repository.NavigationView.add` hasn't been called for any of the popped pages, they are automatically removed. :obj:`~gi.repository.Adw.NavigationView.signals.popped` will be emitted for each of the popped pages. See :obj:`~gi.repository.NavigationView.pop_to_page` and :obj:`~gi.repository.Adw.NavigationPage.props.tag`\. .. versionadded:: 1.4 :param tag: a page tag .. method:: push(page: ~gi.repository.Adw.NavigationPage) -> None Pushes ``page`` onto the navigation stack. If :obj:`~gi.repository.NavigationView.add` hasn't been called, the page is automatically removed once it's popped. :obj:`~gi.repository.Adw.NavigationView.signals.pushed` will be emitted for ``page``\. See :obj:`~gi.repository.NavigationView.push_by_tag`\. .. versionadded:: 1.4 :param page: the page to push .. method:: push_by_tag(tag: str) -> None Pushes the page with the tag ``tag`` onto the navigation stack. If :obj:`~gi.repository.NavigationView.add` hasn't been called, the page is automatically removed once it's popped. :obj:`~gi.repository.Adw.NavigationView.signals.pushed` will be emitted for the page. See :obj:`~gi.repository.NavigationView.push` and :obj:`~gi.repository.Adw.NavigationPage.props.tag`\. .. versionadded:: 1.4 :param tag: the page tag .. method:: remove(page: ~gi.repository.Adw.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 :obj:`~gi.repository.NavigationView.add`\. .. versionadded:: 1.4 :param page: the page to remove .. method:: replace(pages: list[~gi.repository.Adw.NavigationPage]) -> None Replaces the current navigation stack with ``pages``\. The last page becomes the visible page. Replacing the navigation stack has no animation. If :obj:`~gi.repository.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 :obj:`~gi.repository.Adw.NavigationView.signals.replaced` signal will be emitted. See :obj:`~gi.repository.NavigationView.replace_with_tags`\. .. versionadded:: 1.4 :param pages: the new navigation stack .. method:: replace_with_tags(tags: list[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 :obj:`~gi.repository.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 :obj:`~gi.repository.Adw.NavigationView.signals.replaced` signal will be emitted. See :obj:`~gi.repository.NavigationView.replace` and :obj:`~gi.repository.Adw.NavigationPage.props.tag`\. .. versionadded:: 1.4 :param tags: tags of the pages in the navigation stack .. method:: set_animate_transitions(animate_transitions: bool) -> None Sets whether ``self`` should animate page transitions. Gesture-based transitions are always animated. .. versionadded:: 1.4 :param animate_transitions: whether to animate page transitions .. method:: 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. .. versionadded:: 1.4 :param pop_on_escape: whether to pop the current page when pressing Escape Properties ---------- .. rst-class:: interim-class .. class:: NavigationView :no-index: .. attribute:: props.animate_transitions :type: bool The type of the None singleton. .. versionadded:: 1.4 .. attribute:: props.navigation_stack :type: ~gi.repository.Gio.ListModel The type of the None singleton. .. versionadded:: 1.4 .. attribute:: props.pop_on_escape :type: bool The type of the None singleton. .. versionadded:: 1.4 .. attribute:: props.visible_page :type: ~gi.repository.Adw.NavigationPage The type of the None singleton. .. versionadded:: 1.4 Signals ------- .. rst-class:: interim-class .. class:: NavigationView.signals :no-index: .. method:: get_next_page() -> ~gi.repository.Adw.NavigationPage | None The type of the None singleton. .. versionadded:: 1.4 .. method:: popped(page: ~gi.repository.Adw.NavigationPage) -> None The type of the None singleton. .. versionadded:: 1.4 :param page: the popped page .. method:: pushed() -> None The type of the None singleton. .. versionadded:: 1.4 .. method:: replaced() -> None The type of the None singleton. .. versionadded:: 1.4