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 is implemented with a linked list with a
  87 tail pointer.  As a result, it is fast at data insertion and deletion,
  88 and not as fast at random data access.  The #GtkListStore sets the
  89 #GTK_TREE_MODEL_ITERS_PERSIST flag, which means that #GtkTreeIter<!--
  90 -->s can be cached while the row exists.  Thus, if access to a
  91 particular row is needed often, it is worth keeping the iter around.
  92 </para>
  93 </refsect2>
  94
  95 <!-- ##### SECTION See_Also ##### -->
  96 <para>
  97 #GtkTreeModel, #GtkTreeStore
  98 </para>
  99
 100 <!-- ##### STRUCT GtkListStore ##### -->
 101 <para>
 102
 103 </para>
 104
 105
 106 <!-- ##### FUNCTION gtk_list_store_new ##### -->
 107 <para>
 108
 109 </para>
 110
 111 @n_columns:
 112 @Varargs:
 113 @Returns:
 114
 115
 116 <!-- ##### FUNCTION gtk_list_store_newv ##### -->
 117 <para>
 118
 119 </para>
 120
 121 @n_columns:
 122 @types:
 123 @Returns:
 124
 125
 126 <!-- ##### FUNCTION gtk_list_store_set_column_types ##### -->
 127 <para>
 128
 129 </para>
 130
 131 @list_store:
 132 @n_columns:
 133 @types:
 134
 135
 136 <!-- ##### FUNCTION gtk_list_store_set ##### -->
 137 <para>
 138
 139 </para>
 140
 141 @list_store:
 142 @iter:
 143 @Varargs:
 144
 145
 146 <!-- ##### FUNCTION gtk_list_store_set_valist ##### -->
 147 <para>
 148
 149 </para>
 150
 151 @list_store:
 152 @iter:
 153 @var_args:
 154
 155
 156 <!-- ##### FUNCTION gtk_list_store_set_value ##### -->
 157 <para>
 158
 159 </para>
 160
 161 @list_store:
 162 @iter:
 163 @column:
 164 @value:
 165
 166
 167 <!-- ##### FUNCTION gtk_list_store_remove ##### -->
 168 <para>
 169
 170 </para>
 171
 172 @list_store:
 173 @iter:
 174 @Returns:
 175 <!-- # Unused Parameters # -->
 176 @store:
 177
 178
 179 <!-- ##### FUNCTION gtk_list_store_insert ##### -->
 180 <para>
 181
 182 </para>
 183
 184 @list_store:
 185 @iter:
 186 @position:
 187 <!-- # Unused Parameters # -->
 188 @store:
 189
 190
 191 <!-- ##### FUNCTION gtk_list_store_insert_before ##### -->
 192 <para>
 193
 194 </para>
 195
 196 @list_store:
 197 @iter:
 198 @sibling:
 199 <!-- # Unused Parameters # -->
 200 @store:
 201
 202
 203 <!-- ##### FUNCTION gtk_list_store_insert_after ##### -->
 204 <para>
 205
 206 </para>
 207
 208 @list_store:
 209 @iter:
 210 @sibling:
 211 <!-- # Unused Parameters # -->
 212 @store:
 213
 214
 215 <!-- ##### FUNCTION gtk_list_store_prepend ##### -->
 216 <para>
 217
 218 </para>
 219
 220 @list_store:
 221 @iter:
 222 <!-- # Unused Parameters # -->
 223 @store:
 224
 225
 226 <!-- ##### FUNCTION gtk_list_store_append ##### -->
 227 <para>
 228
 229 </para>
 230
 231 @list_store:
 232 @iter:
 233 <!-- # Unused Parameters # -->
 234 @store:
 235
 236
 237 <!-- ##### FUNCTION gtk_list_store_clear ##### -->
 238 <para>
 239
 240 </para>
 241
 242 @list_store:
 243
 244
 245 <!-- ##### FUNCTION gtk_list_store_iter_is_valid ##### -->
 246 <para>
 247
 248 </para>
 249
 250 @list_store:
 251 @iter:
 252 @Returns:
 253
 254
 255 <!-- ##### FUNCTION gtk_list_store_reorder ##### -->
 256 <para>
 257
 258 </para>
 259
 260 @store:
 261 @new_order:
 262
 263
 264 <!-- ##### FUNCTION gtk_list_store_swap ##### -->
 265 <para>
 266
 267 </para>
 268
 269 @store:
 270 @a:
 271 @b:
 272
 273
 274 <!-- ##### FUNCTION gtk_list_store_move_before ##### -->
 275 <para>
 276
 277 </para>
 278
 279 @store:
 280 @iter:
 281 @position:
 282
 283
 284 <!-- ##### FUNCTION gtk_list_store_move_after ##### -->
 285 <para>
 286
 287 </para>
 288
 289 @store:
 290 @iter:
 291 @position:
 292
 293