: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` :Constructors: :: NavigationView(**properties) new() -> Gtk.Widget 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: ~typing.Sequence[~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: ~typing.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 :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 Whether to animate page transitions. Gesture-based transitions are always animated. .. versionadded:: 1.4 .. 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.visible_page :type: ~gi.repository.Adw.NavigationPage The currently visible page. .. versionadded:: 1.4 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