Sidebar#

Added in version 1.9.

class Sidebar(**properties: Any)#

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, ConstraintTarget

Adaptive sidebar widget.

https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/sidebar.png

AdwSidebar contains SidebarSection objects, which in turn contain SidebarItem objects.

To add sections, use append, prepend or insert.

To remove sections, use remove or remove_all.

To inspect the items, use get_item or items.

To inspect sections themselves, use get_section or sections.

Selection and activation#

AdwSidebar has zero or one selected items. The index of the item can be accessed and changed via selected. Set it to INVALID_LIST_POSITION to remove selection.

Selection cannot be permanently disabled.

selected_item can be used to access the selected item.

Connect to the 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.

Modes#

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

Use the mode to determine its look and behavior.

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

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

Use 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.

Drag-and-Drop#

AdwSidebar items can have a drop target for arbitrary content.

Use setup_drop_target to set it up, specifying the supported content types and drag actions, then connect to 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 drop_enter signal and return the action from its handler.

To determine it based on the content, set drop_preload to TRUE, then connect to drop_value_loaded signal and return the action from its handler.

In both cases the action will be passed as a parameter to the 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 drag_motion_activate to FALSE on them.

AdwSidebar allows adding sections as children.

Example of an AdwSidebar UI definition:

<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 ListBox with the `.navigation-sidebar <style-classes.html#sidebars>`__ style class in sidebar mode, or an PreferencesPage in page mode.

Accessibility#

AdwSidebar uses the generic role.

Constructors#

class Sidebar

classmethod new() → Widget#: Creates a new AdwSidebar.

Added in version 1.9.

Methods#

class Sidebar

append(section: SidebarSection) → None#

Appends section to self.

Added in version 1.9.

Parameters:: section – a section to append

get_drop_preload() → bool#: Gets whether drop data should be preloaded on hover.

Added in version 1.9.

get_filter() → Filter | None#: Gets the item filter for self.

Added in version 1.9.

get_item(index: int) → SidebarItem | 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 get_index.

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

Added in version 1.9.

Parameters:: index – index of the item

get_items() → SelectionModel#

Gets a list model with self's items.

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

The model implements SectionModel and creates sections corresponding to the sidebar’s sections.

The model also implements SelectionModel and can be used to track and change the selection.

To only track sections, use sections instead.

Added in version 1.9.

get_menu_model() → MenuModel | None#: Gets the context menu model for self's items.

Added in version 1.9.

get_mode() → SidebarMode#: Gets self's look and behavior.

Added in version 1.9.

get_placeholder() → Widget | None#: Gets the placeholder widget for self.

Added in version 1.9.

get_section(index: int) → SidebarSection | None#

Gets the section at index within self.

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

Added in version 1.9.

Parameters:: index – index of the section

get_sections() → ListModel#

Gets a list model with self's sections.

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

To track items, use items instead.

Added in version 1.9.

get_selected() → int#

Gets the index of the currently selected item.

See also: get_selected_item.

Added in version 1.9.

get_selected_item() → SidebarItem | None#

Gets the currently selected item.

This is a convenience method, equivalent to calling get_item with selected provided as the index.

To change selection, use set_selected.

Added in version 1.9.

insert(section: SidebarSection, position: int) → None#

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.

Added in version 1.9.

Parameters:

section – a section to insert
position – position to insert section at

prepend(section: SidebarSection) → None#

Prepends section to self.

Added in version 1.9.

Parameters:: section – a section to prepend

remove(section: SidebarSection) → None#

Removes section from self.

Added in version 1.9.

Parameters:: section – a section to remove

remove_all() → None#: Removes all sections from self.

Added in version 1.9.

set_drop_preload(preload: bool) → None#

Sets whether drop data should be preloaded on hover.

See preload.

Added in version 1.9.

Parameters:: preload – whether to preload drop data

set_filter(filter: Filter | None = None) → None#

Sets the item filter for self.

Can be used to implement search within the sidebar.

Use placeholder to provide an empty state.

Added in version 1.9.

Parameters:: filter – the item filter

set_menu_model(menu_model: MenuModel | None = None) → None#

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 setup_menu signal to set up the menu actions for the particular item.

menu_model will be preferred over this model if set.

Added in version 1.9.

Parameters:: menu_model – a menu model

set_mode(mode: SidebarMode) → None#

Sets self's look and behavior.

If set to sidebar, behaves like a sidebar: with a sidebar style and a persistent selection.

If set to 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 NavigationSplitView when collapsed, as the sidebar pane becomes a page there.

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

Added in version 1.9.

Parameters:: mode – the new mode

set_placeholder(placeholder: Widget | None = None) → None#

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 filter.

Added in version 1.9.

Parameters:: placeholder – the placeholder widget

set_selected(selected: int) → None#

Selects the item at selected.

If set to INVALID_LIST_POSITION, no item is selected.

If mode is set to page, the selection is invisible, but still tracked, indicating which item will be selected once the mode is changed to sidebar.

Properties#

class Sidebar

props.drop_preload: bool#: The type of the None singleton.

Added in version 1.9.

props.filter: Filter#: The type of the None singleton.

Added in version 1.9.

props.items: SelectionModel#: The type of the None singleton.

Added in version 1.9.

props.menu_model: MenuModel#: The type of the None singleton.

Added in version 1.9.

props.mode: SidebarMode#: The type of the None singleton.

Added in version 1.9.

props.placeholder: Widget#: The type of the None singleton.

Added in version 1.9.

props.sections: ListModel#: The type of the None singleton.

Added in version 1.9.

props.selected: int#: The type of the None singleton.

Added in version 1.9.

props.selected_item: SidebarItem#: The type of the None singleton.

Added in version 1.9.