Gtk.ListView¶

Subclasses:: None

Methods¶

Inherited:: Gtk.Widget (183), GObject.Object (37), Gtk.Accessible (17), Gtk.Buildable (1), Gtk.Orientable (2), Gtk.Scrollable (9)
Structs:: Gtk.WidgetClass (18), GObject.ObjectClass (5)

class	`new` (model, factory)
	`get_enable_rubberband` ()
	`get_factory` ()
	`get_header_factory` ()
	`get_model` ()
	`get_show_separators` ()
	`get_single_click_activate` ()
	`get_tab_behavior` ()
	`scroll_to` (pos, flags, scroll)
	`set_enable_rubberband` (enable_rubberband)
	`set_factory` (factory)
	`set_header_factory` (factory)
	`set_model` (model)
	`set_show_separators` (show_separators)
	`set_single_click_activate` (single_click_activate)
	`set_tab_behavior` (tab_behavior)

Virtual Methods¶

Inherited:: Gtk.Widget (25), GObject.Object (7), Gtk.Accessible (6), Gtk.Buildable (9), Gtk.Scrollable (1)

Properties¶

Inherited:: Gtk.Widget (35), Gtk.Accessible (1), Gtk.Orientable (1), Gtk.Scrollable (4)

Name	Type	Flags
`enable-rubberband`	`bool`	r/w/en
`factory`	`Gtk.ListItemFactory`	r/w/en
`header-factory`	`Gtk.ListItemFactory`	r/w/en
`model`	`Gtk.SelectionModel`	r/w/en
`show-separators`	`bool`	r/w/en
`single-click-activate`	`bool`	r/w/en
`tab-behavior`	`Gtk.ListTabBehavior`	r/w/en

Signals¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Name	Short Description
`activate`	Emitted when a row has been activated by the user.

Fields¶

Inherited:: Gtk.Widget (13), GObject.Object (1)

Class Details¶

class Gtk.ListView(**kwargs)¶

Bases:: Gtk.ListBase
Abstract:: No
Structure:: Gtk.ListViewClass

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 [property`Gtk`.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 [property`Gtk`.ListView:enable-rubberband].

If you need multiple columns with headers, see [class`Gtk`.ColumnView].

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

An example of using GtkListView : ```c static void setup_listitem_cb (Gtk.ListItemFactory *factory, Gtk.ListItem *list_item) { Gtk.Widget *image;

image = Gtk.Image.new (); Gtk.Image.set_icon_size (GTK_IMAGE (image), Gtk.IconSize.LARGE); Gtk.ListItem.set_child (list_item, image); }

static void bind_listitem_cb (Gtk.ListItemFactory *factory, Gtk.ListItem *list_item) { Gtk.Widget *image; Gio.AppInfo *app_info;

image = Gtk.ListItem.get_child (list_item); app_info = Gtk.ListItem.get_item (list_item); Gtk.Image.set_from_gicon (GTK_IMAGE (image), Gio.AppInfo.get_icon (app_info)); }

static void activate_cb (Gtk.ListView *list, int position, object unused) { Gio.AppInfo *app_info;

app_info = Gio.ListModel.get_item (G_LIST_MODEL (Gtk.ListView.get_model (list)), position); Gio.AppInfo.launch (app_info, None, None, None); GObject.Object.unref (app_info); }

…

model = create_application_list ();

factory = Gtk.SignalListItemFactory.new (); g_signal_connect (factory, “setup”, G_CALLBACK (setup_listitem_cb), None); g_signal_connect (factory, “bind”, G_CALLBACK (bind_listitem_cb), None);

list = Gtk.ListView.new (GTK_SELECTION_MODEL (Gtk.SingleSelection.new (model)), factory);

g_signal_connect (list, “activate”, G_CALLBACK (activate_cb), None);

Gtk.ScrolledWindow.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 [signal`Gtk`.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 [property`Gtk`.ListView:show-separators] property is set. Each child widget uses a single CSS node named row. If the [property`Gtk`.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 [enum`Gtk`.AccessibleRole.list] role, and the list items use the [enum`Gtk`.AccessibleRole.list_item] role.

classmethod new(model, factory)[source]¶

Parameters:

model (Gtk.SelectionModel or None) – the model to use
factory (Gtk.ListItemFactory or None) – The factory to populate items with

Returns:

a new GtkListView using the given model and factory

Return type:

Gtk.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 ``c list_view = gtk_list_view_new (create_model (),

gtk_builder_list_item_factory_new_from_resource (“/resource.ui”));

``

get_enable_rubberband()[source]¶

Returns:: true if rubberband selection is enabled
Return type:: bool

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

get_factory()[source]¶

Returns:: The factory in use
Return type:: Gtk.ListItemFactory or None

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

get_header_factory()[source]¶

Returns:: The factory in use
Return type:: Gtk.ListItemFactory or None

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

New in version 4.12.

get_model()[source]¶

Returns:: The model in use
Return type:: Gtk.SelectionModel or None

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

get_show_separators()[source]¶

Returns:: true if the listview shows separators
Return type:: bool

Returns whether the listview should show separators between rows.

get_single_click_activate()[source]¶

Returns:: true if rows are activated on single click
Return type:: bool

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

get_tab_behavior()[source]¶

Returns:: The behavior of the <kbd>Tab</kbd> key
Return type:: Gtk.ListTabBehavior

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

New in version 4.12.

scroll_to(pos, flags, scroll)[source]¶

Parameters:

pos (int) – position of the item. Must be less than the number of items in the view.
flags (Gtk.ListScrollFlags) – actions to perform
scroll (Gtk.ScrollInfo or None) – details of how to perform the scroll operation or None to scroll into view

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.

New in version 4.12.

set_enable_rubberband(enable_rubberband)[source]¶

Parameters:: enable_rubberband (bool) – whether to enable rubberband selection

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

set_factory(factory)[source]¶

Parameters:: factory (Gtk.ListItemFactory or None) – the factory to use

Sets the GtkListItemFactory to use for populating list items.

set_header_factory(factory)[source]¶

Parameters:: factory (Gtk.ListItemFactory or None) – the factory to use

Sets the GtkListItemFactory to use for populating the [class`Gtk`.ListHeader] objects used in section headers.

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

New in version 4.12.

set_model(model)[source]¶

Parameters:: model (Gtk.SelectionModel or None) – the model to use

Sets the model to use.

This must be a [iface`Gtk`.SelectionModel] to use.

set_show_separators(show_separators)[source]¶

Parameters:: show_separators (bool) – whether to show separators

Sets whether the listview should show separators between rows.

set_single_click_activate(single_click_activate)[source]¶

Parameters:: single_click_activate (bool) – whether to activate items on single click

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

set_tab_behavior(tab_behavior)[source]¶

Parameters:: tab_behavior (Gtk.ListTabBehavior) – The desired tab behavior

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.

New in version 4.12.

Signal Details¶

Gtk.ListView.signals.activate(list_view, position)¶

Signal Name:

activate

Flags:

RUN_LAST

Parameters:

list_view (Gtk.ListView) – The object which received the signal
position (int) – position of item to activate

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 [method`Gtk`.ListItem.set_activatable] for details on how to use this signal.

Property Details¶

Gtk.ListView.props.enable_rubberband¶

Name:: enable-rubberband
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Allow rubberband selection.

Gtk.ListView.props.factory¶

Name:: factory
Type:: Gtk.ListItemFactory
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Factory for populating list items.

The factory must be for configuring [class`Gtk`.ListItem] objects.

Gtk.ListView.props.header_factory¶

Name:: header-factory
Type:: Gtk.ListItemFactory
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Factory for creating header widgets.

The factory must be for configuring [class`Gtk`.ListHeader] objects.

New in version 4.12.

Gtk.ListView.props.model¶

Name:: model
Type:: Gtk.SelectionModel
Default Value:: None
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Model for the items displayed.

Gtk.ListView.props.show_separators¶

Name:: show-separators
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Show separators between rows.

Gtk.ListView.props.single_click_activate¶

Name:: single-click-activate
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

Activate rows on single click and select them on hover.

Gtk.ListView.props.tab_behavior¶

Name:: tab-behavior
Type:: Gtk.ListTabBehavior
Default Value:: Gtk.ListTabBehavior.ALL
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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

New in version 4.12.