ListStore

class ListStore(**properties: Any)

Superclasses: Object

Implemented Interfaces: ListModel

GListStore is a simple implementation of ListModel that stores all items in memory.

It provides insertions, deletions, and lookups in logarithmic time with a fast path for the common case of iterating the list linearly.

Constructors

class ListStore
classmethod new(item_type: type) → ListStore

Creates a new ListStore with items of type item_type. item_type must be a subclass of Object.

Added in version 2.44.

Parameters:

item_type – the Type of items in the list

Methods

class ListStore
append(item: Object) → None

Appends item to store. item must be of type ListStore:item-type.

This function takes a ref on item.

Use splice() to append multiple items at the same time efficiently.

Added in version 2.44.

Parameters:

item – the new item

find(item: Object) → tuple[bool, int]

Looks up the given item in the list store by looping over the items until the first occurrence of item. If item was not found, then position will not be set, and this method will return False.

If you need to compare the two items with a custom comparison function, use find_with_equal_func() with a custom EqualFunc instead.

Added in version 2.64.

Parameters:

item – an item

find_with_equal_func(item: Object | None, equal_func: Callable[[None, None], bool]) → tuple[bool, int]

Looks up the given item in the list store by looping over the items and comparing them with equal_func until the first occurrence of item which matches. If item was not found, then position will not be set, and this method will return False.

item is always passed as second parameter to equal_func.

Since GLib 2.76 it is possible to pass NULL for item.

Added in version 2.64.

Parameters:

  • item – an item

  • equal_func – A custom equality check function

find_with_equal_func_full(item: Object | None, equal_func: Callable[[...], bool], *user_data: Any) → tuple[bool, int]

Like find_with_equal_func() but with an additional user_data that is passed to equal_func.

item is always passed as second parameter to equal_func.

Since GLib 2.76 it is possible to pass NULL for item.

Added in version 2.74.

Parameters:

  • item – an item

  • equal_func – A custom equality check function

  • user_data – user data for equal_func

insert(position: int, item: Object) → None

Inserts item into store at position. item must be of type ListStore:item-type or derived from it. position must be smaller than the length of the list, or equal to it to append.

This function takes a ref on item.

Use splice() to insert multiple items at the same time efficiently.

Added in version 2.44.

Parameters:

  • position – the position at which to insert the new item

  • item – the new item

insert_sorted(item, compare_func, *user_data)

Inserts item into store at a position to be determined by the compare_func.

The list must already be sorted before calling this function or the result is undefined. Usually you would approach this by only ever inserting items by way of this function.

This function takes a ref on item.

Added in version 2.44.

Parameters:

  • item – the new item

  • compare_func – pairwise comparison function for sorting

  • user_data – user data for compare_func

remove(position: int) → None

Removes the item from store that is at position. position must be smaller than the current length of the list.

Use splice() to remove multiple items at the same time efficiently.

Added in version 2.44.

Parameters:

position – the position of the item that is to be removed

remove_all() → None

Removes all items from store.

Added in version 2.44.

sort(compare_func, *user_data)

Sort the items in store according to compare_func.

Added in version 2.46.

Parameters:

  • compare_func – pairwise comparison function for sorting

  • user_data – user data for compare_func

splice(position: int, n_removals: int, additions: Sequence[Object]) → None

Changes store by removing n_removals items and adding n_additions items to it. additions must contain n_additions items of type ListStore:item-type. None is not permitted.

This function is more efficient than insert() and remove(), because it only emits ListModel::items-changed once for the change.

This function takes a ref on each item in additions.

The parameters position and n_removals must be correct (ie: position + n_removals must be less than or equal to the length of the list at the time this function is called).

Added in version 2.44.

Parameters:

  • position – the position at which to make the change

  • n_removals – the number of items to remove

  • additions – the items to add

Properties

class ListStore
props.item_type: type

The type of items contained in this list store. Items must be subclasses of Object.

Added in version 2.44.

props.n_items: int

The number of items contained in this list store.

Added in version 2.74.