Adw.Sidebar – libadwaita-1 Reference Manual

Packages

libadwaita-1

Adw

Sidebar

Sidebar

Object Hierarchy:

Object hierarchy for Sidebar

Description:

[ CCode ( type_id = "adw_sidebar_get_type ()" ) ]
[ Version ( since = "1.9" ) ]
public sealed class Sidebar : Widget, Accessible, Buildable, ConstraintTarget

Adaptive sidebar widget.

<picture> <source srcset="sidebar-dark.png" media="(prefers-color-scheme: dark)"> <img src="sidebar.png" alt="sidebar" > </picture>

`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:items].

To inspect sections themselves, use [method@Sidebar.get_section] or [property@Sidebar:sections].

Selection and activation

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

Selection cannot be permanently disabled.

[property@Sidebar:selected-item] can be used to access the selected item.

Connect to the [signal@Sidebar:AdwSidebar: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

<picture> <source srcset="sidebar-modes-dark.png" media="(prefers-color-scheme: dark)"> <img src="sidebar-modes.png" alt="sidebar-modes"> </picture>

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

Use the [property@Sidebar: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">  <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:filter] property.

Use [property@Sidebar: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:menu-model] property to provide a menu model, and the [ signal@Sidebar:AdwSidebar:setup-menu] signal to set up actions for the given item.

To set or override the menu for just one section, use [property@SidebarSection: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:AdwSidebar: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:AdwSidebar:drop-enter] signal and return the action from its handler.

To determine it based on the content, set [property@Sidebar:drop-preload] to `TRUE`, then connect to [signal@Sidebar:AdwSidebar: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:AdwSidebar: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:drag-motion-activate] to `FALSE` on them.

`AdwSidebar` as `GtkBuildable`

`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-classes.html#sidebars) style class in sidebar mode, or an [class@PreferencesPage] in page mode.

Accessibility

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

Namespace: Adw

Package: libadwaita-1

Content:

Properties:

public bool drop_preload { get; set; }
Whether the drop data should be preloaded on hover.
public Filter filter { get; set; }
The item filter.
public SelectionModel items { owned get; }
A list model with the sidebar's items.
public MenuModel menu_model { get; set; }
Context menu model for the items.
public SidebarMode mode { get; set; }
Determines the sidebar's look and behavior.
public Widget placeholder { get; set; }
The placeholder widget.
public ListModel sections { owned get; }
A list model with the sidebar's sections.
public uint selected { get; set; }
The index of the currently selected item.
public SidebarItem selected_item { get; }
The currently selected item.

Creation methods:

public Sidebar ()
Creates a new `AdwSidebar`.

Methods:

public void append (owned SidebarSection section)
Appends section to this .
public bool get_drop_preload ()
Gets whether drop data should be preloaded on hover.
public unowned Filter? get_filter ()
Gets the item filter for this.
public unowned SidebarItem? get_item (uint index)
Gets the item at index within this.
public SelectionModel get_items ()
Gets a list model with this's items.
public unowned MenuModel? get_menu_model ()
Gets the context menu model for this 's items.
public SidebarMode get_mode ()
Gets this's look and behavior.
public unowned Widget? get_placeholder ()
Gets the placeholder widget for this .
public unowned SidebarSection? get_section (uint index)
Gets the section at index within this.
public ListModel get_sections ()
Gets a list model with this's sections.
public uint get_selected ()
Gets the index of the currently selected item.
public unowned SidebarItem? get_selected_item ()
Gets the currently selected item.
public void insert (owned SidebarSection section, int position)
Inserts section at position to this.
public void prepend (owned SidebarSection section)
Prepends section to this .
public void remove (SidebarSection section)
Removes section from this .
public void remove_all ()
Removes all sections from this.
public void set_drop_preload (bool preload)
Sets whether drop data should be preloaded on hover.
public void set_filter (Filter? filter)
Sets the item filter for this.
public void set_menu_model (MenuModel? menu_model)
Sets the context menu model for this 's items.
public void set_mode (SidebarMode mode)
Sets this's look and behavior.
public void set_placeholder (Widget? placeholder)
Sets the placeholder widget for this .
public void set_selected (uint selected)
Selects the item at selected.
public void setup_drop_target (DragAction actions, Type[]? types)
Sets up a drop target on the items.

Signals:

public signal void activated (uint index)
Emitted when an item at index has been activated.
public signal bool drop (uint index, Value value, DragAction preferred_action)
Emitted when content is dropped onto the item at index.
public signal DragAction drop_enter (uint index)
Emitted when the pointer enters the item at index.
public signal DragAction drop_value_loaded (uint index, Value value)
Emitted when the dropped content is preloaded for the item at index.
public signal void setup_menu (SidebarItem? item)
Emitted when a context menu is opened or closed for item.

Inherited Members:

All known members inherited from class Gtk.Widget

All known members inherited from class GLib.Object

All known members inherited from interface Gtk.Accessible

All known members inherited from interface Gtk.Buildable

Generated by valadoc