NavigationSplitView

Added in version 1.4.

class NavigationSplitView(**properties: Any)

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, ConstraintTarget

A widget presenting sidebar and content side by side or as a navigation view.

AdwNavigationSplitView has two NavigationPage children: sidebar and content, and displays them side by side.

When collapsed is set to TRUE, it instead puts both children inside an NavigationView. The show_content controls which child is visible while collapsed.

See also OverlaySplitView.

AdwNavigationSplitView is typically used together with an Breakpoint setting the collapsed property to TRUE on small widths, as follows:

<object class="AdwWindow">
  <property name="default-width">800</property>
  <property name="default-height">800</property>
  <child>
    <object class="AdwBreakpoint">
      <condition>max-width: 400sp</condition>
      <setter object="split_view" property="collapsed">True</setter>
    </object>
  </child>
  <property name="content">
    <object class="AdwNavigationSplitView" id="split_view">
      <property name="sidebar">
        <object class="AdwNavigationPage">
          <property name="title" translatable="yes">Sidebar</property>
          <property name="child">
            <!-- ... -->
          </property>
        </object>
      </property>
      <property name="content">
        <object class="AdwNavigationPage">
          <property name="title" translatable="yes">Content</property>
          <property name="child">
            <!-- ... -->
          </property>
        </object>
      </property>
    </object>
  </property>
</object>

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 sidebar_width_fraction property.

The sidebar also has minimum and maximum sizes, controlled with the min_sidebar_width and max_sidebar_width properties.

The minimum and maximum sizes are using the length unit specified with the 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, 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 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 show_content to TRUE.

• navigation.pop doesn’t take any parameters and sets

show_content to FALSE.

---

The AdwNavigationSplitView implementation of the Buildable interface supports setting the sidebar widget by specifying “sidebar” as the “type” attribute of a <child> 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.

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.

navigation-split-view
├── widget.sidebar-pane
│   ╰── [sidebar child]
╰── widget.content-pane
    ╰── [content child]

Accessibility

AdwNavigationSplitView uses the group role.

Constructors

class NavigationSplitView

classmethod new() → Widget

Creates a new AdwNavigationSplitView.

Added in version 1.4.

Methods

class NavigationSplitView

get_collapsed() → bool

Gets whether self is collapsed.

Added in version 1.4.

get_content() → NavigationPage | None

Sets the content widget for self.

Added in version 1.4.

get_max_sidebar_width() → float

Gets the maximum sidebar width for self.

Added in version 1.4.

get_min_sidebar_width() → float

Gets the minimum sidebar width for self.

Added in version 1.4.

get_show_content() → bool

Gets which page is visible when self is collapsed.

Added in version 1.4.

get_sidebar() → NavigationPage | None

Gets the sidebar widget for self.

Added in version 1.4.

get_sidebar_position() → PackType

Gets the sidebar position for self.

Added in version 1.7.

get_sidebar_width_fraction() → float

Gets the preferred sidebar width fraction for self.

Added in version 1.4.

get_sidebar_width_unit() → LengthUnit

Gets the length unit for minimum and maximum sidebar widths.

Added in version 1.4.

set_collapsed(collapsed: bool) → None

Sets whether self is collapsed.

When collapsed, the children are put inside an NavigationView, otherwise they are displayed side by side.

The show_content controls which child is visible while collapsed.

Added in version 1.4.

Parameters:

collapsed – whether self is collapsed

set_content(content: NavigationPage | None = None) → None

Sets the content widget for self.

Added in version 1.4.

Parameters:

content – the content widget

set_max_sidebar_width(width: float) → None

Sets the maximum sidebar width for self.

Maximum width is affected by sidebar_width_unit.

The sidebar widget can still be allocated with larger width if its own minimum width exceeds it.

Added in version 1.4.

Parameters:

width – the maximum width

set_min_sidebar_width(width: float) → None

Sets the minimum sidebar width for self.

Minimum width is affected by sidebar_width_unit.

The sidebar widget can still be allocated with larger width if its own minimum width exceeds it.

Added in version 1.4.

Parameters:

width – the minimum width

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 collapsed is TRUE; otherwise the sidebar widget will be visible.

If the split view is already collapsed, the visible page changes immediately.

Added in version 1.4.

Parameters:

show_content – whether to show content when collapsed

set_sidebar(sidebar: NavigationPage | None = None) → None

Sets the sidebar widget for self.

Added in version 1.4.

Parameters:

sidebar – the sidebar widget

set_sidebar_position(position: PackType) → None

Sets the sidebar position for self.

If set to start, the sidebar is displayed before the content, and the sidebar will be the root page when collapsed.

If set to end, the sidebar is displayed after the content, and the content will be the root page.

Added in version 1.7.

Parameters:

position – the new position

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 min_sidebar_width and max_sidebar_width.

The sidebar widget can be allocated with larger width if its own minimum width exceeds the preferred width.

Added in version 1.4.

Parameters:

fraction – the preferred width fraction

set_sidebar_width_unit(unit: LengthUnit) → None

Sets the length unit for minimum and maximum sidebar widths.

See min_sidebar_width and max_sidebar_width.

Added in version 1.4.

Parameters:

unit – the length unit

Properties

class NavigationSplitView

props.collapsed: bool

Whether the split view is collapsed.

When collapsed, the children are put inside an NavigationView, otherwise they are displayed side by side.

The show_content controls which child is visible while collapsed.

Added in version 1.4.

props.content: NavigationPage

The content widget.

Added in version 1.4.

props.max_sidebar_width: float

The maximum sidebar width.

Maximum width is affected by sidebar_width_unit.

The sidebar widget can still be allocated with larger width if its own minimum width exceeds it.

Added in version 1.4.

props.min_sidebar_width: float

The minimum sidebar width.

Minimum width is affected by sidebar_width_unit.

The sidebar widget can still be allocated with larger width if its own minimum width exceeds it.

Added in version 1.4.

props.show_content: bool

Determines the visible page when collapsed.

If set to TRUE, the content widget will be the visible page when collapsed is TRUE; otherwise the sidebar widget will be visible.

If the split view is already collapsed, the visible page changes immediately.

Added in version 1.4.

props.sidebar: NavigationPage

The sidebar widget.

Added in version 1.4.

props.sidebar_position: PackType

The sidebar position.

If set to start, the sidebar is displayed before the content, and the sidebar will be the root page when collapsed.

If set to end, the sidebar is displayed after the content, and the content will be the root page.

Added in version 1.7.

props.sidebar_width_fraction: float

The preferred sidebar width as a fraction of the total width.

The preferred width is additionally limited by min_sidebar_width and max_sidebar_width.

The sidebar widget can be allocated with larger width if its own minimum width exceeds the preferred width.

Added in version 1.4.

props.sidebar_width_unit: LengthUnit

The length unit for minimum and maximum sidebar widths.

See min_sidebar_width and max_sidebar_width.

Added in version 1.4.