ListView
Superclasses: ListBase
, Widget
, InitiallyUnowned
, Object
Implemented Interfaces: Accessible
, Buildable
, ConstraintTarget
, Orientable
, Scrollable
GtkListView
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 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
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);
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 show_separators
property is set. Each child widget uses a single CSS node named row
.
If the 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 LIST
role, and the list
items use the LIST_ITEM
role.
Constructors
- class ListView
- classmethod new(model: SelectionModel | None = None, factory: ListItemFactory | None = None) Widget
Creates a new
GtkListView
that uses the givenfactory
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
- class ListView
-
- get_factory() ListItemFactory | None
Gets the factory that’s currently used to populate list items.
- get_header_factory() ListItemFactory | None
Gets the factory that’s currently used to populate section headers.
Added in version 4.12.
- get_model() SelectionModel | None
Gets the model that’s currently used to read the items displayed.
- get_single_click_activate() bool
Returns whether rows will be activated on single click and selected on hover.
- get_tab_behavior() ListTabBehavior
Gets the behavior set for the Tab key.
Added in version 4.12.
- scroll_to(pos: int, flags: ListScrollFlags, scroll: ScrollInfo | None = 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.
Added in version 4.12.
- Parameters:
pos – position of the item
flags – actions to perform
scroll – details of how to perform the scroll operation or
None
to scroll into view
- set_enable_rubberband(enable_rubberband: bool) None
Sets whether selections can be changed by dragging with the mouse.
- Parameters:
enable_rubberband –
True
to enable rubberband selection
- set_factory(factory: ListItemFactory | None = None) None
Sets the
GtkListItemFactory
to use for populating list items.- Parameters:
factory – the factory to use
- set_header_factory(factory: ListItemFactory | None = None) None
Sets the
GtkListItemFactory
to use for populating theListHeader
objects used in section headers.If this factory is set to
None
, the list will not show section headers.Added in version 4.12.
- Parameters:
factory – the factory to use
- set_model(model: SelectionModel | None = None) None
Sets the model to use.
This must be a
SelectionModel
to use.- Parameters:
model – the model to use
- set_show_separators(show_separators: bool) None
Sets whether the list box should show separators between rows.
- Parameters:
show_separators –
True
to show separators
- set_single_click_activate(single_click_activate: bool) None
Sets whether rows should be activated on single click and selected on hover.
- Parameters:
single_click_activate –
True
to activate items on single click
- set_tab_behavior(tab_behavior: ListTabBehavior) None
Sets the behavior of the Tab and Shift`+:kbd:`Tab keys.
Added in version 4.12.
- Parameters:
tab_behavior – The desired tab behavior
Properties
- class ListView
-
- props.factory: ListItemFactory
Factory for populating list items.
- props.header_factory: ListItemFactory
Factory for creating header widgets.
Added in version 4.12.
- props.model: SelectionModel
Model for the items displayed.
- props.tab_behavior: ListTabBehavior
Behavior of the Tab key
Added in version 4.12.
Signals
- class ListView.signals
- activate(position: int) None
Emitted when a row has been activated by the user, usually via activating the GtkListView|list.activate-item action.
This allows for a convenient way to handle activation in a listview. See
set_activatable
for details on how to use this signal.- Parameters:
position – position of item to activate