Gtk.ListItem¶

class — extends GObject.Object

Used by list widgets to represent items in a Gio.ListModel.

GtkListItem objects are managed by the list widget (with its factory) and cannot be created by applications, but they need to be populated by application code. This is done by calling ListItem.set_child.

GtkListItem objects exist in 2 stages:

The unbound stage where the listitem is not currently connected to an item in the list. In that case, the ListItem.item property is set to NULL.
The bound stage where the listitem references an item from the list. The ListItem.item property is not NULL.

Methods¶

get_accessible_description¶

def get_accessible_description(self) -> str

Gets the accessible description of self.

get_accessible_label¶

def get_accessible_label(self) -> str

Gets the accessible label of self.

get_activatable¶

def get_activatable(self) -> bool

Checks if a listitem has been set to be activatable via ListItem.set_activatable.

get_child¶

def get_child(self) -> Widget | None

Gets the child previously set via ListItem.set_child or NULL if none was set.

get_focusable¶

def get_focusable(self) -> bool

Checks if a listitem has been set to be focusable via ListItem.set_focusable.

get_item¶

def get_item(self) -> GObject.Object | None

Gets the model item that associated with self.

If self is unbound, this function returns NULL.

get_position¶

def get_position(self) -> int

Gets the position in the model that self currently displays.

If self is unbound, GTK_INVALID_LIST_POSITION is returned.

get_selectable¶

def get_selectable(self) -> bool

Checks if a listitem has been set to be selectable via ListItem.set_selectable.

Do not confuse this function with ListItem.get_selected.

get_selected¶

def get_selected(self) -> bool

Checks if the item is displayed as selected.

The selected state is maintained by the list widget and its model and cannot be set otherwise.

set_accessible_description¶

def set_accessible_description(self, description: str) -> None

Sets the accessible description for the listitem.

The accessible description may be used by e.g. screen readers.

Parameters:

description — the description

set_accessible_label¶

def set_accessible_label(self, label: str) -> None

Sets the accessible label for the listitem.

The accessible label may be used by e.g. screen readers.

Parameters:

label — the label

set_activatable¶

def set_activatable(self, activatable: bool) -> None

Sets self to be activatable.

If an item is activatable, double-clicking on the item, using the Return key or calling Widget.activate will activate the item. Activating instructs the containing view to handle activation. GtkListView for example will be emitting the ListView.activate signal.

By default, listitems are activatable.

Parameters:

activatable — if the item should be activatable

set_child¶

def set_child(self, child: Widget | None = ...) -> None

Sets the child to be used for this listitem.

This function is typically called by applications when setting up a listitem so that the widget can be reused when binding it multiple times.

Parameters:

child — The listitem's child or NULL to unset

set_focusable¶

def set_focusable(self, focusable: bool) -> None

Sets self to be focusable.

If an item is focusable, it can be focused using the keyboard. This works similar to Widget.set_focusable.

Note that if items are not focusable, the keyboard cannot be used to activate them and selecting only works if one of the listitem's children is focusable.

By default, listitems are focusable.

Parameters:

focusable — if the item should be focusable

set_selectable¶

def set_selectable(self, selectable: bool) -> None

Sets self to be selectable.

If an item is selectable, clicking on the item or using the keyboard will try to select or unselect the item. If this succeeds is up to the model to determine, as it is managing the selected state.

Note that this means that making an item non-selectable has no influence on the selected state at all. A non-selectable item may still be selected.

By default, listitems are selectable. When rebinding them to a new item, they will also be reset to be selectable by GTK.

Parameters:

selectable — if the item should be selectable

Properties¶

accessible_description¶

accessible_description: str  # read/write

The accessible description to set on the listitem.

accessible_label¶

accessible_label: str  # read/write

The accessible label to set on the listitem.

activatable¶

activatable: bool  # read/write

If the item can be activated by the user.

child¶

child: Widget  # read/write

Widget used for display.

focusable¶

focusable: bool  # read/write

If the item can be focused with the keyboard.

item¶

item: GObject.Object  # read-only

Displayed item.

position¶

position: int  # read-only

Position of the item.

selectable¶

selectable: bool  # read/write

If the item can be selected by the user.

selected¶

selected: bool  # read-only

If the item is currently selected.