Gtk.ListBox

Gtk.ListBox — A list container

Object Hierarchy:

    GObject
    ╰── GInitiallyUnowned
        ╰── Gtk.Widget
            ╰── Gtk.Container
                ├── Gtk.Bin
                │   ╰── Gtk.ListBoxRow
                ╰── Gtk.ListBox

See also:

Gtk.ScrolledWindow

Functions:

Signals:

  • “activate-cursor-row” (listbox, user_data)
  • “move-cursor” (listbox, user_data)
  • “row-activated” (box, row, user_data)
  • “row-selected” (box, row, user_data)
  • “select-all” (box, user_data)
  • “selected-rows-changed” (box, user_data)
  • “toggle-cursor-row” (listbox, user_data)
  • “unselect-all” (box, user_data)

Description:

A Gtk.ListBox is a vertical container that contains Gtk.ListBoxRow 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 Gtk.TreeView, especially when the list contents has a more complicated layout than what is allowed by a Gtk.CellRenderer, or when the contents is interactive (i.e. has a button in it).

Although a Gtk.ListBox must have only Gtk.ListBoxRow children you can add any kind of widget to it via Gtk.Container::add(), and a Gtk.ListBoxRow widget will automatically be inserted between the list and the widget.

Gtk.ListBoxRows 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.

The Gtk.ListBox widget was added in GTK+ 3.10.

Function Details:

new()

new () -> Gtk.Widget

Creates a new Gtk.ListBox container.

  • Returns: a new Gtk.ListBox

  • Since: 3.10

prepend()

prepend (self, child:Gtk.Widget)

Prepend a widget to the list. If a sort function is set, the widget willactually be inserted at the calculated position and this function has thesame effect of `Gtk.Container:add()`.

  • Since: 3.10

insert()

insert (self, child:Gtk.Widget, position:int)

Insert the child into the box at position. If a sort function isset, the widget will actually be inserted at the calculated position andthis function has the same effect of `Gtk.Container:add(). Ifpositionis -1, or larger than the total number of items in thebox, then thechild` will be appended to the end.

  • Since: 3.10

select_row()

select_row (self, row:Gtk.ListBoxRow=None)

Make row the currently selected row.

  • Since: 3.10

unselect_row()

unselect_row (self, row:Gtk.ListBoxRow)

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

  • Since: 3.14

select_all()

select_all (self)

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

  • Since: 3.14

unselect_all()

unselect_all (self)

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

  • Since: 3.14

get_selected_row()

get_selected_row (self) -> Gtk.ListBoxRow

Gets the selected row. Note that the box may allow multiple selection, in whichcase you should use Gtk.ListBox:selected_foreach() tofind all selected rows.

  • Returns: the selected row.

  • Since: 3.10

selected_foreach()

selected_foreach (self, func:Gtk.ListBoxForeachFunc, data=None)

Calls a function for each selected child. Note that the selection cannot be modified from within this function.

  • Since: 3.14

get_selected_rows()

get_selected_rows (self) -> list

Creates a list of all selected children.

  • Returns: A GList containing the Gtk.Widget for each selected child.Free with g_list_free() when done.

  • Since: 3.14

set_selection_mode()

set_selection_mode (self, mode:Gtk.SelectionMode)

Sets how selection works in the listbox.See Gtk.SelectionMode for details.

  • Since: 3.10

get_selection_mode()

get_selection_mode (self) -> Gtk.SelectionMode

Gets the selection mode of the listbox.

  • Returns: a Gtk.SelectionMode

  • Since: 3.10

set_activate_on_single_click()

set_activate_on_single_click (self, single:bool)

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

  • Since: 3.10

get_activate_on_single_click()

get_activate_on_single_click (self) -> bool

Returns whether rows activate on single clicks.

  • Returns: True if rows are activated on single click, FALSE otherwise

  • Since: 3.10

get_adjustment()

get_adjustment (self) -> Gtk.Adjustment

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

  • Returns: the adjustment.

  • Since: 3.10

set_adjustment()

set_adjustment (self, adjustment:Gtk.Adjustment=None)

Sets the adjustment (if any) that the widget uses tofor vertical scrolling. For instance, this is usedto get the page size for PageUp/Down key handling. In the normal case when the box is packed insidea Gtk.ScrolledWindow the adjustment from that willbe picked up automatically, so there is no needto manually do that.

  • Since: 3.10

set_placeholder()

set_placeholder (self, placeholder:Gtk.Widget=None)

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

  • Since: 3.10

get_row_at_index()

get_row_at_index (self, index_:int) -> Gtk.ListBoxRow or None

Gets the n-th child in the list (not counting headers).If _index is negative or larger than the number of items in thelist, None is returned.

  • Returns: the child Gtk.Widget or None.

  • Since: 3.10

get_row_at_y()

get_row_at_y (self, y:int) -> Gtk.ListBoxRow or None

Gets the row at the y position.

  • Returns: the row or Nonein case no row exists for the given y coordinate.

  • Since: 3.10

invalidate_filter()

invalidate_filter (self)

Update the filtering for all rows. Call this when resultof the filter function on the box is changed dueto an external factor. For instance, this would be usedif the filter function just looked for a specific searchstring and the entry with the search string has changed.

  • Since: 3.10

invalidate_headers()

invalidate_headers (self)

Update the separators for all rows. Call this when resultof the header function on the box is changed dueto an external factor.

  • Since: 3.10

invalidate_sort()

invalidate_sort (self)

Update the sorting for all rows. Call this when resultof the sort function on the box is changed dueto an external factor.

  • Since: 3.10

set_filter_func()

set_filter_func (self, filter_func:Gtk.ListBoxFilterFunc=None, user_data=None)

By setting a filter function on the box one can decide dynamically whichof the rows to show. For instance, to implement a search function on a list thatfilters the original list to only show the matching rows. The filter_func will be called for each row after the call, and it willcontinue to be called each time a row changes (via Gtk.ListBox:row_changed()) orwhen Gtk.ListBox:invalidate_filter() is called. Note that using a filter function is incompatible with using a model(see Gtk.ListBox:bind_model()).

  • Since: 3.10

set_header_func()

set_header_func (self, update_header:Gtk.ListBoxUpdateHeaderFunc=None, user_data=None)

By setting a header function on the box one can dynamically add headersin 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 anew kind, in a list sorted by the kind. The update_header can look at the current header widget using Gtk.ListBox:row_get_header()and either update the state of the widget as needed, or set a new one usingGtk.ListBox:row_set_header(). If no header is needed, set the header to 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 performanceto 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 willcontinue to be called each time a row changes (via Gtk.ListBox:row_changed()) and whenthe row before changes (either by Gtk.ListBox:row_changed() on the previous row, or whenthe previous row becomes a different row). It is also called for all rows whenGtk.ListBox:invalidate_headers() is called.

  • Since: 3.10

set_sort_func()

set_sort_func (self, sort_func:Gtk.ListBoxSortFunc=None, user_data=None)

By setting a sort function on the box one can dynamically reorder the rowsof the list, based on the contents of the rows. The sort_func will be called for each row after the call, and will continue tobe called each time a row changes (via Gtk.ListBox:row_changed()) and whenGtk.ListBox:invalidate_sort() is called. Note that using a sort function is incompatible with using a model(see Gtk.ListBox:bind_model()).

  • Since: 3.10

drag_highlight_row()

drag_highlight_row (self, row:Gtk.ListBoxRow)

This is a helper function for implementing DnD onto a Gtk.ListBox.The passed in row will be highlighted via `Gtk.Drag:highlight()`,and any previously highlighted row will be unhighlighted. The row will also be unhighlighted when the widget getsa drag leave event.

  • Since: 3.10

drag_unhighlight_row()

drag_unhighlight_row (self)

If a row has previously been highlighted via Gtk.ListBox:drag_highlight_row()it will have the highlight removed.

  • Since: 3.10

bind_model()

bind_model (self, model:Gio.ListModel=None, create_widget_func:Gtk.ListBoxCreateWidgetFunc=None, user_data=None)

Binds model to box. If box was already bound to a model, that previous binding isdestroyed. The contents of box are cleared and then filled with widgets thatrepresent items from model. box is updated whenever model changes.If model is None, box is left empty. It is undefined to add or remove widgets directly (for example, withGtk.ListBox:insert() or `Gtk.Container:add()) whileboxis bound to amodel. Note that using a model is incompatible with the filtering and sortingfunctionality inGtk.ListBox`. When using a model, filtering and sortingshould be implemented by the model.

  • Since: 3.16

Example:

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk

class ListBox(Gtk.Window):
    def __init__(self):
        Gtk.Window.__init__(self)
        self.set_default_size(200, -1)
        self.connect("destroy", Gtk.main_quit)

        listbox = Gtk.ListBox()

        self.add(listbox)

        for count in range(0, 9):
            label = Gtk.Label("Row %i" % (count))
            listbox.add(label)

        listbox.connect("row-activated", self.on_row_activated)

    def on_row_activated(self, listbox, listboxrow):
        print("Row %i activated" % (listboxrow.get_index()))

window = ListBox()
window.show_all()

Gtk.main()

results matching ""

    No results matching ""