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 affects 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 <!-- ##### SECTION Stability_Level ##### -->
 102
 103
 104 <!-- ##### STRUCT GtkListStore ##### -->
 105 <para>
 106
 107 </para>
 108
 109
 110 <!-- ##### FUNCTION gtk_list_store_new ##### -->
 111 <para>
 112
 113 </para>
 114
 115 @n_columns:
 116 @Varargs:
 117 @Returns:
 118
 119
 120 <!-- ##### FUNCTION gtk_list_store_newv ##### -->
 121 <para>
 122
 123 </para>
 124
 125 @n_columns:
 126 @types:
 127 @Returns:
 128
 129
 130 <!-- ##### FUNCTION gtk_list_store_set_column_types ##### -->
 131 <para>
 132
 133 </para>
 134
 135 @list_store:
 136 @n_columns:
 137 @types:
 138
 139
 140 <!-- ##### FUNCTION gtk_list_store_set ##### -->
 141 <para>
 142
 143 </para>
 144
 145 @list_store:
 146 @iter:
 147 @Varargs:
 148
 149
 150 <!-- ##### FUNCTION gtk_list_store_set_valist ##### -->
 151 <para>
 152
 153 </para>
 154
 155 @list_store:
 156 @iter:
 157 @var_args:
 158
 159
 160 <!-- ##### FUNCTION gtk_list_store_set_value ##### -->
 161 <para>
 162
 163 </para>
 164
 165 @list_store:
 166 @iter:
 167 @column:
 168 @value:
 169
 170
 171 <!-- ##### FUNCTION gtk_list_store_remove ##### -->
 172 <para>
 173
 174 </para>
 175
 176 @list_store:
 177 @iter:
 178 @Returns:
 179 <!-- # Unused Parameters # -->
 180 @store:
 181
 182
 183 <!-- ##### FUNCTION gtk_list_store_insert ##### -->
 184 <para>
 185
 186 </para>
 187
 188 @list_store:
 189 @iter:
 190 @position:
 191 <!-- # Unused Parameters # -->
 192 @store:
 193
 194
 195 <!-- ##### FUNCTION gtk_list_store_insert_before ##### -->
 196 <para>
 197
 198 </para>
 199
 200 @list_store:
 201 @iter:
 202 @sibling:
 203 <!-- # Unused Parameters # -->
 204 @store:
 205
 206
 207 <!-- ##### FUNCTION gtk_list_store_insert_after ##### -->
 208 <para>
 209
 210 </para>
 211
 212 @list_store:
 213 @iter:
 214 @sibling:
 215 <!-- # Unused Parameters # -->
 216 @store:
 217
 218
 219 <!-- ##### FUNCTION gtk_list_store_insert_with_values ##### -->
 220 <para>
 221
 222 </para>
 223
 224 @list_store:
 225 @iter:
 226 @position:
 227 @Varargs:
 228
 229
 230 <!-- ##### FUNCTION gtk_list_store_insert_with_valuesv ##### -->
 231 <para>
 232
 233 </para>
 234
 235 @list_store:
 236 @iter:
 237 @position:
 238 @columns:
 239 @values:
 240 @n_values:
 241
 242
 243 <!-- ##### FUNCTION gtk_list_store_prepend ##### -->
 244 <para>
 245
 246 </para>
 247
 248 @list_store:
 249 @iter:
 250 <!-- # Unused Parameters # -->
 251 @store:
 252
 253
 254 <!-- ##### FUNCTION gtk_list_store_append ##### -->
 255 <para>
 256
 257 </para>
 258
 259 @list_store:
 260 @iter:
 261 <!-- # Unused Parameters # -->
 262 @store:
 263
 264
 265 <!-- ##### FUNCTION gtk_list_store_clear ##### -->
 266 <para>
 267
 268 </para>
 269
 270 @list_store:
 271
 272
 273 <!-- ##### FUNCTION gtk_list_store_iter_is_valid ##### -->
 274 <para>
 275
 276 </para>
 277
 278 @list_store:
 279 @iter:
 280 @Returns:
 281
 282
 283 <!-- ##### FUNCTION gtk_list_store_reorder ##### -->
 284 <para>
 285
 286 </para>
 287
 288 @store:
 289 @new_order:
 290
 291
 292 <!-- ##### FUNCTION gtk_list_store_swap ##### -->
 293 <para>
 294
 295 </para>
 296
 297 @store:
 298 @a:
 299 @b:
 300
 301
 302 <!-- ##### FUNCTION gtk_list_store_move_before ##### -->
 303 <para>
 304
 305 </para>
 306
 307 @store:
 308 @iter:
 309 @position:
 310
 311
 312 <!-- ##### FUNCTION gtk_list_store_move_after ##### -->
 313 <para>
 314
 315 </para>
 316
 317 @store:
 318 @iter:
 319 @position:
 320
 321