:right-sidebar: True
NavigationSplitView
===================================================================
.. currentmodule:: gi.repository.Adw
.. versionadded:: 1.4
.. class:: NavigationSplitView(**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.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`
A widget presenting sidebar and content side by side or as a navigation view.
.. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/navigation-split-view-collapsed.png
``AdwNavigationSplitView`` has two :obj:`~gi.repository.Adw.NavigationPage` children: sidebar and
content, and displays them side by side.
When :obj:`~gi.repository.Adw.NavigationSplitView.props.collapsed` is set to ``TRUE``\, it instead
puts both children inside an :obj:`~gi.repository.Adw.NavigationView`\. The
:obj:`~gi.repository.Adw.NavigationSplitView.props.show_content` controls which child is visible
while collapsed.
See also :obj:`~gi.repository.Adw.OverlaySplitView`\.
``AdwNavigationSplitView`` is typically used together with an :obj:`~gi.repository.Adw.Breakpoint`
setting the ``collapsed`` property to ``TRUE`` on small widths, as follows:
.. code-block:: xml
:dedent:
Sizing
--------------------------------------------------------------------------------
When not collapsed, ``AdwNavigationSplitView`` changes the sidebar width
depending on its own width.
If possible, it tries to allocate a fraction of the total width, controlled
with the :obj:`~gi.repository.Adw.NavigationSplitView.props.sidebar_width_fraction` property.
The sidebar also has minimum and maximum sizes, controlled with the
:obj:`~gi.repository.Adw.NavigationSplitView.props.min_sidebar_width` and
:obj:`~gi.repository.Adw.NavigationSplitView.props.max_sidebar_width` properties.
The minimum and maximum sizes are using the length unit specified with the
:obj:`~gi.repository.Adw.NavigationSplitView.props.sidebar_width_unit`\.
By default, sidebar is using 25% of the total width, with 180sp as the
minimum size and 280sp as the maximum size.
Header Bar Integration
--------------------------------------------------------------------------------
When used inside ``AdwNavigationSplitView``\, :obj:`~gi.repository.Adw.HeaderBar` will
automatically hide the window buttons in the middle.
When collapsed, it also displays a back button for the content widget, as
well as the page titles. See :obj:`~gi.repository.Adw.NavigationView` documentation for details.
Actions
--------------------------------------------------------------------------------
``AdwNavigationSplitView`` defines the same actions as ``AdwNavigationView``\, but
they can be used even when the split view is not collapsed:
- ``navigation.push`` takes a string parameter specifying the tag of the page
to push. If it matches the tag of the content widget, it sets
:obj:`~gi.repository.Adw.NavigationSplitView.props.show_content` to ``TRUE``\.
- ``navigation.pop`` doesn't take any parameters and sets
:obj:`~gi.repository.Adw.NavigationSplitView.props.show_content` to ``FALSE``\.
--------------------------------------------------------------------------------
The ``AdwNavigationSplitView`` implementation of the :obj:`~gi.repository.Gtk.Buildable`
interface supports setting the sidebar widget by specifying “sidebar” as the
“type” attribute of a ```` element, Specifying “content” child type or
omitting it results in setting the content widget.
CSS nodes
--------------------------------------------------------------------------------
``AdwNavigationSplitView`` has a single CSS node with the name
``navigation-split-view``\.
When collapsed, it contains a child node with the name ``navigation-view``
containing both children.
.. code-block::
:dedent:
navigation-split-view
╰── navigation-view
├── [sidebar child]
╰── [content child]
When not collapsed, it contains two nodes with the name ``widget``\, one with
the ``.sidebar-pane`` style class, the other one with ``.content-view`` style
class, containing the sidebar and content children respectively.
.. code-block::
:dedent:
navigation-split-view
├── widget.sidebar-pane
│ ╰── [sidebar child]
╰── widget.content-pane
╰── [content child]
Accessibility
--------------------------------------------------------------------------------
``AdwNavigationSplitView`` uses the ``GTK_ACCESSIBLE_ROLE_GROUP`` role.
Constructors
------------
.. rst-class:: interim-class
.. class:: NavigationSplitView
:no-index:
.. classmethod:: new() -> ~gi.repository.Gtk.Widget
Creates a new ``AdwNavigationSplitView``\.
.. versionadded:: 1.4
Methods
-------
.. rst-class:: interim-class
.. class:: NavigationSplitView
:no-index:
.. method:: get_collapsed() -> bool
Gets whether ``self`` is collapsed.
.. versionadded:: 1.4
.. method:: get_content() -> ~gi.repository.Adw.NavigationPage | None
Sets the content widget for ``self``\.
.. versionadded:: 1.4
.. method:: get_max_sidebar_width() -> float
Gets the maximum sidebar width for ``self``\.
.. versionadded:: 1.4
.. method:: get_min_sidebar_width() -> float
Gets the minimum sidebar width for ``self``\.
.. versionadded:: 1.4
.. method:: get_show_content() -> bool
Gets which page is visible when ``self`` is collapsed.
.. versionadded:: 1.4
.. method:: get_sidebar() -> ~gi.repository.Adw.NavigationPage | None
Gets the sidebar widget for ``self``\.
.. versionadded:: 1.4
.. method:: get_sidebar_width_fraction() -> float
Gets the preferred sidebar width fraction for ``self``\.
.. versionadded:: 1.4
.. method:: get_sidebar_width_unit() -> ~gi.repository.Adw.LengthUnit
Gets the length unit for minimum and maximum sidebar widths.
.. versionadded:: 1.4
.. method:: set_collapsed(collapsed: bool) -> None
Sets whether ``self`` is collapsed.
When collapsed, the children are put inside an :obj:`~gi.repository.Adw.NavigationView`\,
otherwise they are displayed side by side.
The :obj:`~gi.repository.Adw.NavigationSplitView.props.show_content` controls which child is
visible while collapsed.
.. versionadded:: 1.4
:param collapsed: whether ``self`` is collapsed
.. method:: set_content(content: ~gi.repository.Adw.NavigationPage | None = None) -> None
Sets the content widget for ``self``\.
.. versionadded:: 1.4
:param content: the content widget
.. method:: set_max_sidebar_width(width: float) -> None
Sets the maximum sidebar width for ``self``\.
Maximum width is affected by
:obj:`~gi.repository.Adw.NavigationSplitView.props.sidebar_width_unit`\.
The sidebar widget can still be allocated with larger width if its own
minimum width exceeds it.
.. versionadded:: 1.4
:param width: the maximum width
.. method:: set_min_sidebar_width(width: float) -> None
Sets the minimum sidebar width for ``self``\.
Minimum width is affected by
:obj:`~gi.repository.Adw.NavigationSplitView.props.sidebar_width_unit`\.
The sidebar widget can still be allocated with larger width if its own
minimum width exceeds it.
.. versionadded:: 1.4
:param width: the minimum width
.. method:: set_show_content(show_content: bool) -> None
Sets which page is visible when ``self`` is collapsed.
If set to ``TRUE``\, the content widget will be the visible page when
:obj:`~gi.repository.Adw.NavigationSplitView.props.collapsed` is ``TRUE``\; otherwise the sidebar
widget will be visible.
If the split view is already collapsed, the visible page changes immediately.
.. versionadded:: 1.4
:param show_content: whether to show content when collapsed
.. method:: set_sidebar(sidebar: ~gi.repository.Adw.NavigationPage | None = None) -> None
Sets the sidebar widget for ``self``\.
.. versionadded:: 1.4
:param sidebar: the sidebar widget
.. method:: set_sidebar_width_fraction(fraction: float) -> None
Sets the preferred sidebar width as a fraction of the total width of ``self``\.
The preferred width is additionally limited by
:obj:`~gi.repository.Adw.NavigationSplitView.props.min_sidebar_width` and
:obj:`~gi.repository.Adw.NavigationSplitView.props.max_sidebar_width`\.
The sidebar widget can be allocated with larger width if its own minimum
width exceeds the preferred width.
.. versionadded:: 1.4
:param fraction: the preferred width fraction
.. method:: set_sidebar_width_unit(unit: ~gi.repository.Adw.LengthUnit) -> None
Sets the length unit for minimum and maximum sidebar widths.
See :obj:`~gi.repository.Adw.NavigationSplitView.props.min_sidebar_width` and
:obj:`~gi.repository.Adw.NavigationSplitView.props.max_sidebar_width`\.
.. versionadded:: 1.4
:param unit: the length unit
Properties
----------
.. rst-class:: interim-class
.. class:: NavigationSplitView
:no-index:
.. attribute:: props.collapsed
:type: bool
The type of the None singleton.
.. versionadded:: 1.4
.. attribute:: props.content
:type: ~gi.repository.Adw.NavigationPage
The type of the None singleton.
.. versionadded:: 1.4
.. attribute:: props.max_sidebar_width
:type: float
The type of the None singleton.
.. versionadded:: 1.4
.. attribute:: props.min_sidebar_width
:type: float
The type of the None singleton.
.. versionadded:: 1.4
.. attribute:: props.show_content
:type: bool
The type of the None singleton.
.. versionadded:: 1.4
.. attribute:: props.sidebar
:type: ~gi.repository.Adw.NavigationPage
The type of the None singleton.
.. versionadded:: 1.4
.. attribute:: props.sidebar_width_fraction
:type: float
The type of the None singleton.
.. versionadded:: 1.4
.. attribute:: props.sidebar_width_unit
:type: ~gi.repository.Adw.LengthUnit
The type of the None singleton.
.. versionadded:: 1.4