Class ListBox

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.gtk.ListBox
All Implemented Interfaces:
Accessible, Buildable, ConstraintTarget, Proxy
@Generated("org.javagi.JavaGI") public class ListBox extends Widget implements Accessible, Buildable, ConstraintTarget

Shows a vertical list.

An example GtkListBox

A GtkListBox only contains GtkListBoxRow children. These rows can by dynamically sorted and filtered, and headers can be added dynamically depending on the row content. It also allows keyboard and mouse navigation and selection like a typical list.

Using GtkListBox is often an alternative to GtkTreeView, especially when the list contents has a more complicated layout than what is allowed by a GtkCellRenderer, or when the contents is interactive (i.e. has a button in it).

Although a GtkListBox must have only GtkListBoxRow children, you can add any kind of widget to it via prepend(Widget), append(Widget) and insert(Widget, int) and a GtkListBoxRow widget will automatically be inserted between the list and the widget.

GtkListBoxRows can be marked as activatable or selectable. If a row is activatable, Gtk.ListBox::row-activated will be emitted for it when the user tries to activate it. If it is selectable, the row will be marked as selected when the user tries to select it.

GtkListBox as GtkBuildable

The GtkListBox implementation of the GtkBuildable interface supports setting a child as the placeholder by specifying “placeholder” as the “type” attribute of a <child> element. See setPlaceholder(Widget) for info.

Shortcuts and Gestures

The following signals have default keybindings:

  • Gtk.ListBox::move-cursor
  • Gtk.ListBox::select-all
  • Gtk.ListBox::toggle-cursor-row
  • Gtk.ListBox::unselect-all

CSS nodes

list[.separators][.rich-list][.navigation-sidebar][.boxed-list]
╰── row[.activatable]

GtkListBox uses a single CSS node named list. It may carry the .separators style class, when the Gtk.ListBox:show-separators property is set. Each GtkListBoxRow uses a single CSS node named row. The row nodes get the .activatable style class added when appropriate.

It may also carry the .boxed-list style class. In this case, the list will be automatically surrounded by a frame and have separators.

The main list node may also carry style classes to select the style of list presentation: .rich-list, .navigation-sidebar or .data-table.

Accessibility

GtkListBox uses the Gtk.AccessibleRole.list role and GtkListBoxRow uses the Gtk.AccessibleRole.list_item role.

  • Constructor Details

    • ListBox

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

    • ListBox

      public ListBox()
      Create a new ListBox.

  • Method Details

    • getType

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

    • getMemoryLayout

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

    • asParent

      protected ListBox 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(Widget child)

      Append a widget to the list.

      If a sort function is set, the widget will actually be inserted at the calculated position.

      Parameters:
      child - the GtkWidget to add

    • bindModel

      public void bindModel(@Nullable ListModel model, @Nullable ListBoxCreateWidgetFunc createWidgetFunc)

      Binds model to box.

      If this ListBox was already bound to a model, that previous binding is destroyed.

      The contents of this ListBox are cleared and then filled with widgets that represent items from model. this ListBox is updated whenever model changes. If model is null, this ListBox is left empty.

      It is undefined to add or remove widgets directly (for example, with insert(Widget, int)) while this ListBox is bound to a model.

      Note that using a model is incompatible with the filtering and sorting functionality in GtkListBox. When using a model, filtering and sorting should be implemented by the model.

      Parameters:
      model - the GListModel to be bound to this ListBox
      createWidgetFunc - a function that creates widgets for items or null in case you also passed null as model

    • dragHighlightRow

      public void dragHighlightRow(ListBoxRow row)

      Add a drag highlight to a row.

      This is a helper function for implementing DnD onto a GtkListBox. The passed in row will be highlighted by setting the StateFlags.DROP_ACTIVE state and any previously highlighted row will be unhighlighted.

      The row will also be unhighlighted when the widget gets a drag leave event.

      Parameters:
      row - a GtkListBoxRow

    • dragUnhighlightRow

      public void dragUnhighlightRow()
      If a row has previously been highlighted via gtk_list_box_drag_highlight_row(), it will have the highlight removed.

    • getActivateOnSingleClick

      public boolean getActivateOnSingleClick()
      Returns whether rows activate on single clicks.
      Returns:
      true if rows are activated on single click, false otherwise

    • getAdjustment

      public @Nullable Adjustment getAdjustment()
      Gets the adjustment (if any) that the widget uses to for vertical scrolling.
      Returns:
      the adjustment

    • getRowAtIndex

      public @Nullable ListBoxRow getRowAtIndex(int index)

      Gets the n-th child in the list (not counting headers).

      If index is negative or larger than the number of items in the list, null is returned.

      Parameters:
      index - the index of the row
      Returns:
      the child GtkWidget

    • getRowAtY

      public @Nullable ListBoxRow getRowAtY(int y)
      Gets the row at the y position.
      Parameters:
      y - position
      Returns:
      the row

    • getSelectedRow

      public @Nullable ListBoxRow getSelectedRow()

      Gets the selected row, or null if no rows are selected.

      Note that the box may allow multiple selection, in which case you should use selectedForeach(ListBoxForeachFunc) to find all selected rows.

      Returns:
      the selected row

    • getSelectedRows

      public List<ListBoxRow> getSelectedRows()
      Creates a list of all selected children.
      Returns:
      A GList containing the GtkWidget for each selected child. Free with g_list_free() when done.

    • getSelectionMode

      public SelectionMode getSelectionMode()
      Gets the selection mode of the listbox.
      Returns:
      a GtkSelectionMode

    • getShowSeparators

      public boolean getShowSeparators()
      Returns whether the list box should show separators between rows.
      Returns:
      true if the list box shows separators

    • getTabBehavior

      public ListTabBehavior getTabBehavior()
      Returns the behavior of the Tab and Shift+Tab keys.
      Returns:
      the tab behavior
      Since:
      4.18

    • insert

      public void insert(Widget child, int position)

      Insert the child into the this ListBox at position.

      If a sort function is set, the widget will actually be inserted at the calculated position.

      If position is -1, or larger than the total number of items in the box, then the child will be appended to the end.

      Parameters:
      child - the GtkWidget to add
      position - the position to insert child in

    • invalidateFilter

      public void invalidateFilter()

      Update the filtering for all rows.

      Call this when result of the filter function on the this ListBox is changed due to an external factor. For instance, this would be used if the filter function just looked for a specific search string and the entry with the search string has changed.

    • invalidateHeaders

      public void invalidateHeaders()

      Update the separators for all rows.

      Call this when result of the header function on the this ListBox is changed due to an external factor.

    • invalidateSort

      public void invalidateSort()

      Update the sorting for all rows.

      Call this when result of the sort function on the this ListBox is changed due to an external factor.

    • prepend

      public void prepend(Widget child)

      Prepend a widget to the list.

      If a sort function is set, the widget will actually be inserted at the calculated position.

      Parameters:
      child - the GtkWidget to add

    • remove

      public void remove(Widget child)
      Removes a child from box.
      Parameters:
      child - the child to remove

    • removeAll

      public void removeAll()

      Removes all rows from box.

      This function does nothing if this ListBox is backed by a model.

      Since:
      4.12

    • selectAll

      public void selectAll()
      Select all children of box, if the selection mode allows it.

    • selectRow

      public void selectRow(@Nullable ListBoxRow row)
      Make row the currently selected row.
      Parameters:
      row - The row to select

    • selectedForeach

      public void selectedForeach(@Nullable ListBoxForeachFunc func)

      Calls a function for each selected child.

      Note that the selection cannot be modified from within this function.

      Parameters:
      func - the function to call for each selected child

    • setActivateOnSingleClick

      public void setActivateOnSingleClick(boolean single)
      If single is true, rows will be activated when you click on them, otherwise you need to double-click.
      Parameters:
      single - a boolean

    • setAdjustment

      public void setAdjustment(@Nullable Adjustment adjustment)

      Sets the adjustment (if any) that the widget uses to for vertical scrolling.

      For instance, this is used to get the page size for PageUp/Down key handling.

      In the normal case when the this ListBox is packed inside a GtkScrolledWindow the adjustment from that will be picked up automatically, so there is no need to manually do that.

      Parameters:
      adjustment - the adjustment

    • setFilterFunc

      public void setFilterFunc(@Nullable ListBoxFilterFunc filterFunc)

      By setting a filter function on the this ListBox one can decide dynamically which of the rows to show.

      For instance, to implement a search function on a list that filters the original list to only show the matching rows.

      The filterFunc will be called for each row after the call, and it will continue to be called each time a row changes (via ListBoxRow.changed()) or when invalidateFilter() is called.

      Note that using a filter function is incompatible with using a model (see bindModel(ListModel, ListBoxCreateWidgetFunc)).

      Parameters:
      filterFunc - callback that lets you filter which rows to show

    • setHeaderFunc

      public void setHeaderFunc(@Nullable ListBoxUpdateHeaderFunc updateHeader)

      Sets a header function.

      By setting a header function on the this ListBox one can dynamically add headers in front of rows, depending on the contents of the row and its position in the list.

      For instance, one could use it to add headers in front of the first item of a new kind, in a list sorted by the kind.

      The updateHeader can look at the current header widget using ListBoxRow.getHeader() and either update the state of the widget as needed, or set a new one using ListBoxRow.setHeader(Widget). If no header is needed, set the header to null.

      Note that you may get many calls updateHeader to this for a particular row when e.g. changing things that don’t affect the header. In this case it is important for performance to not blindly replace an existing header with an identical one.

      The updateHeader function will be called for each row after the call, and it will continue to be called each time a row changes (via ListBoxRow.changed()) and when the row before changes (either by ListBoxRow.changed() on the previous row, or when the previous row becomes a different row). It is also called for all rows when invalidateHeaders() is called.

      Parameters:
      updateHeader - callback that lets you add row headers

    • setPlaceholder

      public void setPlaceholder(@Nullable Widget placeholder)
      Sets the placeholder widget that is shown in the list when it doesn't display any visible children.
      Parameters:
      placeholder - a GtkWidget

    • setSelectionMode

      public void setSelectionMode(SelectionMode mode)
      Sets how selection works in the listbox.
      Parameters:
      mode - The GtkSelectionMode

    • setShowSeparators

      public void setShowSeparators(boolean showSeparators)
      Sets whether the list box should show separators between rows.
      Parameters:
      showSeparators - true to show separators

    • setSortFunc

      public void setSortFunc(@Nullable ListBoxSortFunc sortFunc)

      Sets a sort function.

      By setting a sort function on the this ListBox one can dynamically reorder the rows of the list, based on the contents of the rows.

      The sortFunc will be called for each row after the call, and will continue to be called each time a row changes (via ListBoxRow.changed()) and when invalidateSort() is called.

      Note that using a sort function is incompatible with using a model (see bindModel(ListModel, ListBoxCreateWidgetFunc)).

      Parameters:
      sortFunc - the sort function

    • setTabBehavior

      public void setTabBehavior(ListTabBehavior behavior)
      Sets the behavior of the Tab and Shift+Tab keys.
      Parameters:
      behavior - the tab behavior
      Since:
      4.18

    • unselectAll

      public void unselectAll()
      Unselect all children of box, if the selection mode allows it.

    • unselectRow

      public void unselectRow(ListBoxRow row)
      Unselects a single row of box, if the selection mode allows it.
      Parameters:
      row - the row to unselect

    • onActivateCursorRow

      public SignalConnection<ListBox.ActivateCursorRowCallback> onActivateCursorRow(ListBox.ActivateCursorRowCallback handler)
      Emitted when the cursor row is activated.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitActivateCursorRow

      public void emitActivateCursorRow()
      Emits the "activate-cursor-row" signal. See onActivateCursorRow(ListBox.ActivateCursorRowCallback).

    • onMoveCursor

      public SignalConnection<ListBox.MoveCursorCallback> onMoveCursor(ListBox.MoveCursorCallback handler)

      Emitted when the user initiates a cursor movement.

      The default bindings for this signal come in two variants, the variant with the Shift modifier extends the selection, the variant without the Shift modifier does not. There are too many key combinations to list them all here.

      • ←, →, ↑, ↓ move by individual children
      • Home, End move to the ends of the box
      • PgUp, PgDn move vertically by pages
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitMoveCursor

      public void emitMoveCursor(MovementStep step, int count, boolean extend, boolean modify)
      Emits the "move-cursor" signal. See onMoveCursor(ListBox.MoveCursorCallback).

    • onRowActivated

      public SignalConnection<ListBox.RowActivatedCallback> onRowActivated(ListBox.RowActivatedCallback handler)
      Emitted when a row has been activated by the user.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitRowActivated

      public void emitRowActivated(@Nullable ListBoxRow row)
      Emits the "row-activated" signal. See onRowActivated(ListBox.RowActivatedCallback).

    • onRowSelected

      public SignalConnection<ListBox.RowSelectedCallback> onRowSelected(ListBox.RowSelectedCallback handler)

      Emitted when a new row is selected, or (with a null row) when the selection is cleared.

      When the box is using SelectionMode.MULTIPLE, this signal will not give you the full picture of selection changes, and you should use the Gtk.ListBox::selected-rows-changed signal instead.

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

    • emitRowSelected

      public void emitRowSelected(@Nullable ListBoxRow row)
      Emits the "row-selected" signal. See onRowSelected(ListBox.RowSelectedCallback).

    • onSelectAll

      public SignalConnection<ListBox.SelectAllCallback> onSelectAll(ListBox.SelectAllCallback handler)

      Emitted to select all children of the box, if the selection mode permits it.

      This is a keybinding signal.

      The default binding for this signal is Ctrl-a.

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

    • emitSelectAll

      public void emitSelectAll()
      Emits the "select-all" signal. See onSelectAll(ListBox.SelectAllCallback).

    • onSelectedRowsChanged

      public SignalConnection<ListBox.SelectedRowsChangedCallback> onSelectedRowsChanged(ListBox.SelectedRowsChangedCallback handler)
      Emitted when the set of selected rows changes.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitSelectedRowsChanged

      public void emitSelectedRowsChanged()
      Emits the "selected-rows-changed" signal. See onSelectedRowsChanged(ListBox.SelectedRowsChangedCallback).

    • onToggleCursorRow

      public SignalConnection<ListBox.ToggleCursorRowCallback> onToggleCursorRow(ListBox.ToggleCursorRowCallback handler)

      Emitted when the cursor row is toggled.

      The default bindings for this signal is Ctrl+␣.

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

    • emitToggleCursorRow

      public void emitToggleCursorRow()
      Emits the "toggle-cursor-row" signal. See onToggleCursorRow(ListBox.ToggleCursorRowCallback).

    • onUnselectAll

      public SignalConnection<ListBox.UnselectAllCallback> onUnselectAll(ListBox.UnselectAllCallback handler)

      Emitted to unselect all children of the box, if the selection mode permits it.

      This is a keybinding signal.

      The default binding for this signal is Ctrl-Shift-a.

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

    • emitUnselectAll

      public void emitUnselectAll()
      Emits the "unselect-all" signal. See onUnselectAll(ListBox.UnselectAllCallback).

    • builder

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