:right-sidebar: True ListStore =================================================================== .. currentmodule:: gi.repository.Gio .. class:: ListStore(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gio.ListModel` ``GListStore`` is a simple implementation of :obj:`~gi.repository.Gio.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 ------------ .. rst-class:: interim-class .. class:: ListStore :no-index: .. classmethod:: new(item_type: type) -> ~gi.repository.Gio.ListStore Creates a new :obj:`~gi.repository.Gio.ListStore` with items of type ``item_type``. ``item_type`` must be a subclass of :obj:`~gi.repository.GObject.Object`. .. versionadded:: 2.44 :param item_type: the :obj:`~gi.repository.GObject.Type` of items in the list Methods ------- .. rst-class:: interim-class .. class:: ListStore :no-index: .. method:: append(item: ~gi.repository.GObject.Object) -> None Appends ``item`` to ``store``. ``item`` must be of type :obj:`~gi.repository.Gio.ListStore`:item-type. This function takes a ref on ``item``. Use :func:`~gi.repository.Gio.ListStore.splice` to append multiple items at the same time efficiently. .. versionadded:: 2.44 :param item: the new item .. method:: find(item: ~gi.repository.GObject.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 :const:`False`. If you need to compare the two items with a custom comparison function, use :func:`~gi.repository.Gio.ListStore.find_with_equal_func` with a custom :obj:`~gi.repository.GLib.EqualFunc` instead. .. versionadded:: 2.64 :param item: an item .. method:: find_with_equal_func(item: ~gi.repository.GObject.Object | None, equal_func: ~typing.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 :const:`False`. ``item`` is always passed as second parameter to ``equal_func``. Since GLib 2.76 it is possible to pass ``NULL`` for ``item``. .. versionadded:: 2.64 :param item: an item :param equal_func: A custom equality check function .. method:: find_with_equal_func_full(item: ~gi.repository.GObject.Object | None, equal_func: ~typing.Callable[[...], bool], *user_data: ~typing.Any) -> tuple[bool, int] Like :func:`~gi.repository.Gio.ListStore.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``. .. versionadded:: 2.74 :param item: an item :param equal_func: A custom equality check function :param user_data: user data for ``equal_func`` .. method:: insert(position: int, item: ~gi.repository.GObject.Object) -> None Inserts ``item`` into ``store`` at ``position``. ``item`` must be of type :obj:`~gi.repository.Gio.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 :func:`~gi.repository.Gio.ListStore.splice` to insert multiple items at the same time efficiently. .. versionadded:: 2.44 :param position: the position at which to insert the new item :param item: the new item .. method:: 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``. .. versionadded:: 2.44 :param item: the new item :param compare_func: pairwise comparison function for sorting :param user_data: user data for ``compare_func`` .. method:: 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 :func:`~gi.repository.Gio.ListStore.splice` to remove multiple items at the same time efficiently. .. versionadded:: 2.44 :param position: the position of the item that is to be removed .. method:: remove_all() -> None Removes all items from ``store``. .. versionadded:: 2.44 .. method:: sort(compare_func, *user_data) Sort the items in ``store`` according to ``compare_func``. .. versionadded:: 2.46 :param compare_func: pairwise comparison function for sorting :param user_data: user data for ``compare_func`` .. method:: splice(position: int, n_removals: int, additions: ~typing.Sequence[~gi.repository.GObject.Object]) -> None Changes ``store`` by removing ``n_removals`` items and adding ``n_additions`` items to it. ``additions`` must contain ``n_additions`` items of type :obj:`~gi.repository.Gio.ListStore`:item-type. :const:`None` is not permitted. This function is more efficient than :func:`~gi.repository.Gio.ListStore.insert` and :func:`~gi.repository.Gio.ListStore.remove`, because it only emits :obj:`~gi.repository.Gio.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). .. versionadded:: 2.44 :param position: the position at which to make the change :param n_removals: the number of items to remove :param additions: the items to add Properties ---------- .. rst-class:: interim-class .. class:: ListStore :no-index: .. attribute:: props.item_type :type: type The type of items contained in this list store. Items must be subclasses of :obj:`~gi.repository.GObject.Object`. .. versionadded:: 2.44 .. attribute:: props.n_items :type: int The number of items contained in this list store. .. versionadded:: 2.74