2000-10-30 23:21:38 +00:00
|
|
|
<!-- ##### SECTION Title ##### -->
|
|
|
|
GtkListStore
|
|
|
|
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
2002-11-02 13:43:01 +00:00
|
|
|
A list-like data structure that can be used with the #GtkTreeView
|
2000-10-30 23:21:38 +00:00
|
|
|
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
|
|
<para>
|
2002-03-07 08:03:09 +00:00
|
|
|
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
|
2002-11-02 13:43:01 +00:00
|
|
|
#GtkTreeSortable interface so it can be sorted by the view.
|
2002-03-07 08:03:09 +00:00
|
|
|
Finally, it also implements the tree <link linkend="gtktreednd">drag and
|
|
|
|
drop</link> interfaces.
|
2000-10-30 23:21:38 +00:00
|
|
|
</para>
|
|
|
|
|
2002-11-17 21:23:58 +00:00
|
|
|
<para>
|
|
|
|
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 #GObject<!-- -->s 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 @gtk_tree_model_row_changed to emit the
|
|
|
|
"row_changed" signal. This most commonly effects lists with
|
|
|
|
#GdkPixbuf<!-- -->s stored.
|
|
|
|
</para>
|
|
|
|
|
2002-11-02 13:43:01 +00:00
|
|
|
<example>
|
|
|
|
<title>Creating a simple list store.</title>
|
|
|
|
<programlisting>
|
|
|
|
enum {
|
|
|
|
COLUMN_STRING,
|
|
|
|
COLUMN_INT,
|
|
|
|
COLUMN_BOOLEAN,
|
|
|
|
N_COLUMNS
|
2002-11-17 21:23:58 +00:00
|
|
|
};
|
2002-11-02 13:43:01 +00:00
|
|
|
|
|
|
|
{
|
|
|
|
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);
|
|
|
|
|
2002-11-02 18:18:50 +00:00
|
|
|
for (i = 0; i < 10; i++)
|
2002-11-02 13:43:01 +00:00
|
|
|
{
|
|
|
|
gchar *some_data;
|
|
|
|
|
|
|
|
some_data = get_some_data (i);
|
|
|
|
|
|
|
|
/* Add a new row to the model */
|
2002-11-02 18:18:50 +00:00
|
|
|
gtk_list_store_append (list_store, &iter);
|
|
|
|
gtk_list_store_set (list_store, &iter,
|
2002-11-02 13:43:01 +00:00
|
|
|
COLUMN_STRING, some_data,
|
|
|
|
COLUMN_INT, i,
|
|
|
|
COLUMN_BOOLEAN, FALSE,
|
|
|
|
-1);
|
|
|
|
|
2002-11-17 21:23:58 +00:00
|
|
|
/* As the store will keep a copy of the string internally, we
|
|
|
|
* free some_data.
|
|
|
|
*/
|
2002-11-02 13:43:01 +00:00
|
|
|
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),
|
2002-11-02 18:18:50 +00:00
|
|
|
&iter,
|
2002-11-02 13:43:01 +00:00
|
|
|
path);
|
|
|
|
gtk_tree_path_free (path);
|
2002-11-02 18:18:50 +00:00
|
|
|
gtk_list_store_set (list_store, &iter,
|
2002-11-02 13:43:01 +00:00
|
|
|
COLUMN_BOOLEAN, TRUE,
|
|
|
|
-1);
|
|
|
|
}
|
|
|
|
</programlisting>
|
|
|
|
</example>
|
2002-03-09 18:06:05 +00:00
|
|
|
|
2002-11-17 21:23:58 +00:00
|
|
|
<refsect2>
|
|
|
|
<title>Performance Considerations</title>
|
2000-10-30 23:21:38 +00:00
|
|
|
<para>
|
2002-11-17 21:23:58 +00:00
|
|
|
Internally, the #GtkListStore is implemented with a linked list with a
|
|
|
|
tail pointer. As a result, it is fast at data insertion and deletion,
|
|
|
|
and not as fast at random data access. The #GtkListStore sets the
|
|
|
|
#GTK_TREE_MODEL_ITERS_PERSIST flag, which means that #GtkTreeIter<!--
|
|
|
|
-->s can be cached while the row exists. Thus, if access to a
|
|
|
|
particular row is needed often, it is worth keeping the iter around.
|
|
|
|
</para>
|
|
|
|
</refsect>
|
2000-10-30 23:21:38 +00:00
|
|
|
|
2002-11-17 21:23:58 +00:00
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
|
|
<para>
|
|
|
|
#GtkTreeModel, #GtkTreeStore
|
2000-10-30 23:21:38 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### STRUCT GtkListStore ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_list_store_new ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
@n_columns:
|
|
|
|
@Varargs:
|
|
|
|
@Returns:
|
|
|
|
|
|
|
|
|
2001-10-03 04:44:13 +00:00
|
|
|
<!-- ##### FUNCTION gtk_list_store_newv ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
@n_columns:
|
|
|
|
@types:
|
|
|
|
@Returns:
|
|
|
|
|
|
|
|
|
2001-11-21 21:43:47 +00:00
|
|
|
<!-- ##### FUNCTION gtk_list_store_set_column_types ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
@list_store:
|
|
|
|
@n_columns:
|
|
|
|
@types:
|
|
|
|
|
|
|
|
|
2001-10-03 04:44:13 +00:00
|
|
|
<!-- ##### FUNCTION gtk_list_store_set ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
@list_store:
|
|
|
|
@iter:
|
|
|
|
@Varargs:
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_list_store_set_valist ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
@list_store:
|
|
|
|
@iter:
|
|
|
|
@var_args:
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_list_store_set_value ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
@list_store:
|
|
|
|
@iter:
|
|
|
|
@column:
|
|
|
|
@value:
|
|
|
|
|
|
|
|
|
2000-10-30 23:21:38 +00:00
|
|
|
<!-- ##### FUNCTION gtk_list_store_remove ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
2001-09-08 18:23:47 +00:00
|
|
|
@list_store:
|
2000-10-30 23:21:38 +00:00
|
|
|
@iter:
|
2002-06-08 06:48:27 +00:00
|
|
|
@Returns:
|
2001-09-08 18:23:47 +00:00
|
|
|
<!-- # Unused Parameters # -->
|
|
|
|
@store:
|
2000-10-30 23:21:38 +00:00
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_list_store_insert ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
2001-09-08 18:23:47 +00:00
|
|
|
@list_store:
|
2000-10-30 23:21:38 +00:00
|
|
|
@iter:
|
|
|
|
@position:
|
2001-09-08 18:23:47 +00:00
|
|
|
<!-- # Unused Parameters # -->
|
|
|
|
@store:
|
2000-10-30 23:21:38 +00:00
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_list_store_insert_before ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
2001-09-08 18:23:47 +00:00
|
|
|
@list_store:
|
2000-10-30 23:21:38 +00:00
|
|
|
@iter:
|
|
|
|
@sibling:
|
2001-09-08 18:23:47 +00:00
|
|
|
<!-- # Unused Parameters # -->
|
|
|
|
@store:
|
2000-10-30 23:21:38 +00:00
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_list_store_insert_after ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
2001-09-08 18:23:47 +00:00
|
|
|
@list_store:
|
2000-10-30 23:21:38 +00:00
|
|
|
@iter:
|
|
|
|
@sibling:
|
2001-09-08 18:23:47 +00:00
|
|
|
<!-- # Unused Parameters # -->
|
|
|
|
@store:
|
2000-10-30 23:21:38 +00:00
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_list_store_prepend ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
2001-09-08 18:23:47 +00:00
|
|
|
@list_store:
|
2000-10-30 23:21:38 +00:00
|
|
|
@iter:
|
2001-09-08 18:23:47 +00:00
|
|
|
<!-- # Unused Parameters # -->
|
|
|
|
@store:
|
2000-10-30 23:21:38 +00:00
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_list_store_append ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
2001-09-08 18:23:47 +00:00
|
|
|
@list_store:
|
2000-10-30 23:21:38 +00:00
|
|
|
@iter:
|
2001-09-08 18:23:47 +00:00
|
|
|
<!-- # Unused Parameters # -->
|
|
|
|
@store:
|
2000-10-30 23:21:38 +00:00
|
|
|
|
|
|
|
|
2001-10-03 04:44:13 +00:00
|
|
|
<!-- ##### FUNCTION gtk_list_store_clear ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
@list_store:
|
|
|
|
|
|
|
|
|
Documentation fixes.
Sun Oct 13 18:50:14 2002 Soeren Sandmann <sandmann@daimi.au.dk>
* gtkmenu.c, gtkmenu.sgml, gtkitemfactory.c, gdkwindow.c,
gtkwindow.c, gtkpaned.sgml, gtkdialog.c, gtkbox.h, gtkbutton.sgml,
gtktreemodel.sgml,gtktable.sgml, gtktable.c:
Documentation fixes.
#85719, #90759, #95169, Owen Taylor;
#89221, Yao Zhang, Matthias Clasen;
#95592, Joost Faassen;
#92637, Vitaly Tishkov;
#94616, Ben Martin;
#94772, sbaillie@bigpond.net.au;
2002-10-13 17:17:14 +00:00
|
|
|
<!-- ##### FUNCTION gtk_list_store_iter_is_valid ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
@list_store:
|
|
|
|
@iter:
|
|
|
|
@Returns:
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_list_store_reorder ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
@store:
|
|
|
|
@new_order:
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_list_store_swap ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
@store:
|
|
|
|
@a:
|
|
|
|
@b:
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gtk_list_store_move ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
|
|
|
@store:
|
|
|
|
@iter:
|
|
|
|
@position:
|
|
|
|
|
|
|
|
|