:right-sidebar: True

Sidebar
===================================================================

.. currentmodule:: gi.repository.Adw


.. versionadded:: 1.9




.. class:: Sidebar(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`



Adaptive sidebar widget.

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

``AdwSidebar`` contains :obj:`~gi.repository.Adw.SidebarSection` objects, which in turn contain
:obj:`~gi.repository.Adw.SidebarItem` objects.

To add sections, use :obj:`~gi.repository.Sidebar.append`\, :obj:`~gi.repository.Sidebar.prepend` or
:obj:`~gi.repository.Sidebar.insert`\.

To remove sections, use :obj:`~gi.repository.Sidebar.remove` or
:obj:`~gi.repository.Sidebar.remove_all`\.

To inspect the items, use :obj:`~gi.repository.Sidebar.get_item` or
:obj:`~gi.repository.Adw.Sidebar.props.items`\.

To inspect sections themselves, use :obj:`~gi.repository.Sidebar.get_section` or
:obj:`~gi.repository.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 :obj:`~gi.repository.Adw.Sidebar.props.selected`\. Set it to
:obj:`~gi.repository.Gtk.INVALID_LIST_POSITION` to remove selection.

Selection cannot be permanently disabled.

:obj:`~gi.repository.Adw.Sidebar.props.selected_item` can be used to access the selected item.

Connect to the :obj:`~gi.repository.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: :obj:`~gi.repository.Adw.ViewSwitcherSidebar`\.

Modes
--------------------------------------------------------------------------------

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

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

Use the :obj:`~gi.repository.Adw.Sidebar.props.mode` to determine its look and behavior.

A typical use case involves using ``AdwSidebar`` inside the sidebar pane of a
:obj:`~gi.repository.Adw.NavigationSplitView`\, and switching mode to page whenever it's
collapsed, as follows:


.. code-block:: xml
    :dedent:

    <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 :obj:`~gi.repository.Adw.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 :obj:`~gi.repository.Adw.Sidebar.props.filter`
property.

Use :obj:`~gi.repository.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
:obj:`~gi.repository.Adw.Sidebar.props.menu_model` property to provide a menu model, and the
:obj:`~gi.repository.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
:obj:`~gi.repository.Adw.SidebarSection.props.menu_model` instead.

Drag-and-Drop
--------------------------------------------------------------------------------

``AdwSidebar`` items can have a drop target for arbitrary content.

Use :obj:`~gi.repository.Sidebar.setup_drop_target` to set it up, specifying the
supported content types and drag actions, then connect to
:obj:`~gi.repository.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
:obj:`~gi.repository.Adw.Sidebar.signals.drop_enter` signal and return the action from its handler.

To determine it based on the content, set :obj:`~gi.repository.Adw.Sidebar.props.drop_preload` to
``TRUE``\, then connect to :obj:`~gi.repository.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
:obj:`~gi.repository.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 :obj:`~gi.repository.Adw.SidebarItem.props.drag_motion_activate` to ``FALSE`` on them.


--------------------------------------------------------------------------------

``AdwSidebar`` allows adding sections as children.

Example of an ``AdwSidebar`` UI definition:


.. code-block:: xml
    :dedent:

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

Accessibility
--------------------------------------------------------------------------------

``AdwSidebar`` uses the :obj:`~gi.repository.Gtk.AccessibleRole.generic` role.


Constructors
------------

.. rst-class:: interim-class

.. class:: Sidebar
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.Widget

      Creates a new ``AdwSidebar``\.


      .. versionadded:: 1.9












Methods
-------

.. rst-class:: interim-class

.. class:: Sidebar
   :no-index:


   .. method:: append(section: ~gi.repository.Adw.SidebarSection) -> None

      Appends ``section`` to ``self``\.



      .. versionadded:: 1.9





      :param section: a section to append




   .. method:: get_drop_preload() -> bool

      Gets whether drop data should be preloaded on hover.



      .. versionadded:: 1.9








   .. method:: get_filter() -> ~gi.repository.Gtk.Filter | None

      Gets the item filter for ``self``\.



      .. versionadded:: 1.9








   .. method:: get_item(index: int) -> ~gi.repository.Adw.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 :obj:`~gi.repository.SidebarItem.get_index`\.

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



      .. versionadded:: 1.9





      :param index: index of the item




   .. method:: get_items() -> ~gi.repository.Gtk.SelectionModel

      Gets a list model with ``self``\'s items.

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

      The model implements :obj:`~gi.repository.Gtk.SectionModel` and creates sections
      corresponding to the sidebar's sections.

      The model also implements :obj:`~gi.repository.Gtk.SelectionModel` and can be used to
      track and change the selection.

      To only track sections, use :obj:`~gi.repository.Adw.Sidebar.props.sections` instead.



      .. versionadded:: 1.9








   .. method:: get_menu_model() -> ~gi.repository.Gio.MenuModel | None

      Gets the context menu model for ``self``\'s items.



      .. versionadded:: 1.9








   .. method:: get_mode() -> ~gi.repository.Adw.SidebarMode

      Gets ``self``\'s look and behavior.



      .. versionadded:: 1.9








   .. method:: get_placeholder() -> ~gi.repository.Gtk.Widget | None

      Gets the placeholder widget for ``self``\.



      .. versionadded:: 1.9








   .. method:: get_section(index: int) -> ~gi.repository.Adw.SidebarSection | None

      Gets the section at ``index`` within ``self``\.

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



      .. versionadded:: 1.9





      :param index: index of the section




   .. method:: get_sections() -> ~gi.repository.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 :obj:`~gi.repository.Adw.Sidebar.props.items` instead.



      .. versionadded:: 1.9








   .. method:: get_selected() -> int

      Gets the index of the currently selected item.

      See also: :obj:`~gi.repository.Sidebar.get_selected_item`\.



      .. versionadded:: 1.9








   .. method:: get_selected_item() -> ~gi.repository.Adw.SidebarItem | None

      Gets the currently selected item.

      This is a convenience method, equivalent to calling :obj:`~gi.repository.Sidebar.get_item`
      with :obj:`~gi.repository.Adw.Sidebar.props.selected` provided as the index.

      To change selection, use :obj:`~gi.repository.Sidebar.set_selected`\.



      .. versionadded:: 1.9








   .. method:: insert(section: ~gi.repository.Adw.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.



      .. versionadded:: 1.9





      :param section: a section to insert

      :param position: position to insert ``section`` at




   .. method:: prepend(section: ~gi.repository.Adw.SidebarSection) -> None

      Prepends ``section`` to ``self``\.



      .. versionadded:: 1.9





      :param section: a section to prepend




   .. method:: remove(section: ~gi.repository.Adw.SidebarSection) -> None

      Removes ``section`` from ``self``\.



      .. versionadded:: 1.9





      :param section: a section to remove




   .. method:: remove_all() -> None

      Removes all sections from ``self``\.



      .. versionadded:: 1.9








   .. method:: set_drop_preload(preload: bool) -> None

      Sets whether drop data should be preloaded on hover.

      See :obj:`~gi.repository.Gtk.DropTarget.props.preload`\.



      .. versionadded:: 1.9





      :param preload: whether to preload drop data




   .. method:: set_filter(filter: ~gi.repository.Gtk.Filter | None = None) -> None

      Sets the item filter for ``self``\.

      Can be used to implement search within the sidebar.

      Use :obj:`~gi.repository.Adw.Sidebar.props.placeholder` to provide an empty state.



      .. versionadded:: 1.9





      :param filter: the item filter




   .. method:: set_menu_model(menu_model: ~gi.repository.Gio.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 :obj:`~gi.repository.Adw.Sidebar.signals.setup_menu` signal to set up
      the menu actions for the particular item.

      :obj:`~gi.repository.Adw.Sidebar.props.menu_model` will be preferred over this model if set.



      .. versionadded:: 1.9





      :param menu_model: a menu model




   .. method:: set_mode(mode: ~gi.repository.Adw.SidebarMode) -> None

      Sets ``self``\'s look and behavior.

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

      If set to :obj:`~gi.repository.Adw.SidebarMode.sidebar`\, behaves like a sidebar: with a
      sidebar style and a persistent selection.

      If set to :obj:`~gi.repository.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 :obj:`~gi.repository.Adw.NavigationSplitView` when
      collapsed, as the sidebar pane becomes a page there.

      When used with :obj:`~gi.repository.Adw.OverlaySplitView`\, the sidebar should stay in sidebar
      mode, as the sidebar pane is still a sidebar when collapsed.



      .. versionadded:: 1.9





      :param mode: the new mode




   .. method:: set_placeholder(placeholder: ~gi.repository.Gtk.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 :obj:`~gi.repository.Adw.Sidebar.props.filter`\.



      .. versionadded:: 1.9





      :param placeholder: the placeholder widget




   .. method:: set_selected(selected: int) -> None

      Selects the item at ``selected``\.

      If set to :obj:`~gi.repository.Gtk.INVALID_LIST_POSITION`\, no item is selected.

      If :obj:`~gi.repository.Adw.Sidebar.props.mode` is set to :obj:`~gi.repository.Adw.SidebarMode.page`\, the
      selection is invisible, but still tracked, indicating which item will be
      selected once the mode is changed to :obj:`~gi.repository.Adw.SidebarMode.sidebar`\.

      See also: :obj:`~gi.repository.Adw.Sidebar.props.selected_item`\.



      .. versionadded:: 1.9





      :param selected: index of the newly selected item




   .. method:: setup_drop_target(actions: ~gi.repository.Gdk.DragAction, types: list[~gobject.GType] | None = None) -> None

      Sets up a drop target on the items.

      This allows to drag arbitrary content onto items.

      The :obj:`~gi.repository.Adw.Sidebar.signals.drop` signal can be used to handle the drop.



      .. versionadded:: 1.9





      :param actions: the supported actions

      :param types: all supported ``GType``\s that can be dropped








Properties
----------

.. rst-class:: interim-class

.. class:: Sidebar
   :no-index:
   

   .. attribute:: props.drop_preload
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.9





   .. attribute:: props.filter
      :type: ~gi.repository.Gtk.Filter

      The type of the None singleton.



      .. versionadded:: 1.9





   .. attribute:: props.items
      :type: ~gi.repository.Gtk.SelectionModel

      The type of the None singleton.



      .. versionadded:: 1.9





   .. attribute:: props.menu_model
      :type: ~gi.repository.Gio.MenuModel

      The type of the None singleton.



      .. versionadded:: 1.9





   .. attribute:: props.mode
      :type: ~gi.repository.Adw.SidebarMode

      The type of the None singleton.



      .. versionadded:: 1.9





   .. attribute:: props.placeholder
      :type: ~gi.repository.Gtk.Widget

      The type of the None singleton.



      .. versionadded:: 1.9





   .. attribute:: props.sections
      :type: ~gi.repository.Gio.ListModel

      The type of the None singleton.



      .. versionadded:: 1.9





   .. attribute:: props.selected
      :type: int

      The type of the None singleton.



      .. versionadded:: 1.9





   .. attribute:: props.selected_item
      :type: ~gi.repository.Adw.SidebarItem

      The type of the None singleton.



      .. versionadded:: 1.9









Signals
-------

.. rst-class:: interim-class

.. class:: Sidebar.signals
   :no-index:
   

   .. method:: activated(index: int) -> None

      The type of the None singleton.



      .. versionadded:: 1.9





      :param index: the item index




   .. method:: drop(index: int, value: ~gi.repository.GObject.Value, preferred_action: ~gi.repository.Gdk.DragAction) -> bool

      The type of the None singleton.







      :param index: index of the item the content was dropped onto

      :param value: the ``GValue`` being dropped

      :param preferred_action: the preferred drop action




   .. method:: drop_enter(index: int) -> ~gi.repository.Gdk.DragAction

      The type of the None singleton.



      .. versionadded:: 1.9





      :param index: index of the hovered item




   .. method:: drop_value_loaded(index: int, value: ~gi.repository.GObject.Value) -> ~gi.repository.Gdk.DragAction

      The type of the None singleton.



      .. versionadded:: 1.9





      :param index: index of the hovered item

      :param value: the ``GValue`` being dropped




   .. method:: setup_menu(item: ~gi.repository.Adw.SidebarItem | None = None) -> None

      The type of the None singleton.







      :param item: an item in ``self``