:right-sidebar: True

ListStore
===================================================================

.. currentmodule:: gi.repository.Gtk





.. deprecated:: 4.10

   Use :obj:`~gi.repository.Gio.ListStore` instead



.. class:: ListStore(*column_types)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.GObject.Object`



Implemented Interfaces: :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.TreeDragDest`, :class:`~gi.repository.Gtk.TreeDragSource`, :class:`~gi.repository.Gtk.TreeModel`, :class:`~gi.repository.Gtk.TreeSortable`



:Constructors:

::

    ListStore(**properties)
    new(types:list) -> Gtk.ListStore



Constructors
------------

.. rst-class:: interim-class

.. class:: ListStore
   :no-index:


   .. classmethod:: new(types: ~typing.Sequence[type]) -> ~gi.repository.Gtk.ListStore

      Creates a new list store.

      The list store will have ``n_columns`` columns, with each column using
      the given type passed to this function.


      Note that only types derived from standard GObject fundamental types
      are supported.

      As an example:


      .. code-block:: c
         :dedent:

         gtk_list_store_new (3, G_TYPE_INT, G_TYPE_STRING, GDK_TYPE_TEXTURE);


      will create a new ``GtkListStore`` with three columns, of type ``int``,
      ``gchararray`` and ``GdkTexture``, respectively.






      .. deprecated:: 4.10

         Use :obj:`~gi.repository.Gio.ListStore` instead




      :param types: 








Methods
-------

.. rst-class:: interim-class

.. class:: ListStore
   :no-index:


   .. method:: append(row=None)

      Appends a new row to ``list_store``.  ``iter`` will be changed to point to this new
      row.  The row will be empty after this function is called.  To fill in
      values, you need to call :func:`~gi.repository.Gtk.ListStore.set` or :func:`~gi.repository.Gtk.ListStore.set_value`.






      .. deprecated:: 4.10

         Use list models




      :param row: 




   .. method:: clear() -> None

      Removes all rows from the list store.






      .. deprecated:: 4.10

         Use list models







   .. method:: insert(position, row=None)

      Creates a new row at ``position``.  ``iter`` will be changed to point to this new
      row.  If ``position`` is -1 or is larger than the number of rows on the list,
      then the new row will be appended to the list. The row will be empty after
      this function is called.  To fill in values, you need to call
      :func:`~gi.repository.Gtk.ListStore.set` or :func:`~gi.repository.Gtk.ListStore.set_value`.






      .. deprecated:: 4.10

         Use list models




      :param position: position to insert the new row, or -1 for last


      :param row: 




   .. method:: insert_after(sibling, row=None)

      Inserts a new row after ``sibling``. If ``sibling`` is :const:`None`, then the row will be
      prepended to the beginning of the list. ``iter`` will be changed to point to
      this new row. The row will be empty after this function is called. To fill
      in values, you need to call :func:`~gi.repository.Gtk.ListStore.set` or :func:`~gi.repository.Gtk.ListStore.set_value`.






      .. deprecated:: 4.10

         Use list models




      :param sibling: A valid ``GtkTreeIter``


      :param row: 




   .. method:: insert_before(sibling, row=None)

      Inserts a new row before ``sibling``. If ``sibling`` is :const:`None`, then the row will
      be appended to the end of the list. ``iter`` will be changed to point to this
      new row. The row will be empty after this function is called. To fill in
      values, you need to call :func:`~gi.repository.Gtk.ListStore.set` or :func:`~gi.repository.Gtk.ListStore.set_value`.






      .. deprecated:: 4.10

         Use list models




      :param sibling: A valid ``GtkTreeIter``


      :param row: 




   .. method:: insert_with_values(position: int, columns: ~typing.Sequence[int], values: ~typing.Sequence[~typing.Any]) -> ~gi.repository.Gtk.TreeIter

      Creates a new row at ``position``. ``iter`` will be changed to point to this new
      row. If ``position`` is -1, or larger than the number of rows in the list, then
      the new row will be appended to the list. The row will be filled with the
      values given to this function.

      Calling
      `gtk_list_store_insert_with_values (list_store, iter, position...)`
      has the same effect as calling:


      .. code-block:: C
         :dedent:

         static void
         insert_value (GtkListStore *list_store,
                       GtkTreeIter  *iter,
                       int           position)
         {
           gtk_list_store_insert (list_store, iter, position);
           gtk_list_store_set (list_store,
                               iter
                               // ...
                               );
         }


      with the difference that the former will only emit ``GtkTreeModel``::row-inserted
      once, while the latter will emit ``GtkTreeModel``::row-inserted,
      ``GtkTreeModel``::row-changed and, if the list store is sorted,
      ``GtkTreeModel``::rows-reordered for every inserted value.

      Since emitting the ``GtkTreeModel::rows-reordered`` signal repeatedly can
      affect the performance of the program, :func:`~gi.repository.Gtk.ListStore.insert_with_values`
      should generally be preferred when inserting rows in a sorted list store.






      .. deprecated:: 4.10

         Use list models




      :param position: position to insert the new row, or -1 to append after existing
         rows


      :param columns: 

      :param values: 




   .. method:: insert_with_valuesv(position: int, columns: ~typing.Sequence[int], values: ~typing.Sequence[~typing.Any]) -> ~gi.repository.Gtk.TreeIter

      A variant of :func:`~gi.repository.Gtk.ListStore.insert_with_values` which
      takes the columns and values as two arrays, instead of
      varargs.

      This function is mainly intended for language-bindings.






      .. deprecated:: 4.10

         Use list models




      :param position: position to insert the new row, or -1 for last


      :param columns: an array of column numbers


      :param values: an array of GValues





   .. method:: iter_is_valid(iter: ~gi.repository.Gtk.TreeIter) -> bool

      Checks if the given iter is a valid iter for this ``GtkListStore``.

      This function is slow. Only use it for debugging and/or testing
      purposes.






      .. deprecated:: 4.10

         Use list models




      :param iter: the iterator to check





   .. method:: move_after(iter: ~gi.repository.Gtk.TreeIter, position: ~gi.repository.Gtk.TreeIter | None = None) -> None

      Moves ``iter`` in ``store`` to the position after ``position``. Note that this
      function only works with unsorted stores. If ``position`` is :const:`None`, ``iter``
      will be moved to the start of the list.






      .. deprecated:: 4.10

         Use list models




      :param iter: A ``GtkTreeIter``


      :param position: A ``GtkTreeIter``





   .. method:: move_before(iter: ~gi.repository.Gtk.TreeIter, position: ~gi.repository.Gtk.TreeIter | None = None) -> None

      Moves ``iter`` in ``store`` to the position before ``position``. Note that this
      function only works with unsorted stores. If ``position`` is :const:`None`, ``iter``
      will be moved to the end of the list.






      .. deprecated:: 4.10

         Use list models




      :param iter: A ``GtkTreeIter``


      :param position: A ``GtkTreeIter``





   .. method:: prepend(row=None)

      Prepends a new row to ``list_store``. ``iter`` will be changed to point to this new
      row. The row will be empty after this function is called. To fill in
      values, you need to call :func:`~gi.repository.Gtk.ListStore.set` or :func:`~gi.repository.Gtk.ListStore.set_value`.






      .. deprecated:: 4.10

         Use list models




      :param row: 




   .. method:: remove(iter: ~gi.repository.Gtk.TreeIter) -> bool

      Removes the given row from the list store.  After being removed,
      ``iter`` is set to be the next valid row, or invalidated if it pointed
      to the last row in ``list_store``.






      .. deprecated:: 4.10

         Use list models




      :param iter: A valid ``GtkTreeIter``





   .. method:: reorder(new_order: ~typing.Sequence[int]) -> None

      Reorders ``store`` to follow the order indicated by ``new_order``. Note that
      this function only works with unsorted stores.






      .. deprecated:: 4.10

         Use list models




      :param new_order: an array of integers mapping the new
         position of each child to its old position before the re-ordering,
         i.e. ``new_order```[newpos] = oldpos`. It must have
         exactly as many items as the list store’s length.





   .. method:: set(treeiter, *args)

      Sets the value of one or more cells in the row referenced by ``iter``.
      The variable argument list should contain integer column numbers,
      each column number followed by the value to be set.
      The list is terminated by a -1. For example, to set column 0 with type
      :obj:`str` to “Foo”, you would write `gtk_list_store_set (store, iter,
      0, "Foo", -1)`.

      The value will be referenced by the store if it is a :obj:`object`, and it
      will be copied if it is a :obj:`str` or ``Boxed``.






      .. deprecated:: 4.10

         Use list models




      :param treeiter: 

      :param args: 




   .. method:: set_column_types(types: ~typing.Sequence[type]) -> None

      Sets the types of the columns of a list store.

      This function is meant primarily for objects that inherit
      from ``GtkListStore``, and should only be used when constructing
      a new instance.

      This function cannot be called after a row has been added, or
      a method on the ``GtkTreeModel`` interface is called.






      .. deprecated:: 4.10

         Use list models




      :param types: An array length n of ``GType``'s





   .. method:: set_value(treeiter, column, value)

      Sets the data in the cell specified by ``iter`` and ``column``.
      The type of ``value`` must be convertible to the type of the
      column.






      .. deprecated:: 4.10

         Use list models




      :param treeiter: 

      :param column: column number to modify


      :param value: new value for the cell





   .. method:: swap(a: ~gi.repository.Gtk.TreeIter, b: ~gi.repository.Gtk.TreeIter) -> None

      Swaps ``a`` and ``b`` in ``store``. Note that this function only works with
      unsorted stores.






      .. deprecated:: 4.10

         Use list models




      :param a: A ``GtkTreeIter``


      :param b: Another ``GtkTreeIter``















Fields
------

.. rst-class:: interim-class

.. class:: ListStore
   :no-index:
   

   .. attribute:: parent

      






   .. attribute:: priv