:right-sidebar: True

ListBox
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: ListBox(**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`



``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 :obj:`~gi.repository.Gtk.ListBox.prepend`,
:obj:`~gi.repository.Gtk.ListBox.append` and :obj:`~gi.repository.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, :obj:`~gi.repository.Gtk.ListBox.signals.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 :obj:`~gi.repository.Gtk.ListBox.set_placeholder`
for info.

CSS nodes
---------


.. code-block:: plain
   :dedent:

   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 :obj:`~gi.repository.Gtk.ListBox.props.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 <section-list-widget.html#list-styles>`_:
.rich-list, .navigation-sidebar or .data-table.

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

``GtkListBox`` uses the :const:`~gi.repository.Gtk.AccessibleRole.LIST` role and ``GtkListBoxRow`` uses
the :const:`~gi.repository.Gtk.AccessibleRole.LIST_ITEM` role.



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

.. rst-class:: interim-class

.. class:: ListBox
   :no-index:


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

      Creates a new ``GtkListBox`` container.














Methods
-------

.. rst-class:: interim-class

.. class:: ListBox
   :no-index:


   .. method:: append(child: ~gi.repository.Gtk.Widget) -> None

      Append a widget to the list.

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







      :param child: the ``GtkWidget`` to add





   .. method:: bind_model(model: ~gi.repository.Gio.ListModel | None = None, create_widget_func: ~typing.Callable[[...], ~gi.repository.Gtk.Widget] | None = None, *user_data: ~typing.Any) -> None

      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 :const:`None`, ``box`` is left empty.

      It is undefined to add or remove widgets directly (for example, with
      :obj:`~gi.repository.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.







      :param model: the ``GListModel`` to be bound to ``box``


      :param create_widget_func: a function that creates widgets for items
         or :const:`None` in case you also passed :const:`None` as ``model``


      :param user_data: user data passed to ``create_widget_func``





   .. method:: drag_highlight_row(row: ~gi.repository.Gtk.ListBoxRow) -> None

      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
      :const:`~gi.repository.Gtk.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.







      :param row: a ``GtkListBoxRow``





   .. method:: drag_unhighlight_row() -> None

      If a row has previously been highlighted via :func:`~gi.repository.Gtk.ListBox.drag_highlight_row`,
      it will have the highlight removed.










   .. method:: get_activate_on_single_click() -> bool

      Returns whether rows activate on single clicks.










   .. method:: get_adjustment() -> ~gi.repository.Gtk.Adjustment | None

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










   .. method:: get_row_at_index(index_: int) -> ~gi.repository.Gtk.ListBoxRow | None

      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, :const:`None` is returned.







      :param index_: the index of the row





   .. method:: get_row_at_y(y: int) -> ~gi.repository.Gtk.ListBoxRow | None

      Gets the row at the ``y`` position.







      :param y: position





   .. method:: get_selected_row() -> ~gi.repository.Gtk.ListBoxRow | None

      Gets the selected row, or :const:`None` if no rows are selected.

      Note that the box may allow multiple selection, in which
      case you should use :obj:`~gi.repository.Gtk.ListBox.selected_foreach` to
      find all selected rows.










   .. method:: get_selected_rows() -> list[~gi.repository.Gtk.ListBoxRow]

      Creates a list of all selected children.










   .. method:: get_selection_mode() -> ~gi.repository.Gtk.SelectionMode

      Gets the selection mode of the listbox.










   .. method:: get_show_separators() -> bool

      Returns whether the list box should show separators
      between rows.










   .. method:: insert(child: ~gi.repository.Gtk.Widget, position: int) -> None

      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.







      :param child: the ``GtkWidget`` to add


      :param position: the position to insert ``child`` in





   .. method:: invalidate_filter() -> None

      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.










   .. method:: invalidate_headers() -> None

      Update the separators for all rows.

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










   .. method:: invalidate_sort() -> None

      Update the sorting for all rows.

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










   .. method:: prepend(child: ~gi.repository.Gtk.Widget) -> None

      Prepend a widget to the list.

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







      :param child: the ``GtkWidget`` to add





   .. method:: remove(child: ~gi.repository.Gtk.Widget) -> None

      Removes a child from ``box``.







      :param child: the child to remove





   .. method:: remove_all() -> None

      Removes all rows from ``box``.

      This function does nothing if ``box`` is backed by a model.



      .. versionadded:: 4.12








   .. method:: select_all() -> None

      Select all children of ``box``, if the selection mode allows it.










   .. method:: select_row(row: ~gi.repository.Gtk.ListBoxRow | None = None) -> None

      Make ``row`` the currently selected row.







      :param row: The row to select





   .. method:: selected_foreach(func: ~typing.Callable[[...], None], *data: ~typing.Any) -> None

      Calls a function for each selected child.

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







      :param func: the function to call for each selected child


      :param data: user data to pass to the function





   .. method:: set_activate_on_single_click(single: bool) -> None

      If ``single`` is :const:`True`, rows will be activated when you click on them,
      otherwise you need to double-click.







      :param single: a boolean





   .. method:: set_adjustment(adjustment: ~gi.repository.Gtk.Adjustment | None = None) -> None

      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.







      :param adjustment: the adjustment





   .. method:: set_filter_func(filter_func: ~typing.Callable[[...], bool] | None = None, *user_data: ~typing.Any) -> None

      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
      :obj:`~gi.repository.Gtk.ListBoxRow.changed`) or when :obj:`~gi.repository.Gtk.ListBox.invalidate_filter`
      is called.

      Note that using a filter function is incompatible with using a model
      (see :obj:`~gi.repository.Gtk.ListBox.bind_model`).







      :param filter_func: callback that lets you filter which rows to show


      :param user_data: user data passed to ``filter_func``





   .. method:: set_header_func(update_header: ~typing.Callable[[...], None] | None = None, *user_data: ~typing.Any) -> None

      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
      :obj:`~gi.repository.Gtk.ListBoxRow.get_header` and either update the state of the widget
      as needed, or set a new one using :obj:`~gi.repository.Gtk.ListBoxRow.set_header`. If no
      header is needed, set the header to :const:`None`.

      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
      :obj:`~gi.repository.Gtk.ListBoxRow.changed`) and when the row before changes (either
      by :obj:`~gi.repository.Gtk.ListBoxRow.changed` on the previous row, or when the previous
      row becomes a different row). It is also called for all rows when
      :obj:`~gi.repository.Gtk.ListBox.invalidate_headers` is called.







      :param update_header: callback that lets you add row headers


      :param user_data: user data passed to ``update_header``





   .. method:: set_placeholder(placeholder: ~gi.repository.Gtk.Widget | None = None) -> None

      Sets the placeholder widget that is shown in the list when
      it doesn't display any visible children.







      :param placeholder: a ``GtkWidget``





   .. method:: set_selection_mode(mode: ~gi.repository.Gtk.SelectionMode) -> None

      Sets how selection works in the listbox.







      :param mode: The ``GtkSelectionMode``





   .. method:: set_show_separators(show_separators: bool) -> None

      Sets whether the list box should show separators
      between rows.







      :param show_separators: :const:`True` to show separators





   .. method:: set_sort_func(sort_func: ~typing.Callable[[...], int] | None = None, *user_data: ~typing.Any) -> None

      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
      :obj:`~gi.repository.Gtk.ListBoxRow.changed`) and when :obj:`~gi.repository.Gtk.ListBox.invalidate_sort`
      is called.

      Note that using a sort function is incompatible with using a model
      (see :obj:`~gi.repository.Gtk.ListBox.bind_model`).







      :param sort_func: the sort function


      :param user_data: user data passed to ``sort_func``





   .. method:: unselect_all() -> None

      Unselect all children of ``box``, if the selection mode allows it.










   .. method:: unselect_row(row: ~gi.repository.Gtk.ListBoxRow) -> None

      Unselects a single row of ``box``, if the selection mode allows it.







      :param row: the row to unselect









Properties
----------

.. rst-class:: interim-class

.. class:: ListBox
   :no-index:
   

   .. attribute:: props.accept_unpaired_release
      :type: bool

      Whether to accept unpaired release events.







   .. attribute:: props.activate_on_single_click
      :type: bool

      Determines whether children can be activated with a single
      click, or require a double-click.







   .. attribute:: props.selection_mode
      :type: ~gi.repository.Gtk.SelectionMode

      The selection mode used by the list box.







   .. attribute:: props.show_separators
      :type: bool

      Whether to show separators between rows.











Signals
-------

.. rst-class:: interim-class

.. class:: ListBox.signals
   :no-index:
   

   .. method:: activate_cursor_row() -> None

      









   .. method:: move_cursor(object: ~gi.repository.Gtk.MovementStep, p0: int, p1: bool, p2: bool) -> None

      






      :param object: 

      :param p0: 

      :param p1: 

      :param p2: 




   .. method:: row_activated(row: ~gi.repository.Gtk.ListBoxRow) -> None

      Emitted when a row has been activated by the user.







      :param row: the activated row





   .. method:: row_selected(row: ~gi.repository.Gtk.ListBoxRow | None = None) -> None

      Emitted when a new row is selected, or (with a :const:`None` ``row``)
      when the selection is cleared.

      When the ``box`` is using :const:`~gi.repository.Gtk.SelectionMode.MULTIPLE`, this signal will not
      give you the full picture of selection changes, and you should use
      the :obj:`~gi.repository.Gtk.ListBox.signals.selected_rows_changed` signal instead.







      :param row: the selected row





   .. method:: select_all() -> None

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

      This is a `keybinding signal <class.SignalAction.html>`_.

      The default binding for this signal is :kbd:`Ctrl`-:kbd:`a`.










   .. method:: selected_rows_changed() -> None

      Emitted when the set of selected rows changes.










   .. method:: toggle_cursor_row() -> None

      









   .. method:: unselect_all() -> None

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

      This is a `keybinding signal <class.SignalAction.html>`_.

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