Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkliststore.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkListStore
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A list-like data structure that can be used with the #GtkTreeView
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GtkListStore object is a list model for use with a #GtkTreeView
  10 widget.  It implements the #GtkTreeModel interface, and consequentialy,
  11 can use all of the methods available there.  It also implements the
  12 #GtkTreeSortable interface so it can be sorted by the view.
  13 Finally, it also implements the tree <link linkend="gtktreednd">drag and
  14 drop</link> interfaces.
  15 </para>
  16
  17 <para>
  18 The #GtkListStore can accept most GObject types as a column type, though
  19 it can't accept all custom types.  Internally, it will keep a copy of
  20 data passed in (such as a string or a boxed pointer).  Columns that
  21 accept #GObject<!-- -->s are handled a little differently.  The
  22 #GtkListStore will keep a reference to the object instead of copying the
  23 value.  As a result, if the object is modified, it is up to the
  24 application writer to call @gtk_tree_model_row_changed to emit the
  25 "row_changed" signal.  This most commonly effects lists with
  26 #GdkPixbuf<!-- -->s stored.
  27 </para>
  28
  29 <example>
  30 <title>Creating a simple list store.</title>
  31 <programlisting>
  32 enum {
  33   COLUMN_STRING,
  34   COLUMN_INT,
  35   COLUMN_BOOLEAN,
  36   N_COLUMNS
  37 };
  38
  39 {
  40   GtkListStore *list_store;
  41   GtkTreePath *path;
  42   GtkTreeIter iter;
  43   gint i;
  44
  45   list_store = gtk_list_store_new (N_COLUMNS,
  46                                    G_TYPE_STRING,
  47                                    G_TYPE_INT,
  48                                    G_TYPE_BOOLEAN);
  49
  50   for (i = 0; i &lt; 10; i++)
  51     {
  52       gchar *some_data;
  53
  54       some_data = get_some_data (i);
  55
  56       /* Add a new row to the model */
  57       gtk_list_store_append (list_store, &amp;iter);
  58       gtk_list_store_set (list_store, &amp;iter,
  59                           COLUMN_STRING, some_data,
  60                           COLUMN_INT, i,
  61                           COLUMN_BOOLEAN,  FALSE,
  62                           -1);
  63
  64       /* As the store will keep a copy of the string internally, we
  65        * free some_data.
  66        */
  67       g_free (some_data);
  68     }
  69
  70   /* Modify a particular row */
  71   path = gtk_tree_path_new_from_string ("4");
  72   gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store),
  73                            &amp;iter,
  74                            path);
  75   gtk_tree_path_free (path);
  76   gtk_list_store_set (list_store, &amp;iter,
  77                       COLUMN_BOOLEAN, TRUE,
  78                       -1);
  79 }
  80 </programlisting>
  81 </example>
  82
  83 <refsect2>
  84 <title>Performance Considerations</title>
  85 <para>
  86 Internally, the #GtkListStore was implemented with a linked list with a
  87 tail pointer prior to GTK+ 2.6.  As a result, it was fast at data
  88 insertion and deletion, and not fast at random data access.  The
  89 #GtkListStore sets the #GTK_TREE_MODEL_ITERS_PERSIST flag, which means
  90 that #GtkTreeIter<!-- -->s can be cached while the row exists.  Thus, if
  91 access to a particular row is needed often and your code is expected to
  92 run on older versions of GTK+, it is worth keeping the iter around.
  93 </para>
  94 </refsect2>
  95
  96 <!-- ##### SECTION See_Also ##### -->
  97 <para>
  98 #GtkTreeModel, #GtkTreeStore
  99 </para>
 100
 101 <!-- ##### STRUCT GtkListStore ##### -->
 102 <para>
 103
 104 </para>
 105
 106
 107 <!-- ##### FUNCTION gtk_list_store_new ##### -->
 108 <para>
 109
 110 </para>
 111
 112 @n_columns:
 113 @Varargs:
 114 @Returns:
 115
 116
 117 <!-- ##### FUNCTION gtk_list_store_newv ##### -->
 118 <para>
 119
 120 </para>
 121
 122 @n_columns:
 123 @types:
 124 @Returns:
 125
 126
 127 <!-- ##### FUNCTION gtk_list_store_set_column_types ##### -->
 128 <para>
 129
 130 </para>
 131
 132 @list_store:
 133 @n_columns:
 134 @types:
 135
 136
 137 <!-- ##### FUNCTION gtk_list_store_set ##### -->
 138 <para>
 139
 140 </para>
 141
 142 @list_store:
 143 @iter:
 144 @Varargs:
 145
 146
 147 <!-- ##### FUNCTION gtk_list_store_set_valist ##### -->
 148 <para>
 149
 150 </para>
 151
 152 @list_store:
 153 @iter:
 154 @var_args:
 155
 156
 157 <!-- ##### FUNCTION gtk_list_store_set_value ##### -->
 158 <para>
 159
 160 </para>
 161
 162 @list_store:
 163 @iter:
 164 @column:
 165 @value:
 166
 167
 168 <!-- ##### FUNCTION gtk_list_store_remove ##### -->
 169 <para>
 170
 171 </para>
 172
 173 @list_store:
 174 @iter:
 175 @Returns:
 176 <!-- # Unused Parameters # -->
 177 @store:
 178
 179
 180 <!-- ##### FUNCTION gtk_list_store_insert ##### -->
 181 <para>
 182
 183 </para>
 184
 185 @list_store:
 186 @iter:
 187 @position:
 188 <!-- # Unused Parameters # -->
 189 @store:
 190
 191
 192 <!-- ##### FUNCTION gtk_list_store_insert_before ##### -->
 193 <para>
 194
 195 </para>
 196
 197 @list_store:
 198 @iter:
 199 @sibling:
 200 <!-- # Unused Parameters # -->
 201 @store:
 202
 203
 204 <!-- ##### FUNCTION gtk_list_store_insert_after ##### -->
 205 <para>
 206
 207 </para>
 208
 209 @list_store:
 210 @iter:
 211 @sibling:
 212 <!-- # Unused Parameters # -->
 213 @store:
 214
 215
 216 <!-- ##### FUNCTION gtk_list_store_prepend ##### -->
 217 <para>
 218
 219 </para>
 220
 221 @list_store:
 222 @iter:
 223 <!-- # Unused Parameters # -->
 224 @store:
 225
 226
 227 <!-- ##### FUNCTION gtk_list_store_append ##### -->
 228 <para>
 229
 230 </para>
 231
 232 @list_store:
 233 @iter:
 234 <!-- # Unused Parameters # -->
 235 @store:
 236
 237
 238 <!-- ##### FUNCTION gtk_list_store_clear ##### -->
 239 <para>
 240
 241 </para>
 242
 243 @list_store:
 244
 245
 246 <!-- ##### FUNCTION gtk_list_store_iter_is_valid ##### -->
 247 <para>
 248
 249 </para>
 250
 251 @list_store:
 252 @iter:
 253 @Returns:
 254
 255
 256 <!-- ##### FUNCTION gtk_list_store_reorder ##### -->
 257 <para>
 258
 259 </para>
 260
 261 @store:
 262 @new_order:
 263
 264
 265 <!-- ##### FUNCTION gtk_list_store_swap ##### -->
 266 <para>
 267
 268 </para>
 269
 270 @store:
 271 @a:
 272 @b:
 273
 274
 275 <!-- ##### FUNCTION gtk_list_store_move_before ##### -->
 276 <para>
 277
 278 </para>
 279
 280 @store:
 281 @iter:
 282 @position:
 283
 284
 285 <!-- ##### FUNCTION gtk_list_store_move_after ##### -->
 286 <para>
 287
 288 </para>
 289
 290 @store:
 291 @iter:
 292 @position:
 293
 294