ListItem

class ListItem(**properties: Any)

Superclasses: Object

Subclasses: ColumnViewCell

GtkListItem is used by list widgets to represent items in a 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 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 item property is set to None.
The bound stage where the listitem references an item from the list. The item property is not None.

Methods

class ListItem

get_accessible_description() → str: Gets the accessible description of self.

Added in version 4.12.

get_accessible_label() → str: Gets the accessible label of self.

Added in version 4.12.

get_activatable() → bool: Checks if a list item has been set to be activatable via set_activatable().

get_child() → Widget | None: Gets the child previously set via set_child() or None if none was set.

get_focusable() → bool: Checks if a list item has been set to be focusable via set_focusable().

Added in version 4.12.

get_item() → Object | None

Gets the model item that associated with self.

If self is unbound, this function returns None.

get_position() → int

Gets the position in the model that self currently displays.

If self is unbound, INVALID_LIST_POSITION is returned.

get_selectable() → bool

Checks if a list item has been set to be selectable via set_selectable().

Do not confuse this function with get_selected.

get_selected() → bool

Checks if the item is displayed as selected.

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

set_accessible_description(description: str) → None

Sets the accessible description for the list item, which may be used by e.g. screen readers.

Added in version 4.12.

Parameters:: description – the description

set_accessible_label(label: str) → None

Sets the accessible label for the list item, which may be used by e.g. screen readers.

Added in version 4.12.

Parameters:: label – the label

set_activatable(activatable: bool) → None

Sets self to be activatable.

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

By default, list items are activatable.

Parameters:: activatable – if the item should be activatable

set_child(child: Widget | None = 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 list item’s child or None to unset

set_focusable(focusable: bool) → None

Sets self to be focusable.

If an item is focusable, it can be focused using the keyboard. This works similar to 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, list items are focusable.

Added in version 4.12.

Parameters:: focusable – if the item should be focusable

set_selectable(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, list items 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

class ListItem

props.accessible_description: str: The accessible description to set on the list item.

Added in version 4.12.

props.accessible_label: str: The accessible label to set on the list item.

Added in version 4.12.

props.activatable: bool: If the item can be activated by the user.

props.child: Widget: Widget used for display.

props.focusable: bool: If the item can be focused with the keyboard.

Added in version 4.12.

props.item: Object: Displayed item.

props.position: int: Position of the item.

props.selectable: bool: If the item can be selected by the user.

props.selected: bool: If the item is currently selected.