Adw.NavigationSplitView

g Adw.NavigationSplitView Adw.NavigationSplitView GObject.GInterface GObject.GInterface Gtk.Accessible Gtk.Accessible GObject.GInterface->Gtk.Accessible Gtk.Buildable Gtk.Buildable GObject.GInterface->Gtk.Buildable Gtk.ConstraintTarget Gtk.ConstraintTarget GObject.GInterface->Gtk.ConstraintTarget GObject.InitiallyUnowned GObject.InitiallyUnowned Gtk.Widget Gtk.Widget GObject.InitiallyUnowned->Gtk.Widget GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned Gtk.Accessible->Gtk.Widget Gtk.Buildable->Gtk.Widget Gtk.ConstraintTarget->Gtk.Widget Gtk.Widget->Adw.NavigationSplitView

Subclasses:

None

Methods

Inherited:

Gtk.Widget (181), GObject.Object (37), Gtk.Accessible (15), Gtk.Buildable (1)

Structs:

Gtk.WidgetClass (18), GObject.ObjectClass (5)

class

new ()

get_collapsed ()

get_content ()

get_max_sidebar_width ()

get_min_sidebar_width ()

get_show_content ()

get_sidebar ()

get_sidebar_width_fraction ()

get_sidebar_width_unit ()

set_collapsed (collapsed)

set_content (content)

set_max_sidebar_width (width)

set_min_sidebar_width (width)

set_show_content (show_content)

set_sidebar (sidebar)

set_sidebar_width_fraction (fraction)

set_sidebar_width_unit (unit)

Virtual Methods

Inherited:

Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9)

Properties

Inherited:

Gtk.Widget (34), Gtk.Accessible (1)

Name

Type

Flags

Short Description

collapsed

bool

r/w/en

content

Adw.NavigationPage

r/w/en

max-sidebar-width

float

r/w/en

min-sidebar-width

float

r/w/en

show-content

bool

r/w/en

sidebar

Adw.NavigationPage

r/w/en

sidebar-width-fraction

float

r/w/en

sidebar-width-unit

Adw.LengthUnit

r/w/en

Signals

Inherited:

Gtk.Widget (13), GObject.Object (1)

Fields

Inherited:

Gtk.Widget (13), GObject.Object (1)

Class Details

class Adw.NavigationSplitView(**kwargs)
Bases:

Gtk.Widget

Abstract:

No

Structure:

Adw.NavigationSplitViewClass

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

<picture> <source srcset=”navigation-split-view-dark.png” media=”(prefers-color-scheme: dark)”> <img src=”navigation-split-view.png” alt=”navigation-split-view”> </picture> <picture> <source srcset=”navigation-split-view-collapsed-dark.png” media=”(prefers-color-scheme: dark)”> <img src=”navigation-split-view-collapsed.png” alt=”navigation-split-view-collapsed”> </picture>

AdwNavigationSplitView has two [class`NavigationPage`] children: sidebar and content, and displays them side by side.

When [property`NavigationSplitView`:py:data::collapsed<Adw.NavigationSplitView.props.collapsed>] is set to TRUE, it instead puts both children inside an [class`NavigationView`]. The [property`NavigationSplitView`:py:data::show-content<Adw.NavigationSplitView.props.show_content>] controls which child is visible while collapsed.

See also [class`OverlaySplitView`].

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

``xml <object class=”AdwWindow”>

<property name=”width-request”>280</property> <property name=”height-request”>200</property> <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 [property`NavigationSplitView`:py:data::sidebar-width-fraction<Adw.NavigationSplitView.props.sidebar_width_fraction>] property.

The sidebar also has minimum and maximum sizes, controlled with the [property`NavigationSplitView`:py:data::min-sidebar-width<Adw.NavigationSplitView.props.min_sidebar_width>] and [property`NavigationSplitView`:py:data::max-sidebar-width<Adw.NavigationSplitView.props.max_sidebar_width>] properties.

The minimum and maximum sizes are using the length unit specified with the [property`NavigationSplitView`:py:data::sidebar-width-unit<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, [class`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 [class`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 [property`NavigationSplitView`:py:data::show-content<Adw.NavigationSplitView.props.show_content>] to TRUE.

  • navigation.pop doesn’t take any parameters and sets [property`NavigationSplitView`:py:data::show-content<Adw.NavigationSplitView.props.show_content>] to FALSE.

Adw.NavigationSplitView as Gtk.Buildable

The AdwNavigationSplitView implementation of the [iface`Gtk`.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 GTK_ACCESSIBLE_ROLE_GROUP role.

New in version 1.4.

classmethod new()
Returns:

the newly created AdwNavigationSplitView

Return type:

Gtk.Widget

Creates a new AdwNavigationSplitView.

New in version 1.4.

get_collapsed()
Returns:

whether self is collapsed

Return type:

bool

Gets whether self is collapsed.

New in version 1.4.

get_content()
Returns:

the content widget

Return type:

Adw.NavigationPage or None

Sets the content widget for self.

New in version 1.4.

get_max_sidebar_width()
Returns:

the maximum width

Return type:

float

Gets the maximum sidebar width for self.

New in version 1.4.

get_min_sidebar_width()
Returns:

the minimum width

Return type:

float

Gets the minimum sidebar width for self.

New in version 1.4.

get_show_content()
Returns:

whether to show content when collapsed

Return type:

bool

Gets which page is visible when self is collapsed.

New in version 1.4.

get_sidebar()
Returns:

the sidebar widget

Return type:

Adw.NavigationPage or None

Gets the sidebar widget for self.

New in version 1.4.

get_sidebar_width_fraction()
Returns:

the preferred width fraction

Return type:

float

Gets the preferred sidebar width fraction for self.

New in version 1.4.

get_sidebar_width_unit()
Returns:

the length unit

Return type:

Adw.LengthUnit

Gets the length unit for minimum and maximum sidebar widths.

New in version 1.4.

set_collapsed(collapsed)
Parameters:

collapsed (bool) – whether self is collapsed

Sets whether self is collapsed.

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

The [property`NavigationSplitView`:py:data::show-content<Adw.NavigationSplitView.props.show_content>] controls which child is visible while collapsed.

New in version 1.4.

set_content(content)
Parameters:

content (Adw.NavigationPage or None) – the content widget

Sets the content widget for self.

New in version 1.4.

set_max_sidebar_width(width)
Parameters:

width (float) – the maximum width

Sets the maximum sidebar width for self.

Maximum width is affected by [property`NavigationSplitView`:py:data::sidebar-width-unit<Adw.NavigationSplitView.props.sidebar_width_unit>].

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

New in version 1.4.

set_min_sidebar_width(width)
Parameters:

width (float) – the minimum width

Sets the minimum sidebar width for self.

Minimum width is affected by [property`NavigationSplitView`:py:data::sidebar-width-unit<Adw.NavigationSplitView.props.sidebar_width_unit>].

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

New in version 1.4.

set_show_content(show_content)
Parameters:

show_content (bool) – whether to show content when collapsed

Sets which page is visible when self is collapsed.

If set to TRUE, the content widget will be the visible page when [property`NavigationSplitView`:py:data::collapsed<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.

New in version 1.4.

set_sidebar(sidebar)
Parameters:

sidebar (Adw.NavigationPage or None) – the sidebar widget

Sets the sidebar widget for self.

New in version 1.4.

set_sidebar_width_fraction(fraction)
Parameters:

fraction (float) – the preferred width fraction

Sets the preferred sidebar width as a fraction of the total width of self.

The preferred width is additionally limited by [property`NavigationSplitView`:py:data::min-sidebar-width<Adw.NavigationSplitView.props.min_sidebar_width>] and [property`NavigationSplitView`:py:data::max-sidebar-width<Adw.NavigationSplitView.props.max_sidebar_width>].

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

New in version 1.4.

set_sidebar_width_unit(unit)
Parameters:

unit (Adw.LengthUnit) – the length unit

Sets the length unit for minimum and maximum sidebar widths.

See [property`NavigationSplitView`:py:data::min-sidebar-width<Adw.NavigationSplitView.props.min_sidebar_width>] and [property`NavigationSplitView`:py:data::max-sidebar-width<Adw.NavigationSplitView.props.max_sidebar_width>].

New in version 1.4.

Property Details

Adw.NavigationSplitView.props.collapsed
Name:

collapsed

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the split view is collapsed.

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

The [property`NavigationSplitView`:py:data::show-content<Adw.NavigationSplitView.props.show_content>] controls which child is visible while collapsed.

New in version 1.4.

Adw.NavigationSplitView.props.content
Name:

content

Type:

Adw.NavigationPage

Default Value:

None

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The content widget.

New in version 1.4.

Adw.NavigationSplitView.props.max_sidebar_width
Name:

max-sidebar-width

Type:

float

Default Value:

280.0

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The maximum sidebar width.

Maximum width is affected by [property`NavigationSplitView`:py:data::sidebar-width-unit<Adw.NavigationSplitView.props.sidebar_width_unit>].

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

New in version 1.4.

Adw.NavigationSplitView.props.min_sidebar_width
Name:

min-sidebar-width

Type:

float

Default Value:

180.0

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The minimum sidebar width.

Minimum width is affected by [property`NavigationSplitView`:py:data::sidebar-width-unit<Adw.NavigationSplitView.props.sidebar_width_unit>].

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

New in version 1.4.

Adw.NavigationSplitView.props.show_content
Name:

show-content

Type:

bool

Default Value:

False

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

Determines the visible page when collapsed.

If set to TRUE, the content widget will be the visible page when [property`NavigationSplitView`:py:data::collapsed<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.

New in version 1.4.

Adw.NavigationSplitView.props.sidebar
Name:

sidebar

Type:

Adw.NavigationPage

Default Value:

None

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The sidebar widget.

New in version 1.4.

Adw.NavigationSplitView.props.sidebar_width_fraction
Name:

sidebar-width-fraction

Type:

float

Default Value:

0.25

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

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

The preferred width is additionally limited by [property`NavigationSplitView`:py:data::min-sidebar-width<Adw.NavigationSplitView.props.min_sidebar_width>] and [property`NavigationSplitView`:py:data::max-sidebar-width<Adw.NavigationSplitView.props.max_sidebar_width>].

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

New in version 1.4.

Adw.NavigationSplitView.props.sidebar_width_unit
Name:

sidebar-width-unit

Type:

Adw.LengthUnit

Default Value:

Adw.LengthUnit.SP

Flags:

READABLE, WRITABLE, EXPLICIT_NOTIFY

The length unit for minimum and maximum sidebar widths.

See [property`NavigationSplitView`:py:data::min-sidebar-width<Adw.NavigationSplitView.props.min_sidebar_width>] and [property`NavigationSplitView`:py:data::max-sidebar-width<Adw.NavigationSplitView.props.max_sidebar_width>].

New in version 1.4.