Adw.Sidebar¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Widget (183), GObject.Object (37), Gtk.Accessible (18), Gtk.Buildable (1)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` ()
	`append` (section)
	`get_drop_preload` ()
	`get_filter` ()
	`get_item` (index)
	`get_items` ()
	`get_menu_model` ()
	`get_mode` ()
	`get_placeholder` ()
	`get_section` (index)
	`get_sections` ()
	`get_selected` ()
	`get_selected_item` ()
	`insert` (section, position)
	`prepend` (section)
	`remove` (section)
	`remove_all` ()
	`set_drop_preload` (preload)
	`set_filter` (filter)
	`set_menu_model` (menu_model)
	`set_mode` (mode)
	`set_placeholder` (placeholder)
	`set_selected` (selected)
	`setup_drop_target` (actions, types)

Virtual Methods¶

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

Properties¶

Inherited:: Gtk.Widget (35), Gtk.Accessible (1)

Name	Type	Flags
`drop-preload`	`bool`	r/w/en
`filter`	`Gtk.Filter`	r/w/en
`items`	`Gtk.SelectionModel`	r
`menu-model`	`Gio.MenuModel`	r/w/en
`mode`	`Adw.SidebarMode`	r/w/en
`placeholder`	`Gtk.Widget`	r/w/en
`sections`	`Gio.ListModel`	r
`selected`	`int`	r/w/en
`selected-item`	`Adw.SidebarItem`	r

Signals¶

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

Name	Short Description
`activated`	Emitted when an item at index has been activated.
`drop`	Emitted when content is dropped onto the item at index.
`drop-enter`	Emitted when the pointer enters the item at index.
`drop-value-loaded`	Emitted when the dropped content is preloaded for the item at index.
`setup-menu`	Emitted when a context menu is opened or closed for item.

Fields¶

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

Class Details¶

class Adw.Sidebar(**kwargs)¶

Bases:: Gtk.Widget
Abstract:: No
Structure:: Adw.SidebarClass

Adaptive sidebar widget.

AdwSidebar contains [class`SidebarSection`] objects, which in turn contain [class`SidebarItem`] objects.

To add sections, use [method`Sidebar`.append], [method`Sidebar`.prepend] or [method`Sidebar`.insert].

To remove sections, use [method`Sidebar`.remove] or [method`Sidebar`.remove_all].

To inspect the items, use [method`Sidebar`.get_item] or [property`Sidebar`:py:data::items<Adw.Sidebar.props.items>].

To inspect sections themselves, use [method`Sidebar`.get_section] or [property`Sidebar`:py:data::sections<Adw.Sidebar.props.sections>].

Selection and activation

AdwSidebar has zero or one selected items. The index of the item can be accessed and changed via [property`Sidebar`:py:data::selected<Adw.Sidebar.props.selected>]. Set it to [const`Gtk`.INVALID_LIST_POSITION] to remove selection.

Selection cannot be permanently disabled.

[property`Sidebar`:py:data::selected-item<Adw.Sidebar.props.selected_item>] can be used to access the selected item.

Connect to the [signal`Sidebar`:py:func:::activated<Adw.Sidebar.signals.activated>] signal to run code when an item has been activated. This can be used to toggle the visible pane when used in a split view.

See also: [class`ViewSwitcherSidebar`].

Modes

AdwSidebar is adaptive and can act as either a regular sidebar, or a page of boxed lists.

Use the [property`Sidebar`:py:data::mode<Adw.Sidebar.props.mode>] to determine its look and behavior.

A typical use case involves using AdwSidebar inside the sidebar pane of a [class`NavigationSplitView`], and switching mode to page whenever it’s collapsed, as follows:

``xml <object class=”AdwWindow”>

<property name=”default-width”>800</property> <property name=”default-height”>600</property> <child>

<object class=”AdwBreakpoint”>
<condition>max-width: 400sp</condition> <setter object=”split_view” property=”collapsed”>True</setter> <setter object=”sidebar” property=”mode”>page</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”>

<object class=”AdwToolbarView”>

<child type=”top”>
<object class=”AdwHeaderBar”/>

</child> <property name=”content”>

<object class=”AdwSidebar” id=”sidebar”>
<!– Calls adw_navigation_split_view_set_show_content (split_view, TRUE); –> <signal name=”activated” handler=”sidebar_activated_cb”/> <!– … –>

</object>

</property>

</object>

</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> ``

When used with [class`OverlaySplitView`], the sidebar should stay in sidebar mode, as the sidebar pane is still a sidebar when collapsed.

Search

AdwSidebar supports filtering items via the [property`Sidebar`:py:data::filter<Adw.Sidebar.props.filter>] property.

Use [property`Sidebar`:py:data::placeholder<Adw.Sidebar.props.placeholder>] to provide an empty state widget. It will be shown when all items have been filtered out, or the sidebar has no items otherwise.

Context Menu

To create a context menu for the sidebar items, use the [property`Sidebar`:py:data::menu-model<Adw.Sidebar.props.menu_model>] property to provide a menu model, and the [signal`Sidebar`:py:func:::setup-menu<Adw.Sidebar.signals.setup_menu>] signal to set up actions for the given item.

To set or override the menu for just one section, use [property`SidebarSection`:py:data::menu-model<Adw.Sidebar.props.menu_model>] instead.

Drag-and-Drop

AdwSidebar items can have a drop target for arbitrary content.

Use [method`Sidebar`.setup_drop_target] to set it up, specifying the supported content types and drag actions, then connect to [signal`Sidebar`:py:func:::drop<Adw.Sidebar.signals.drop>] to handle drops.

In some cases, it may be necessary to determine the used action based on the dragged content, or the hovered item.

To determine it based on the sidebar item, connect to the [signal`Sidebar`:py:func:::drop-enter<Adw.Sidebar.signals.drop_enter>] signal and return the action from its handler.

To determine it based on the content, set [property`Sidebar`:py:data::drop-preload<Adw.Sidebar.props.drop_preload>] to TRUE, then connect to [signal`Sidebar`:py:func:::drop-value-loaded<Adw.Sidebar.signals.drop_value_loaded>] signal and return the action from its handler.

In both cases the action will be passed as a parameter to the [signal`Sidebar`:py:func:::drop<Adw.Sidebar.signals.drop>] signal.

Regardless of whether a drop target was set up, dragging content over sidebar items activates them after a timeout. To disable this behavior for specific items, set [property`SidebarItem`:py:data::drag-motion-activate<Adw.Sidebar.props.drag_motion_activate>] to FALSE on them.

Adw.Sidebar as Gtk.Buildable

AdwSidebar allows adding sections as children.

Example of an AdwSidebar UI definition:

``xml <object class=”AdwSidebar”>

<child>

<object class=”AdwSidebarSection”>

<child>

<object class=”AdwSidebarItem”>
<property name=”title” translatable=”yes”>Recent</property> <property name=”icon-name”>document-open-recent-symbolic</property>

</object>

</child> <child>

<object class=”AdwSidebarItem”>
<property name=”title” translatable=”yes”>Starred</property> <property name=”icon-name”>starred-symbolic</property>

</object>

</child>

</object>

</child> <child>

<object class=”AdwSidebarSection”>
<property name=”title” translatable=”yes”>Places</property> <child>

<object class=”AdwSidebarItem”>
<property name=”title” translatable=”yes”>Music</property> <property name=”icon-name”>folder-music-symbolic</property>

</object>

</child> <child>

<object class=”AdwSidebarItem”>
<property name=”title” translatable=”yes”>Pictures</property> <property name=”icon-name”>folder-pictures-symbolic</property>

</object>

</child> <child>

<object class=”AdwSidebarItem”>
<property name=”title” translatable=”yes”>Videos</property> <property name=”icon-name”>folder-videos-symbolic</property>

</object>

</child>

</object>

</child> <child>

<object class=”AdwSidebarSection”>

<child>

<object class=”AdwSidebarItem”>
<property name=”title” translatable=”yes”>Trash</property> <property name=”icon-name”>user-trash-symbolic</property>

</object>

</child>

</object>

</child>

</object> ``

CSS nodes

AdwSidebar has a main CSS node with the name sidebar.

Internally, it’s using a [class`Gtk`.ListBox] with the .navigation-sidebar style class in sidebar mode, or an [class`PreferencesPage`] in page mode.

Accessibility

AdwSidebar uses the [enum`Gtk`.AccessibleRole.generic] role.

New in version 1.9.

classmethod new()¶

Returns:: the newly created AdwSidebar
Return type:: Gtk.Widget

Creates a new AdwSidebar.

New in version 1.9.

append(section)¶

Parameters:: section (Adw.SidebarSection) – a section to append

Appends section to self.

New in version 1.9.

get_drop_preload()¶

Returns:: whether drop data should be preloaded on hover
Return type:: bool

Gets whether drop data should be preloaded on hover.

New in version 1.9.

get_filter()¶

Returns:: the item filter
Return type:: Gtk.Filter or None

Gets the item filter for self.

New in version 1.9.

get_item(index)¶

Parameters:: index (int) – index of the item
Returns:: the item at index
Return type:: Adw.SidebarItem or None

Gets the item at index within self.

The index starts from 0 at the top of the sidebar, and is same as the one returned by [method`SidebarItem`.get_index].

Can return NULL if index is larger or equal to the number of items.

New in version 1.9.

get_items()¶

Returns:: a model containing the items
Return type:: Gtk.SelectionModel

Gets a list model with self's items.

This can be used to keep an up-to-date view.

The model implements [iface`Gtk`.SectionModel] and creates sections corresponding to the sidebar’s sections.

The model also implements [iface`Gtk`.SelectionModel] and can be used to track and change the selection.

To only track sections, use [property`Sidebar`:py:data::sections<Adw.Sidebar.props.sections>] instead.

New in version 1.9.

get_menu_model()¶

Returns:: the context menu model
Return type:: Gio.MenuModel or None

Gets the context menu model for self's items.

New in version 1.9.

get_mode()¶

Returns:: the current mode
Return type:: Adw.SidebarMode

Gets self's look and behavior.

New in version 1.9.

get_placeholder()¶

Returns:: the placeholder widget
Return type:: Gtk.Widget or None

Gets the placeholder widget for self.

New in version 1.9.

get_section(index)¶

Parameters:: index (int) – index of the section
Returns:: the section at index
Return type:: Adw.SidebarSection or None

Gets the section at index within self.

Can return NULL if index is larger or equal to the number of sections.

New in version 1.9.

get_sections()¶

Returns:: a model containing the sections
Return type:: Gio.ListModel

Gets a list model with self's sections.

This can be used to keep an up-to-date view.

To track items, use [property`Sidebar`:py:data::items<Adw.Sidebar.props.items>] instead.

New in version 1.9.

get_selected()¶

Returns:: index of the currently selected item
Return type:: int

Gets the index of the currently selected item.

See also: [method`Sidebar`.get_selected_item].

New in version 1.9.

get_selected_item()¶

Returns:: the selected item
Return type:: Adw.SidebarItem or None

Gets the currently selected item.

This is a convenience method, equivalent to calling [method`Sidebar`.get_item] with [property`Sidebar`:py:data::selected<Adw.Sidebar.props.selected>] provided as the index.

To change selection, use [method`Sidebar`.set_selected].

New in version 1.9.

insert(section, position)¶

Parameters:

section (Adw.SidebarSection) – a section to insert
position (int) – position to insert section at

Inserts section at position to self.

If position is -1, or larger than the total number of sections in self, the section will be appended to the end.

New in version 1.9.

prepend(section)¶

Parameters:: section (Adw.SidebarSection) – a section to prepend

Prepends section to self.

New in version 1.9.

remove(section)¶

Parameters:: section (Adw.SidebarSection) – a section to remove

Removes section from self.

New in version 1.9.

remove_all()¶: Removes all sections from self.

New in version 1.9.

set_drop_preload(preload)¶

Parameters:: preload (bool) – whether to preload drop data

Sets whether drop data should be preloaded on hover.

See [property`Gtk`.DropTarget:preload].

New in version 1.9.

set_filter(filter)¶

Parameters:: filter (Gtk.Filter or None) – the item filter

Sets the item filter for self.

Can be used to implement search within the sidebar.

Use [property`Sidebar`:py:data::placeholder<Adw.Sidebar.props.placeholder>] to provide an empty state.

New in version 1.9.

set_menu_model(menu_model)¶

Parameters:: menu_model (Gio.MenuModel or None) – a menu model

Sets the context menu model for self's items.

When a context menu is shown for an item, it will be constructed from the provided menu model. Use the [signal`Sidebar`:py:func:::setup-menu<Adw.Sidebar.signals.setup_menu>] signal to set up the menu actions for the particular item.

[property`Sidebar`:py:data::menu-model<Adw.Sidebar.props.menu_model>] will be preferred over this model if set.

New in version 1.9.

set_mode(mode)¶

Parameters:: mode (Adw.SidebarMode) – the new mode

Sets self's look and behavior.

If set to [enum`Adw`.SidebarMode.sidebar], behaves like a sidebar: with a sidebar style and a persistent selection.

If set to [enum`Adw`.SidebarMode.page], behaves like a page of boxed lists. In this mode, the selection is invisible and only tracked to determine the initially selected item once switched back to sidebar mode.

The page mode is intended to be used with [class`NavigationSplitView`] when collapsed, as the sidebar pane becomes a page there.

When used with [class`OverlaySplitView`], the sidebar should stay in sidebar mode, as the sidebar pane is still a sidebar when collapsed.

New in version 1.9.

set_placeholder(placeholder)¶

Parameters:: placeholder (Gtk.Widget or None) – the placeholder widget

Sets the placeholder widget for self.

This widget will be shown if self has no items, or all of its items have been filtered out by [property`Sidebar`:py:data::filter<Adw.Sidebar.props.filter>].

New in version 1.9.

set_selected(selected)¶

Parameters:: selected (int) – index of the newly selected item

Selects the item at selected.

If set to [const`Gtk`.INVALID_LIST_POSITION], no item is selected.

If [property`Sidebar`:py:data::mode<Adw.Sidebar.props.mode>] is set to [enum`Adw`.SidebarMode.page], the selection is invisible, but still tracked, indicating which item will be selected once the mode is changed to [enum`Adw`.SidebarMode.sidebar].

See also: [property`Sidebar`:py:data::selected-item<Adw.Sidebar.props.selected_item>].

New in version 1.9.

setup_drop_target(actions, types)¶

Parameters:

actions (Gdk.DragAction) – the supported actions
types ([GObject.GType] or None) – all supported ``GType``s that can be dropped

Sets up a drop target on the items.

This allows to drag arbitrary content onto items.

The [signal`Sidebar`:py:func:::drop<Adw.Sidebar.signals.drop>] signal can be used to handle the drop.

New in version 1.9.

Signal Details¶

Adw.Sidebar.signals.activated(sidebar, index)¶

Signal Name:

activated

Flags:

RUN_LAST

Parameters:

sidebar (Adw.Sidebar) – The object which received the signal
index (int) – the item index

Emitted when an item at index has been activated.

New in version 1.9.

Adw.Sidebar.signals.drop(sidebar, index, value, preferred_action)¶

Signal Name:

drop

Flags:

RUN_LAST

Parameters:

sidebar (Adw.Sidebar) – The object which received the signal
index (int) – index of the item the content was dropped onto
value (GObject.Value) – the GValue being dropped
preferred_action (Gdk.DragAction) – the preferred drop action

Returns:

whether the drop was accepted

SinceL 1.9

Return type:

bool

Emitted when content is dropped onto the item at index.

The content must be of one of the types set up via [method`Sidebar`.setup_drop_target].

See [signal`Gtk`.DropTarget::drop].

Adw.Sidebar.signals.drop_enter(sidebar, index)¶

Signal Name:

drop-enter

Flags:

RUN_LAST

Parameters:

sidebar (Adw.Sidebar) – The object which received the signal
index (int) – index of the hovered item

Returns:

the preferred action for the drop

Return type:

Gdk.DragAction

Emitted when the pointer enters the item at index.

Applications can use this to set their default drop action even when [property`Sidebar`:py:data::drop-preload<Adw.Sidebar.props.drop_preload>] is set to FALSE.

See [signal`Gtk`.DropTarget::enter].

New in version 1.9.

Adw.Sidebar.signals.drop_value_loaded(sidebar, index, value)¶

Signal Name:

drop-value-loaded

Flags:

RUN_LAST

Parameters:

sidebar (Adw.Sidebar) – The object which received the signal
index (int) – index of the hovered item
value (GObject.Value) – the GValue being dropped

Returns:

the preferred action for the drop

Return type:

Gdk.DragAction

Emitted when the dropped content is preloaded for the item at index.

In order for data to be preloaded, [property`Sidebar`:py:data::drop-preload<Adw.Sidebar.props.drop_preload>] must be set to TRUE.

The content must be of one of the types set up via [method`Sidebar`.setup_drop_target].

See [property`Gtk`.DropTarget:value].

New in version 1.9.

Adw.Sidebar.signals.setup_menu(sidebar, item)¶

Signal Name:

setup-menu

Flags:

RUN_LAST

Parameters:

sidebar (Adw.Sidebar) – The object which received the signal
item (Adw.SidebarItem or None) – an item in self

Emitted when a context menu is opened or closed for item.

If the menu has been closed, item will be set to NULL.

It can be used to set up menu actions before showing the menu, for example disable actions not applicable to item.

Property Details¶

Adw.Sidebar.props.drop_preload¶

Name:: drop-preload
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Whether the drop data should be preloaded on hover.

See [property`Gtk`.DropTarget:preload].

New in version 1.9.

Adw.Sidebar.props.filter¶

Name:: filter
Type:: Gtk.Filter
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The item filter.

Can be used to implement search within the sidebar.

Use [property`Sidebar`:py:data::placeholder<Adw.Sidebar.props.placeholder>] to provide an empty state.

New in version 1.9.

Adw.Sidebar.props.items¶

Name:: items
Type:: Gtk.SelectionModel
Default Value:: None
Flags:: READABLE

A list model with the sidebar’s items.

This can be used to keep an up-to-date view.

The model implements [iface`Gtk`.SectionModel] and creates sections corresponding to the sidebar’s sections.

The model also implements [iface`Gtk`.SelectionModel] and can be used to track and change the selection.

To only track sections, use [property`Sidebar`:py:data::sections<Adw.Sidebar.props.sections>] instead.

New in version 1.9.

Adw.Sidebar.props.menu_model¶

Name:: menu-model
Type:: Gio.MenuModel
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Context menu model for the items.

When a context menu is shown for an item, it will be constructed from the provided menu model. Use the [signal`Sidebar`:py:func:::setup-menu<Adw.Sidebar.signals.setup_menu>] signal to set up the menu actions for the particular item.

[property`Sidebar`:py:data::menu-model<Adw.Sidebar.props.menu_model>] will be preferred over this model if set.

New in version 1.9.

Adw.Sidebar.props.mode¶

Name:: mode
Type:: Adw.SidebarMode
Default Value:: Adw.SidebarMode.SIDEBAR
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Determines the sidebar’s look and behavior.

If set to [enum`Adw`.SidebarMode.sidebar], behaves like a sidebar: with a sidebar style and a persistent selection.

If set to [enum`Adw`.SidebarMode.page], behaves like a page of boxed lists. In this mode, the selection is invisible and only tracked to determine the initially selected item once switched back to sidebar mode.

The page mode is intended to be used with [class`NavigationSplitView`] when collapsed, as the sidebar pane becomes a page there.

When used with [class`OverlaySplitView`], the sidebar should stay in sidebar mode, as the sidebar pane is still a sidebar when collapsed.

New in version 1.9.

Adw.Sidebar.props.placeholder¶

Name:: placeholder
Type:: Gtk.Widget
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The placeholder widget.

This widget will be shown if the sidebar has no items, or all of its items have been filtered out by [property`Sidebar`:py:data::filter<Adw.Sidebar.props.filter>].

New in version 1.9.

Adw.Sidebar.props.sections¶

Name:: sections
Type:: Gio.ListModel
Default Value:: None
Flags:: READABLE

A list model with the sidebar’s sections.

This can be used to keep an up-to-date view.

To track items, use [property`Sidebar`:py:data::items<Adw.Sidebar.props.items>] instead.

New in version 1.9.

Adw.Sidebar.props.selected¶

Name:: selected
Type:: int
Default Value:: 4294967295
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The index of the currently selected item.

If set to [const`Gtk`.INVALID_LIST_POSITION], no item is selected.

If [property`Sidebar`:py:data::mode<Adw.Sidebar.props.mode>] is set to [enum`Adw`.SidebarMode.page], the selection is invisible, but still tracked, indicating which item will be selected once the mode is changed to [enum`Adw`.SidebarMode.sidebar].

See also: [property`Sidebar`:py:data::selected-item<Adw.Sidebar.props.selected_item>].

New in version 1.9.

Adw.Sidebar.props.selected_item¶

Name:: selected-item
Type:: Adw.SidebarItem
Default Value:: None
Flags:: READABLE

The currently selected item.

This is a convenience property, equivalent to calling [method`Sidebar`.get_item] with [property`Sidebar`:py:data::selected<Adw.Sidebar.props.selected>] provided as the index.

To change selection, use [property`Sidebar`:py:data::selected<Adw.Sidebar.props.selected>].

New in version 1.9.