Class Sidebar

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.gobject.TypeInstance
org.gnome.gobject.GObject
org.gnome.gobject.InitiallyUnowned
org.gnome.gtk.Widget
org.gnome.adw.Sidebar
All Implemented Interfaces:
Accessible, Buildable, ConstraintTarget, Proxy
@Generated("org.javagi.JavaGI") public final class Sidebar extends Widget implements Accessible, Buildable, ConstraintTarget

Adaptive sidebar widget.

sidebar

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

To add sections, use append(SidebarSection), prepend(SidebarSection) or insert(SidebarSection, int).

To remove sections, use remove(SidebarSection) or removeAll().

To inspect the items, use getItem(int) or Sidebar:items.

To inspect sections themselves, use getSection(int) or Sidebar:sections.

Selection and activation

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

Selection cannot be permanently disabled.

Sidebar:selected-item can be used to access the selected item.

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

Modes

sidebar-modes

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

Use the Sidebar: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 Sidebar:filter property.

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

To set or override the menu for just one section, use SidebarSection:menu-model instead.

Drag-and-Drop

AdwSidebar items can have a drop target for arbitrary content.

Use setupDropTarget(Set, Type[]) to set it up, specifying the supported content types and drag actions, then connect to Sidebar::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 Sidebar::drop-enter signal and return the action from its handler.

To determine it based on the content, set Sidebar:drop-preload to TRUE, then connect to Sidebar::drop-value-loaded signal and return the action from its handler.

In both cases the action will be passed as a parameter to the Sidebar::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 SidebarItem:drag-motion-activate to FALSE on them.

AdwSidebar as GtkBuildable

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 class in sidebar mode, or an PreferencesPage in page mode.

Accessibility

AdwSidebar uses the Gtk.AccessibleRole.generic role.

Since:
1.9

  • Constructor Details

    • Sidebar

      public Sidebar(MemorySegment address)
      Create a Sidebar instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Sidebar

      public Sidebar()
      Create a new Sidebar.

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Sidebar class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • asParent

      protected Sidebar asParent()
      Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.
      Overrides:
      asParent in class Widget
      Returns:
      the instance as if it were its parent type

    • append

      public void append(SidebarSection section)
      Appends section to self.
      Parameters:
      section - a section to append
      Since:
      1.9

    • getDropPreload

      public boolean getDropPreload()
      Gets whether drop data should be preloaded on hover.
      Returns:
      whether drop data should be preloaded on hover
      Since:
      1.9

    • getFilter

      public @Nullable Filter getFilter()
      Gets the item filter for self.
      Returns:
      the item filter
      Since:
      1.9

    • getItem

      public @Nullable SidebarItem getItem(int index)

      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 SidebarItem.getIndex().

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

      Parameters:
      index - index of the item
      Returns:
      the item at index
      Since:
      1.9

    • getItems

      public SelectionModel getItems()

      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 Sidebar:sections instead.

      Returns:
      a model containing the items
      Since:
      1.9

    • getMenuModel

      public @Nullable MenuModel getMenuModel()
      Gets the context menu model for self's items.
      Returns:
      the context menu model
      Since:
      1.9

    • getMode

      public SidebarMode getMode()
      Gets self's look and behavior.
      Returns:
      the current mode
      Since:
      1.9

    • getPlaceholder

      public @Nullable Widget getPlaceholder()
      Gets the placeholder widget for self.
      Returns:
      the placeholder widget
      Since:
      1.9

    • getSection

      public @Nullable SidebarSection getSection(int index)

      Gets the section at index within self.

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

      Parameters:
      index - index of the section
      Returns:
      the section at index
      Since:
      1.9

    • getSections

      public ListModel getSections()

      Gets a list model with self's sections.

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

      To track items, use Sidebar:items instead.

      Returns:
      a model containing the sections
      Since:
      1.9

    • getSelected

      public int getSelected()

      Gets the index of the currently selected item.

      See also: getSelectedItem().

      Returns:
      index of the currently selected item
      Since:
      1.9

    • getSelectedItem

      public @Nullable SidebarItem getSelectedItem()

      Gets the currently selected item.

      This is a convenience method, equivalent to calling getItem(int) with Sidebar:selected provided as the index.

      To change selection, use setSelected(int).

      Returns:
      the selected item
      Since:
      1.9

    • insert

      public void insert(SidebarSection section, int position)

      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.

      Parameters:
      section - a section to insert
      position - position to insert section at
      Since:
      1.9

    • prepend

      public void prepend(SidebarSection section)
      Prepends section to self.
      Parameters:
      section - a section to prepend
      Since:
      1.9

    • remove

      public void remove(SidebarSection section)
      Removes section from self.
      Parameters:
      section - a section to remove
      Since:
      1.9

    • removeAll

      public void removeAll()
      Removes all sections from self.
      Since:
      1.9

    • setDropPreload

      public void setDropPreload(boolean preload)

      Sets whether drop data should be preloaded on hover.

      See Gtk.DropTarget:preload.

      Parameters:
      preload - whether to preload drop data
      Since:
      1.9

    • setFilter

      public void setFilter(@Nullable Filter filter)

      Sets the item filter for self.

      Can be used to implement search within the sidebar.

      Use Sidebar:placeholder to provide an empty state.

      Parameters:
      filter - the item filter
      Since:
      1.9

    • setMenuModel

      public void setMenuModel(@Nullable MenuModel menuModel)

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

      Sidebar:menu-model will be preferred over this model if set.

      Parameters:
      menuModel - a menu model
      Since:
      1.9

    • setMode

      public void setMode(SidebarMode mode)

      Sets self's look and behavior.

      sidebar-modes

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

      If set to 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 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.

      Parameters:
      mode - the new mode
      Since:
      1.9

    • setPlaceholder

      public void setPlaceholder(@Nullable Widget placeholder)

      Sets the placeholder widget for self.

      This widget will be shown if this Sidebar has no items, or all of its items have been filtered out by Sidebar:filter.

      Parameters:
      placeholder - the placeholder widget
      Since:
      1.9

    • setSelected

      public void setSelected(int selected)

      Selects the item at selected.

      If set to Gtk.INVALID_LIST_POSITION, no item is selected.

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

      See also: Sidebar:selected-item.

      Parameters:
      selected - index of the newly selected item
      Since:
      1.9

    • setupDropTarget

      public void setupDropTarget(Set<DragAction> actions, @Nullable Type @Nullable [] types)

      Sets up a drop target on the items.

      This allows to drag arbitrary content onto items.

      The Sidebar::drop signal can be used to handle the drop.

      Parameters:
      actions - the supported actions
      types - all supported GTypes that can be dropped
      Since:
      1.9

    • setupDropTarget

      public void setupDropTarget(DragAction actions, @Nullable Type @Nullable [] types)

      Sets up a drop target on the items.

      This allows to drag arbitrary content onto items.

      The Sidebar::drop signal can be used to handle the drop.

      Parameters:
      actions - the supported actions
      types - all supported GTypes that can be dropped
      Since:
      1.9

    • onActivated

      public SignalConnection<Sidebar.ActivatedCallback> onActivated(Sidebar.ActivatedCallback handler)
      Emitted when an item at index has been activated.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      1.9
      See Also:

    • emitActivated

      public void emitActivated(int index)
      Emits the "activated" signal. See onActivated(Sidebar.ActivatedCallback).

    • onDrop

      public SignalConnection<Sidebar.DropCallback> onDrop(Sidebar.DropCallback handler)

      Emitted when content is dropped onto the item at index.

      The content must be of one of the types set up via setupDropTarget(Set, Type[]).

      See Gtk.DropTarget::drop.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitDrop

      public boolean emitDrop(int index, @Nullable Value value, Set<DragAction> preferredAction)
      Emits the "drop" signal. See onDrop(Sidebar.DropCallback).

    • onDropEnter

      public SignalConnection<Sidebar.DropEnterCallback> onDropEnter(Sidebar.DropEnterCallback handler)

      Emitted when the pointer enters the item at index.

      Applications can use this to set their default drop action even when Sidebar:drop-preload is set to FALSE.

      See Gtk.DropTarget::enter.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      1.9
      See Also:

    • emitDropEnter

      public Set<DragAction> emitDropEnter(int index)
      Emits the "drop-enter" signal. See onDropEnter(Sidebar.DropEnterCallback).

    • onDropValueLoaded

      public SignalConnection<Sidebar.DropValueLoadedCallback> onDropValueLoaded(Sidebar.DropValueLoadedCallback handler)

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

      In order for data to be preloaded, Sidebar:drop-preload must be set to TRUE.

      The content must be of one of the types set up via setupDropTarget(Set, Type[]).

      See Gtk.DropTarget:value.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      1.9
      See Also:

    • emitDropValueLoaded

      public Set<DragAction> emitDropValueLoaded(int index, @Nullable Value value)
      Emits the "drop-value-loaded" signal. See onDropValueLoaded(Sidebar.DropValueLoadedCallback).

    • onSetupMenu

      public SignalConnection<Sidebar.SetupMenuCallback> onSetupMenu(Sidebar.SetupMenuCallback handler)

      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.

      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitSetupMenu

      public void emitSetupMenu(@Nullable SidebarItem item)
      Emits the "setup-menu" signal. See onSetupMenu(Sidebar.SetupMenuCallback).

    • builder

      public static Sidebar.Builder<? extends Sidebar.Builder> builder()
      A Sidebar.Builder object constructs a Sidebar with the specified properties. Use the various set...() methods to set properties, and finish construction with Sidebar.Builder.build().
      Returns:
      the builder object