Gtk.ListView¶

class — extends ListBase, Accessible, Buildable, ConstraintTarget, Orientable, Scrollable

Presents a large dynamic list of items.

GtkListView uses its factory to generate one row widget for each visible item and shows them in a linear display, either vertically or horizontally.

The ListView.show-separators property offers a simple way to display separators between the rows.

GtkListView allows the user to select items according to the selection characteristics of the model. For models that allow multiple selected items, it is possible to turn on rubberband selection, using ListView.enable-rubberband.

If you need multiple columns with headers, see ColumnView.

To learn more about the list widget framework, see the overview.

An example of using GtkListView:

static void
setup_listitem_cb (GtkListItemFactory *factory,
                   GtkListItem        *list_item)
{
  GtkWidget *image;

  image = gtk_image_new ();
  gtk_image_set_icon_size (GTK_IMAGE (image), GTK_ICON_SIZE_LARGE);
  gtk_list_item_set_child (list_item, image);
}

static void
bind_listitem_cb (GtkListItemFactory *factory,
                  GtkListItem        *list_item)
{
  GtkWidget *image;
  GAppInfo *app_info;

  image = gtk_list_item_get_child (list_item);
  app_info = gtk_list_item_get_item (list_item);
  gtk_image_set_from_gicon (GTK_IMAGE (image), g_app_info_get_icon (app_info));
}

static void
activate_cb (GtkListView  *list,
             guint         position,
             gpointer      unused)
{
  GAppInfo *app_info;

  app_info = g_list_model_get_item (G_LIST_MODEL (gtk_list_view_get_model (list)), position);
  g_app_info_launch (app_info, NULL, NULL, NULL);
  g_object_unref (app_info);
}

...

  model = create_application_list ();

  factory = gtk_signal_list_item_factory_new ();
  g_signal_connect (factory, "setup", G_CALLBACK (setup_listitem_cb), NULL);
  g_signal_connect (factory, "bind", G_CALLBACK (bind_listitem_cb), NULL);

  list = gtk_list_view_new (GTK_SELECTION_MODEL (gtk_single_selection_new (model)), factory);

  g_signal_connect (list, "activate", G_CALLBACK (activate_cb), NULL);

  gtk_scrolled_window_set_child (GTK_SCROLLED_WINDOW (sw), list);

Actions¶

GtkListView defines a set of built-in actions:

list.activate-item activates the item at given position by emitting the ListView.activate signal.

CSS nodes¶

listview[.separators][.rich-list][.navigation-sidebar][.data-table]
├── row[.activatable]
│
├── row[.activatable]
│
┊
╰── [rubberband]

GtkListView uses a single CSS node named listview. It may carry the .separators style class, when ListView.show-separators property is set. Each child widget uses a single CSS node named row. If the ListItem.activatable property is set, the corresponding row will have the .activatable style class. For rubberband selection, a node with name rubberband is used.

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

Accessibility¶

GtkListView uses the AccessibleRole.list role, and the list items use the AccessibleRole.list_item role.

Constructors¶

new¶

@classmethod
def new(cls, model: SelectionModel | None = ..., factory: ListItemFactory | None = ...) -> Widget

Creates a new GtkListView that uses the given factory for mapping items to widgets.

The function takes ownership of the arguments, so you can write code like

list_view = gtk_list_view_new (create_model (),
  gtk_builder_list_item_factory_new_from_resource ("/resource.ui"));

Parameters:

model — the model to use
factory — The factory to populate items with

Methods¶

get_enable_rubberband¶

def get_enable_rubberband(self) -> bool

Returns whether rows can be selected by dragging with the mouse.

get_factory¶

def get_factory(self) -> ListItemFactory | None

Gets the factory that's currently used to populate list items.

get_header_factory¶

def get_header_factory(self) -> ListItemFactory | None

Gets the factory that's currently used to populate section headers.

get_model¶

def get_model(self) -> SelectionModel | None

Gets the model that's currently used to read the items displayed.

get_show_separators¶

def get_show_separators(self) -> bool

Returns whether the listview should show separators between rows.

get_single_click_activate¶

def get_single_click_activate(self) -> bool

Returns whether rows will be activated on single click and selected on hover.

get_tab_behavior¶

def get_tab_behavior(self) -> ListTabBehavior

Gets the behavior set for the <kbd>Tab</kbd> key.

scroll_to¶

def scroll_to(self, pos: int, flags: ListScrollFlags | int, scroll: ScrollInfo | None = ...) -> None

Scrolls to the item at the given position and performs the actions specified in flags.

This function works no matter if the listview is shown or focused. If it isn't, then the changes will take effect once that happens.

Parameters:

pos — position of the item. Must be less than the number of items in the view.
flags — actions to perform
scroll — details of how to perform the scroll operation or None to scroll into view

set_enable_rubberband¶

def set_enable_rubberband(self, enable_rubberband: bool) -> None

Sets whether selections can be changed by dragging with the mouse.

Parameters:

enable_rubberband — whether to enable rubberband selection

set_factory¶

def set_factory(self, factory: ListItemFactory | None = ...) -> None

Sets the GtkListItemFactory to use for populating list items.

Parameters:

factory — the factory to use

set_header_factory¶

def set_header_factory(self, factory: ListItemFactory | None = ...) -> None

Sets the GtkListItemFactory to use for populating the ListHeader objects used in section headers.

If this factory is set to NULL, the list will not show section headers.

Parameters:

factory — the factory to use

set_model¶

def set_model(self, model: SelectionModel | None = ...) -> None

Sets the model to use.

This must be a SelectionModel to use.

Parameters:

model — the model to use

set_show_separators¶

def set_show_separators(self, show_separators: bool) -> None

Sets whether the listview should show separators between rows.

Parameters:

show_separators — whether to show separators

set_single_click_activate¶

def set_single_click_activate(self, single_click_activate: bool) -> None

Sets whether rows should be activated on single click and selected on hover.

Parameters:

single_click_activate — whether to activate items on single click

set_tab_behavior¶

def set_tab_behavior(self, tab_behavior: ListTabBehavior | int) -> None

Sets the <kbd>Tab</kbd> key behavior.

This influences how the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys move the focus in the listview.

Parameters:

tab_behavior — The desired tab behavior

Properties¶

enable_rubberband¶

enable_rubberband: bool  # read/write

Allow rubberband selection.

factory¶

factory: ListItemFactory  # read/write

Factory for populating list items.

The factory must be for configuring ListItem objects.

header_factory¶

header_factory: ListItemFactory  # read/write

Factory for creating header widgets.

The factory must be for configuring ListHeader objects.

model¶

model: SelectionModel  # read/write

Model for the items displayed.

show_separators¶

show_separators: bool  # read/write

Show separators between rows.

single_click_activate¶

single_click_activate: bool  # read/write

Activate rows on single click and select them on hover.

tab_behavior¶

tab_behavior: ListTabBehavior | int  # read/write

Behavior of the <kbd>Tab</kbd> key

Signals¶

activate¶

def on_activate(self, position: int) -> None: ...

Emitted when a row has been activated by the user.

Activation usually happens via the list.activate-item action of the GtkListView.

This allows for a convenient way to handle activation in a listview. See ListItem.set_activatable for details on how to use this signal.