: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 :obj:`~gi.repository.Gtk.AccessibleRole.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_hhomogeneous() -> bool Gets whether ``self`` is horizontally homogeneous. .. versionadded:: 1.7 .. 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_vhomogeneous() -> bool Gets whether ``self`` is vertically homogeneous. .. versionadded:: 1.7 .. method:: get_visible_page() -> ~gi.repository.Adw.NavigationPage | None Gets the currently visible page in ``self``\. .. versionadded:: 1.4 .. method:: get_visible_page_tag() -> str | None Gets the tag of the currently visible page in ``self``\. .. versionadded:: 1.7 .. 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_hhomogeneous(hhomogeneous: bool) -> None Sets ``self`` 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. .. versionadded:: 1.7 :param hhomogeneous: whether to make ``self`` horizontally homogeneous .. 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 .. method:: set_vhomogeneous(vhomogeneous: bool) -> None Sets ``self`` 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. .. versionadded:: 1.7 :param vhomogeneous: whether to make ``self`` vertically homogeneous Properties ---------- .. rst-class:: interim-class .. class:: NavigationView :no-index: .. attribute:: props.animate_transitions :type: bool Whether to animate page transitions. Gesture-based transitions are always animated. .. versionadded:: 1.4 .. attribute:: props.hhomogeneous :type: bool Whether the view is horizontally homogeneous. If the view is horizontally homogeneous, it allocates the same width for all pages. If it's not, the page may change width when a different page becomes visible. .. versionadded:: 1.7 .. attribute:: props.navigation_stack :type: ~gi.repository.Gio.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. .. versionadded:: 1.4 .. attribute:: props.pop_on_escape :type: bool Whether pressing Escape pops the current page. Applications using ``AdwNavigationView`` to implement a browser may want to disable it. .. versionadded:: 1.4 .. attribute:: props.vhomogeneous :type: bool Whether the view is vertically homogeneous. 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. .. versionadded:: 1.7 .. attribute:: props.visible_page :type: ~gi.repository.Adw.NavigationPage The currently visible page. .. versionadded:: 1.4 .. attribute:: props.visible_page_tag :type: str The tag of the currently visible page. .. versionadded:: 1.7 Signals ------- .. rst-class:: interim-class .. class:: NavigationView.signals :no-index: .. method:: get_next_page() -> ~gi.repository.Adw.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 :obj:`~gi.repository.Adw.NavigationView.signals.pushed` handler. .. versionadded:: 1.4 .. method:: popped(page: ~gi.repository.Adw.NavigationPage) -> None Emitted after ``page`` has been popped from the navigation stack. See :obj:`~gi.repository.NavigationView.pop`\. When using :obj:`~gi.repository.NavigationView.pop_to_page` or :obj:`~gi.repository.NavigationView.pop_to_tag`\, this signal is emitted for each of the popped pages. .. versionadded:: 1.4 :param page: the popped page .. method:: pushed() -> None Emitted after a page has been pushed to the navigation stack. See :obj:`~gi.repository.NavigationView.push`\. .. versionadded:: 1.4 .. method:: replaced() -> None Emitted after the navigation stack has been replaced. See :obj:`~gi.repository.NavigationView.replace`\. .. versionadded:: 1.4