gtk4/org.gtkkn.bindings.gtk/ListStore

ListStore

open class ListStore( val gtkListStorePointer: <Error class: unknown class><<Error class: unknown class>>) : Buildable, TreeDragDest, TreeDragSource, TreeModel, TreeSortable(source)

⚠️ Deprecated ⚠️

This is deprecated since version 4.10.

Use class@Gio.ListStore instead

---

A list-like data structure that can be used with the class@Gtk.TreeView.

The GtkListStore object is a list model for use with a GtkTreeView widget. It implements the GtkTreeModel interface, and consequentialy, can use all of the methods available there. It also implements the GtkTreeSortable interface so it can be sorted by the view. Finally, it also implements the tree iface.TreeDragSource.html and iface.TreeDragDest.html interfaces.

The GtkListStore can accept most GTypes as a column type, though it can’t accept all custom types. Internally, it will keep a copy of data passed in (such as a string or a boxed pointer). Columns that accept GObjects are handled a little differently. The GtkListStore will keep a reference to the object instead of copying the value. As a result, if the object is modified, it is up to the application writer to call method@Gtk.TreeModel.row_changed to emit the signal@Gtk.TreeModel::row_changed signal. This most commonly affects lists with class@Gdk.Textures stored.

An example for creating a simple list store:

enum {
  COLUMN_STRING,
  COLUMN_INT,
  COLUMN_BOOLEAN,
  N_COLUMNS
};

{
  GtkListStore *list_store;
  GtkTreePath *path;
  GtkTreeIter iter;
  int i;

  list_store = gtk_list_store_new (N_COLUMNS,
                                   G_TYPE_STRING,
                                   G_TYPE_INT,
                                   G_TYPE_BOOLEAN);

  for (i = 0; i < 10; i++)
    {
      char *some_data;

      some_data = get_some_data (i);

      // Add a new row to the model
      gtk_list_store_append (list_store, &iter);
      gtk_list_store_set (list_store, &iter,
                          COLUMN_STRING, some_data,
                          COLUMN_INT, i,
                          COLUMN_BOOLEAN,  FALSE,
                          -1);

      // As the store will keep a copy of the string internally,
      // we free some_data.
      g_free (some_data);
    }

  // Modify a particular row
  path = gtk_tree_path_new_from_string ("4");
  gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store),
                           &iter,
                           path);
  gtk_tree_path_free (path);
  gtk_list_store_set (list_store, &iter,
                      COLUMN_BOOLEAN, TRUE,
                      -1);
}

GtkListStore is deprecated since GTK 4.10, and should not be used in newly written code. You should use class@Gio.ListStore instead, and the various list models provided by GTK.

Performance Considerations

Internally, the GtkListStore was originally implemented with a linked list with a tail pointer. As a result, it was fast at data insertion and deletion, and not fast at random data access. The GtkListStore sets the GTK_TREE_MODEL_ITERS_PERSIST flag, which means that GtkTreeIters can be cached while the row exists. Thus, if access to a particular row is needed often and your code is expected to run on older versions of GTK, it is worth keeping the iter around.

Atomic Operations

It is important to note that only the methods gtk_list_store_insert_with_values() and gtk_list_store_insert_with_valuesv() are atomic, in the sense that the row is being appended to the store and the values filled in in a single operation with regard to GtkTreeModel signaling. In contrast, using e.g. gtk_list_store_append() and then gtk_list_store_set() will first create a row, which triggers the GtkTreeModel::row-inserted signal on GtkListStore. The row, however, is still empty, and any signal handler connecting to GtkTreeModel::row-inserted on this particular store should be prepared for the situation that the row might be empty. This is especially important if you are wrapping the GtkListStore inside a GtkTreeModelFilter and are using a GtkTreeModelFilterVisibleFunc. Using any of the non-atomic operations to append rows to the GtkListStore will cause the GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the function must be prepared for that.

GtkListStore as GtkBuildable

The GtkListStore implementation of the iface@Gtk.Buildable interface allows to specify the model columns with a <columns> element that may contain multiple <column> elements, each specifying one model column. The “type” attribute specifies the data type for the column.

Additionally, it is possible to specify content for the list store in the UI definition, with the <data> element. It can contain multiple <row> elements, each specifying to content for one row of the list model. Inside a <row>, the <col> elements specify the content for individual cells.

Note that it is probably more common to define your models in the code, and one might consider it a layering violation to specify the content of a list store in a UI definition, data, not presentation, and common wisdom is to separate the two, as far as possible.

An example of a UI Definition fragment for a list store:

<object class="GtkListStore">
  <columns>
    <column type="gchararray"/>
    <column type="gchararray"/>
    <column type="gint"/>
  </columns>
  <data>
    <row>
      <col id="0">John</col>
      <col id="1">Doe</col>
      <col id="2">25</col>
    </row>
    <row>
      <col id="0">Johan</col>
      <col id="1">Dahlin</col>
      <col id="2">50</col>
    </row>
  </data>
</object>

Skipped during bindings generation

parameter columns: Array parameter of type gint is not supported
parameter new_order: Array parameter of type gint is not supported
parameter types: Array parameter of type GType is not supported
parameter var_args: va_list type is not supported
parameter columns: Array parameter of type gint is not supported
parameter types: Array parameter of type GType is not supported

Constructors

ListStore

constructor(gtkListStorePointer: <Error class: unknown class><<Error class: unknown class>>)

Types

Companion

object Companion

Properties

gtkBuildablePointer

open override val gtkBuildablePointer: <Error class: unknown class><<Error class: unknown class>>

gtkListStorePointer

val gtkListStorePointer: <Error class: unknown class><<Error class: unknown class>>

gtkTreeDragDestPointer

open override val gtkTreeDragDestPointer: <Error class: unknown class><<Error class: unknown class>>

gtkTreeDragSourcePointer

open override val gtkTreeDragSourcePointer: <Error class: unknown class><<Error class: unknown class>>

gtkTreeModelPointer

open override val gtkTreeModelPointer: <Error class: unknown class><<Error class: unknown class>>

gtkTreeSortablePointer

open override val gtkTreeSortablePointer: <Error class: unknown class><<Error class: unknown class>>

Functions

append

open fun append(iter: TreeIter)

This is deprecated since version 4.10.

clear

open fun clear()

This is deprecated since version 4.10.

dragDataDelete

open fun dragDataDelete(path: TreePath): Boolean

This is deprecated since version 4.10.

dragDataGet

open fun dragDataGet(path: TreePath): <Error class: unknown class>?

This is deprecated since version 4.10.

dragDataReceived

open fun dragDataReceived(dest: TreePath, value: <Error class: unknown class>): Boolean

This is deprecated since version 4.10.

filterNew

open fun filterNew(root: TreePath? = null): TreeModel

This is deprecated since version 4.10.

---

foreach

open fun foreach(func: TreeModelForeachFunc)

This is deprecated since version 4.10.

---

getBuildableId

open fun getBuildableId(): String?

Gets the ID of the @buildable object.

getColumnType

open fun getColumnType(index: <Error class: unknown class>): <Error class: unknown class>

This is deprecated since version 4.10.

---

getFlags

open fun getFlags(): TreeModelFlags

This is deprecated since version 4.10.

---

getIter

open fun getIter(iter: TreeIter, path: TreePath): Boolean

This is deprecated since version 4.10.

---

getIterFirst

open fun getIterFirst(iter: TreeIter): Boolean

This is deprecated since version 4.10.

---

getIterFromString

open fun getIterFromString(iter: TreeIter, pathString: String): Boolean

This is deprecated since version 4.10.

---

getNColumns

open fun getNColumns(): <Error class: unknown class>

This is deprecated since version 4.10.

---

getPath

open fun getPath(iter: TreeIter): TreePath

This is deprecated since version 4.10.

---

getStringFromIter

open fun getStringFromIter(iter: TreeIter): String?

This is deprecated since version 4.10.

---

getValue

open fun getValue(iter: TreeIter, column: <Error class: unknown class>, value: <Error class: unknown class>)

This is deprecated since version 4.10.

---

hasDefaultSortFunc

open fun hasDefaultSortFunc(): Boolean

This is deprecated since version 4.10.

---

insert

open fun insert(iter: TreeIter, position: <Error class: unknown class>)

This is deprecated since version 4.10.

insertAfter

open fun insertAfter(iter: TreeIter, sibling: TreeIter? = null)

This is deprecated since version 4.10.

insertBefore

open fun insertBefore(iter: TreeIter, sibling: TreeIter? = null)

This is deprecated since version 4.10.

iterChildren

open fun iterChildren(iter: TreeIter, parent: TreeIter? = null): Boolean

This is deprecated since version 4.10.

---

iterHasChild

open fun iterHasChild(iter: TreeIter): Boolean

This is deprecated since version 4.10.

---

iterIsValid

open fun iterIsValid(iter: TreeIter): Boolean

This is deprecated since version 4.10.

iterNChildren

open fun iterNChildren(iter: TreeIter? = null): <Error class: unknown class>

This is deprecated since version 4.10.

---

iterNext

open fun iterNext(iter: TreeIter): Boolean

This is deprecated since version 4.10.

---

iterNthChild

open fun iterNthChild(iter: TreeIter, parent: TreeIter? = null, n: <Error class: unknown class>): Boolean

This is deprecated since version 4.10.

---

iterParent

open fun iterParent(iter: TreeIter, child: TreeIter): Boolean

This is deprecated since version 4.10.

---

iterPrevious

open fun iterPrevious(iter: TreeIter): Boolean

This is deprecated since version 4.10.

---

moveAfter

open fun moveAfter(iter: TreeIter, position: TreeIter? = null)

This is deprecated since version 4.10.

moveBefore

open fun moveBefore(iter: TreeIter, position: TreeIter? = null)

This is deprecated since version 4.10.

onRowChanged

open fun onRowChanged( connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (path: TreePath, iter: TreeIter) -> Unit): <Error class: unknown class>

This signal is emitted when a row in the model has changed.

onRowDeleted

open fun onRowDeleted( connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (path: TreePath) -> Unit): <Error class: unknown class>

This signal is emitted when a row has been deleted.

onRowHasChildToggled

open fun onRowHasChildToggled( connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (path: TreePath, iter: TreeIter) -> Unit): <Error class: unknown class>

This signal is emitted when a row has gotten the first child row or lost its last child row.

onRowInserted

open fun onRowInserted( connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (path: TreePath, iter: TreeIter) -> Unit): <Error class: unknown class>

This signal is emitted when a new row has been inserted in the model.

onRowsReordered

open fun onRowsReordered( connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: (path: TreePath, iter: TreeIter, <Error class: unknown class>?) -> Unit): <Error class: unknown class>

This signal is emitted when the children of a node in the GtkTreeModel have been reordered.

onSortColumnChanged

open fun onSortColumnChanged(connectFlags: <Error class: unknown class> = ConnectFlags(0u), handler: () -> Unit): <Error class: unknown class>

The ::sort-column-changed signal is emitted when the sort column or sort order of @sortable is changed. The signal is emitted before the contents of @sortable are resorted.

prepend

open fun prepend(iter: TreeIter)

This is deprecated since version 4.10.

refNode

open fun refNode(iter: TreeIter)

This is deprecated since version 4.10.

---

remove