Package ch.bailu.gtk.gtk

Class ListBox

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.gobject.Object
ch.bailu.gtk.gobject.InitiallyUnowned
ch.bailu.gtk.gtk.Widget
ch.bailu.gtk.gtk.ListBox
All Implemented Interfaces:
PointerInterface
public class ListBox extends Widget
`GtkListBox` is a vertical list.

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 [method@Gtk.ListBox.prepend],
[method@Gtk.ListBox.append] and [method@Gtk.ListBox.insert] 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, [signal@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 [method@Gtk.ListBox.set_placeholder]
for info.

# CSS nodes 
<!-- language="plain" -->
 list[.separators][.rich-list][.navigation-sidebar]
 ╰── row[.activatable]


`GtkListBox` uses a single CSS node named list. It may carry the .separators
style class, when the [property@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.

The main list node may also carry style classes to select
the style of [list presentation](section-list-widget.html#list-styles):
.rich-list, .navigation-sidebar or .data-table.

# Accessibility

`GtkListBox` uses the %GTK_ACCESSIBLE_ROLE_LIST role and `GtkListBoxRow` uses
the %GTK_ACCESSIBLE_ROLE_LIST_ITEM role.

https://docs.gtk.org/gtk4/class.ListBox.html

  • Field Details

  • Constructor Details

    • ListBox

      public ListBox(PointerContainer pointer)

    • ListBox

      public ListBox()
      Creates a new `GtkListBox` container.

  • Method Details

    • getClassHandler

      public static ClassHandler getClassHandler()

    • append

      public void append(@Nonnull 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, ListBox.OnListBoxCreateWidgetFunc create_widget_func, @Nullable Pointer user_data, ListBox.OnDestroyNotify user_data_free_func)
      Binds @model to @box.

      If @box was already bound to a model, that previous binding is
      destroyed.

      The contents of @box are cleared and then filled with widgets that
      represent items from @model. @box is updated whenever @model changes.
      If @model is %NULL, @box is left empty.

      It is undefined to add or remove widgets directly (for example, with
      [method@Gtk.ListBox.insert]) while @box 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 @box
      create_widget_func - a function that creates widgets for items or %NULL in case you also passed %NULL as @model
      user_data - user data passed to @create_widget_func
      user_data_free_func - function for freeing @user_data

    • dragHighlightRow

      public void dragHighlightRow(@Nonnull 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
      %GTK_STATE_FLAG_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 Adjustment getAdjustment()
      Gets the adjustment (if any) that the widget uses to
      for vertical scrolling.
      Returns:
      the adjustment

    • getRowAtIndex

      public 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 ListBoxRow getRowAtY(int y)
      Gets the row at the @y position.
      Parameters:
      y - position
      Returns:
      the row

    • getSelectedRow

      public 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 [method@Gtk.ListBox.selected_foreach] to
      find all selected rows.
      Returns:
      the selected row

    • getSelectedRows

      public List 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 int 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

    • insert

      public void insert(@Nonnull Widget child, int position)
      Insert the @child into the @box 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 @box 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 @box 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 @box is changed due
      to an external factor.

    • prepend

      public void prepend(@Nonnull 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(@Nonnull Widget child)
      Removes a child from @box.
      Parameters:
      child - the child to remove

    • 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(ListBox.OnListBoxForeachFunc func, @Nullable Pointer data)
      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
      data - user data to pass to the function

    • 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 @box 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(ListBox.OnListBoxFilterFunc filter_func, @Nullable Pointer user_data, ListBox.OnDestroyNotify destroy)
      By setting a filter function on the @box 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 @filter_func will be called for each row after the call, and
      it will continue to be called each time a row changes (via
      [method@Gtk.ListBoxRow.changed]) or when [method@Gtk.ListBox.invalidate_filter]
      is called.

      Note that using a filter function is incompatible with using a model
      (see [method@Gtk.ListBox.bind_model]).
      Parameters:
      filter_func - callback that lets you filter which rows to show
      user_data - user data passed to @filter_func
      destroy - destroy notifier for @user_data

    • setHeaderFunc

      public void setHeaderFunc(ListBox.OnListBoxUpdateHeaderFunc update_header, @Nullable Pointer user_data, ListBox.OnDestroyNotify destroy)
      Sets a header function.

      By setting a header function on the @box 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 @update_header can look at the current header widget using
      [method@Gtk.ListBoxRow.get_header] and either update the state of the widget
      as needed, or set a new one using [method@Gtk.ListBoxRow.set_header]. If no
      header is needed, set the header to %NULL.

      Note that you may get many calls @update_header 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 @update_header function will be called for each row after the call,
      and it will continue to be called each time a row changes (via
      [method@Gtk.ListBoxRow.changed]) and when the row before changes (either
      by [method@Gtk.ListBoxRow.changed] on the previous row, or when the previous
      row becomes a different row). It is also called for all rows when
      [method@Gtk.ListBox.invalidate_headers] is called.
      Parameters:
      update_header - callback that lets you add row headers
      user_data - user data passed to @update_header
      destroy - destroy notifier for @user_data

    • 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(int mode)
      Sets how selection works in the listbox.
      Parameters:
      mode - The `GtkSelectionMode`

    • setShowSeparators

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

    • setSortFunc

      public void setSortFunc(ListBox.OnListBoxSortFunc sort_func, @Nullable Pointer user_data, ListBox.OnDestroyNotify destroy)
      Sets a sort function.

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

      The @sort_func will be called for each row after the call, and will
      continue to be called each time a row changes (via
      [method@Gtk.ListBoxRow.changed]) and when [method@Gtk.ListBox.invalidate_sort]
      is called.

      Note that using a sort function is incompatible with using a model
      (see [method@Gtk.ListBox.bind_model]).
      Parameters:
      sort_func - the sort function
      user_data - user data passed to @sort_func
      destroy - destroy notifier for @user_data

    • unselectAll

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

    • unselectRow

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

    • onActivateCursorRow

      public SignalHandler onActivateCursorRow(ListBox.OnActivateCursorRow signal)
      Connect to signal "activate-cursor-row".
      See ListBox.OnActivateCursorRow.onActivateCursorRow() for signal description.
      Field SIGNAL_ON_ACTIVATE_CURSOR_ROW contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onMoveCursor

      public SignalHandler onMoveCursor(ListBox.OnMoveCursor signal)
      Connect to signal "move-cursor".
      See ListBox.OnMoveCursor.onMoveCursor(int, int, boolean, boolean) for signal description.
      Field SIGNAL_ON_MOVE_CURSOR contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onRowActivated

      public SignalHandler onRowActivated(ListBox.OnRowActivated signal)
      Connect to signal "row-activated".
      See ListBox.OnRowActivated.onRowActivated(ch.bailu.gtk.gtk.ListBoxRow) for signal description.
      Field SIGNAL_ON_ROW_ACTIVATED contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onRowSelected

      public SignalHandler onRowSelected(ListBox.OnRowSelected signal)
      Connect to signal "row-selected".
      See ListBox.OnRowSelected.onRowSelected(ch.bailu.gtk.gtk.ListBoxRow) for signal description.
      Field SIGNAL_ON_ROW_SELECTED contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onSelectAll

      public SignalHandler onSelectAll(ListBox.OnSelectAll signal)
      Connect to signal "select-all".
      See ListBox.OnSelectAll.onSelectAll() for signal description.
      Field SIGNAL_ON_SELECT_ALL contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onSelectedRowsChanged

      public SignalHandler onSelectedRowsChanged(ListBox.OnSelectedRowsChanged signal)
      Connect to signal "selected-rows-changed".
      See ListBox.OnSelectedRowsChanged.onSelectedRowsChanged() for signal description.
      Field SIGNAL_ON_SELECTED_ROWS_CHANGED contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onToggleCursorRow

      public SignalHandler onToggleCursorRow(ListBox.OnToggleCursorRow signal)
      Connect to signal "toggle-cursor-row".
      See ListBox.OnToggleCursorRow.onToggleCursorRow() for signal description.
      Field SIGNAL_ON_TOGGLE_CURSOR_ROW contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • onUnselectAll

      public SignalHandler onUnselectAll(ListBox.OnUnselectAll signal)
      Connect to signal "unselect-all".
      See ListBox.OnUnselectAll.onUnselectAll() for signal description.
      Field SIGNAL_ON_UNSELECT_ALL contains original signal name and can be used as resource reference.
      Parameters:
      signal - callback function (lambda).
      Returns:
      SignalHandler. Can be used to disconnect signal and to release callback function.

    • asAccessible

      public Accessible asAccessible()
      Implements interface Accessible. Call this to get access to interface functions.
      Overrides:
      asAccessible in class Widget
      Returns:
      Accessible

    • asBuildable

      public Buildable asBuildable()
      Implements interface Buildable. Call this to get access to interface functions.
      Overrides:
      asBuildable in class Widget
      Returns:
      Buildable

    • asConstraintTarget

      public ConstraintTarget asConstraintTarget()
      Implements interface ConstraintTarget. Call this to get access to interface functions.
      Overrides:
      asConstraintTarget in class Widget
      Returns:
      ConstraintTarget

    • getTypeID

      public static long getTypeID()

    • getParentTypeID

      public static long getParentTypeID()

    • getTypeSize

      public static TypeSystem.TypeSize getTypeSize()

    • getParentTypeSize

      public static TypeSystem.TypeSize getParentTypeSize()

    • getInstanceSize

      public static int getInstanceSize()