Synopsis#include <gtk/gtk.h> GtkListStore; GtkListStore* gtk_list_store_new (gint n_columns, ...); GtkListStore* gtk_list_store_newv (gint n_columns, GType *types); void gtk_list_store_set_column_types (GtkListStore *list_store, gint n_columns, GType *types); void gtk_list_store_set (GtkListStore *list_store, GtkTreeIter *iter, ...); void gtk_list_store_set_valist (GtkListStore *list_store, GtkTreeIter *iter, va_list var_args); void gtk_list_store_set_value (GtkListStore *list_store, GtkTreeIter *iter, gint column, GValue *value); void gtk_list_store_set_valuesv (GtkListStore *list_store, GtkTreeIter *iter, gint *columns, GValue *values, gint n_values); gboolean gtk_list_store_remove (GtkListStore *list_store, GtkTreeIter *iter); void gtk_list_store_insert (GtkListStore *list_store, GtkTreeIter *iter, gint position); void gtk_list_store_insert_before (GtkListStore *list_store, GtkTreeIter *iter, GtkTreeIter *sibling); void gtk_list_store_insert_after (GtkListStore *list_store, GtkTreeIter *iter, GtkTreeIter *sibling); void gtk_list_store_insert_with_values (GtkListStore *list_store, GtkTreeIter *iter, gint position, ...); void gtk_list_store_insert_with_valuesv (GtkListStore *list_store, GtkTreeIter *iter, gint position, gint *columns, GValue *values, gint n_values); void gtk_list_store_prepend (GtkListStore *list_store, GtkTreeIter *iter); void gtk_list_store_append (GtkListStore *list_store, GtkTreeIter *iter); void gtk_list_store_clear (GtkListStore *list_store); gboolean gtk_list_store_iter_is_valid (GtkListStore *list_store, GtkTreeIter *iter); void gtk_list_store_reorder (GtkListStore *store, gint *new_order); void gtk_list_store_swap (GtkListStore *store, GtkTreeIter *a, GtkTreeIter *b); void gtk_list_store_move_before (GtkListStore *store, GtkTreeIter *iter, GtkTreeIter *position); void gtk_list_store_move_after (GtkListStore *store, GtkTreeIter *iter, GtkTreeIter *position); Implemented InterfacesGtkListStore implements GtkBuildable, GtkTreeModel, GtkTreeDragSource, GtkTreeDragDest and GtkTreeSortable. DescriptionThe 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 drag and drop interfaces.
The GtkListStore can accept most GObject types 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 Example 23. Creating a simple list store. enum { COLUMN_STRING, COLUMN_INT, COLUMN_BOOLEAN, N_COLUMNS }; { GtkListStore *list_store; GtkTreePath *path; GtkTreeIter iter; gint i; list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT, G_TYPE_BOOLEAN); for (i = 0; i < 10; i++) { gchar *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); } Performance ConsiderationsInternally, the GtkListStore was implemented with a linked list with a tail pointer prior to GTK+ 2.6. 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.
It is important to note that only the methods
GtkListStore as GtkBuildableThe GtkListStore implementation of the GtkBuildable 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. Example 24. 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> Detailsgtk_list_store_new ()GtkListStore* gtk_list_store_new (gint n_columns, ...);
Creates a new list store as with
As an example,
gtk_list_store_newv ()GtkListStore* gtk_list_store_newv (gint n_columns, GType *types); Non-vararg creation function. Used primarily by language bindings.
gtk_list_store_set_column_types ()void gtk_list_store_set_column_types (GtkListStore *list_store, gint n_columns, GType *types); This function is meant primarily for GObjects that inherit from GtkListStore, and should only be used when constructing a new GtkListStore. It will not function after a row has been added, or a method on the GtkTreeModel interface is called.
gtk_list_store_set ()void gtk_list_store_set (GtkListStore *list_store, GtkTreeIter *iter, ...);
Sets the value of one or more cells in the row referenced by
gtk_list_store_set_valist ()void gtk_list_store_set_valist (GtkListStore *list_store, GtkTreeIter *iter, va_list var_args);
See
gtk_list_store_set_value ()void gtk_list_store_set_value (GtkListStore *list_store, GtkTreeIter *iter, gint column, GValue *value);
Sets the data in the cell specified by
gtk_list_store_set_valuesv ()void gtk_list_store_set_valuesv (GtkListStore *list_store, GtkTreeIter *iter, gint *columns, GValue *values, gint n_values);
A variant of
Since 2.12 gtk_list_store_remove ()gboolean gtk_list_store_remove (GtkListStore *list_store, GtkTreeIter *iter);
Removes the given row from the list store. After being removed,
gtk_list_store_insert ()void gtk_list_store_insert (GtkListStore *list_store, GtkTreeIter *iter, gint position);
Creates a new row at
gtk_list_store_insert_before ()void gtk_list_store_insert_before (GtkListStore *list_store, GtkTreeIter *iter, GtkTreeIter *sibling);
Inserts a new row before
gtk_list_store_insert_after ()void gtk_list_store_insert_after (GtkListStore *list_store, GtkTreeIter *iter, GtkTreeIter *sibling);
Inserts a new row after
gtk_list_store_insert_with_values ()void gtk_list_store_insert_with_values (GtkListStore *list_store, GtkTreeIter *iter, gint position, ...);
Creates a new row at
Calling
gtk_list_store_insert (list_store, iter, position); gtk_list_store_set (list_store, iter, ...);
with the difference that the former will only emit a row_inserted signal,
while the latter will emit row_inserted, row_changed and, if the list store
is sorted, rows_reordered. Since emitting the rows_reordered signal
repeatedly can affect the performance of the program,
Since 2.6 gtk_list_store_insert_with_valuesv ()void gtk_list_store_insert_with_valuesv (GtkListStore *list_store, GtkTreeIter *iter, gint position, gint *columns, GValue *values, gint n_values);
A variant of
Since 2.6 gtk_list_store_prepend ()void gtk_list_store_prepend (GtkListStore *list_store, GtkTreeIter *iter);
Prepends a new row to
gtk_list_store_append ()void gtk_list_store_append (GtkListStore *list_store, GtkTreeIter *iter);
Appends a new row to
gtk_list_store_clear ()void gtk_list_store_clear (GtkListStore *list_store); Removes all rows from the list store.
gtk_list_store_iter_is_valid ()gboolean gtk_list_store_iter_is_valid (GtkListStore *list_store, GtkTreeIter *iter);
WarningThis function is slow. Only use it for debugging and/or testing purposes.
Checks if the given iter is a valid iter for this GtkListStore.
Since 2.2 gtk_list_store_reorder ()void gtk_list_store_reorder (GtkListStore *store, gint *new_order);
Reorders
Since 2.2 gtk_list_store_swap ()void gtk_list_store_swap (GtkListStore *store, GtkTreeIter *a, GtkTreeIter *b);
Swaps
Since 2.2 gtk_list_store_move_before ()void gtk_list_store_move_before (GtkListStore *store, GtkTreeIter *iter, GtkTreeIter *position);
Moves
Since 2.2 gtk_list_store_move_after ()void gtk_list_store_move_after (GtkListStore *store, GtkTreeIter *iter, GtkTreeIter *position);
Moves
Since 2.2 |