gtktreemodel.h 15.4 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14
/* gtktreemodel.h
 * Copyright (C) 2000  Red Hat, Inc.,  Jonathan Blandford <jrb@redhat.com>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
Javier Jardón's avatar
Javier Jardón committed
15
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
16 17
 */

18 19 20
#ifndef __GTK_TREE_MODEL_H__
#define __GTK_TREE_MODEL_H__

21
#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
22 23 24
#error "Only <gtk/gtk.h> can be included directly."
#endif

Manish Singh's avatar
Manish Singh committed
25
#include <glib-object.h>
26
#include <gdk/gdk.h>
27

28
G_BEGIN_DECLS
29 30

#define GTK_TYPE_TREE_MODEL            (gtk_tree_model_get_type ())
31 32
#define GTK_TREE_MODEL(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_TREE_MODEL, GtkTreeModel))
#define GTK_IS_TREE_MODEL(obj)	       (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_TREE_MODEL))
33
#define GTK_TREE_MODEL_GET_IFACE(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), GTK_TYPE_TREE_MODEL, GtkTreeModelIface))
34

35 36
#define GTK_TYPE_TREE_ITER             (gtk_tree_iter_get_type ())
#define GTK_TYPE_TREE_PATH             (gtk_tree_path_get_type ())
37
#define GTK_TYPE_TREE_ROW_REFERENCE    (gtk_tree_row_reference_get_type ())
38

39 40 41 42 43
typedef struct _GtkTreeIter         GtkTreeIter;
typedef struct _GtkTreePath         GtkTreePath;
typedef struct _GtkTreeRowReference GtkTreeRowReference;
typedef struct _GtkTreeModel        GtkTreeModel; /* Dummy typedef */
typedef struct _GtkTreeModelIface   GtkTreeModelIface;
44

45 46 47 48 49
/**
 * GtkTreeModelForeachFunc:
 * @model: the #GtkTreeModel being iterated
 * @path: the current #GtkTreePath
 * @iter: the current #GtkTreeIter
50
 * @data: (closure): The user data passed to gtk_tree_model_foreach()
51 52 53 54
 *
 * Type of the callback passed to gtk_tree_model_foreach() to
 * iterate over the rows in a tree model.
 *
55
 * Returns: %TRUE to stop iterating, %FALSE to continue
56 57 58
 *
 */
typedef gboolean (* GtkTreeModelForeachFunc) (GtkTreeModel *model, GtkTreePath *path, GtkTreeIter *iter, gpointer data);
59

60 61 62 63 64 65 66 67 68 69 70 71 72 73
/**
 * GtkTreeModelFlags:
 * @GTK_TREE_MODEL_ITERS_PERSIST: iterators survive all signals
 *     emitted by the tree
 * @GTK_TREE_MODEL_LIST_ONLY: the model is a list only, and never
 *     has children
 *
 * These flags indicate various properties of a #GtkTreeModel.
 *
 * They are returned by gtk_tree_model_get_flags(), and must be
 * static for the lifetime of the object. A more complete description
 * of #GTK_TREE_MODEL_ITERS_PERSIST can be found in the overview of
 * this section.
 */
74 75
typedef enum
{
76
  GTK_TREE_MODEL_ITERS_PERSIST = 1 << 0,
77
  GTK_TREE_MODEL_LIST_ONLY = 1 << 1
78 79
} GtkTreeModelFlags;

80 81 82 83 84 85 86
/**
 * GtkTreeIter:
 * @stamp: a unique stamp to catch invalid iterators
 * @user_data: model-specific data
 * @user_data2: model-specific data
 * @user_data3: model-specific data
 *
87
 * The #GtkTreeIter is the primary structure
88
 * for accessing a #GtkTreeModel. Models are expected to put a unique
89 90
 * integer in the @stamp member, and put
 * model-specific data in the three @user_data
91 92
 * members.
 */
93 94 95
struct _GtkTreeIter
{
  gint stamp;
Havoc Pennington's avatar
Havoc Pennington committed
96 97 98
  gpointer user_data;
  gpointer user_data2;
  gpointer user_data3;
99 100
};

101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129
/**
 * GtkTreeModelIface:
 * @row_changed: Signal emitted when a row in the model has changed.
 * @row_inserted: Signal emitted when a new row has been inserted in
 *    the model.
 * @row_has_child_toggled: Signal emitted when a row has gotten the
 *    first child row or lost its last child row.
 * @row_deleted: Signal emitted when a row has been deleted.
 * @rows_reordered: Signal emitted when the children of a node in the
 *    GtkTreeModel have been reordered.
 * @get_flags: Get #GtkTreeModelFlags supported by this interface.
 * @get_n_columns: Get the number of columns supported by the model.
 * @get_column_type: Get the type of the column.
 * @get_iter: Sets iter to a valid iterator pointing to path.
 * @get_path: Gets a newly-created #GtkTreePath referenced by iter.
 * @get_value: Initializes and sets value to that at column.
 * @iter_next: Sets iter to point to the node following it at the
 *    current level.
 * @iter_previous: Sets iter to point to the previous node at the
 *    current level.
 * @iter_children: Sets iter to point to the first child of parent.
 * @iter_has_child: %TRUE if iter has children, %FALSE otherwise.
 * @iter_n_children: Gets the number of children that iter has.
 * @iter_nth_child: Sets iter to be the child of parent, using the
 *    given index.
 * @iter_parent: Sets iter to be the parent of child.
 * @ref_node: Lets the tree ref the node.
 * @unref_node: Lets the tree unref the node.
 */
130
struct _GtkTreeModelIface
131
{
132
  /*< private >*/
133
  GTypeInterface g_iface;
134

135 136
  /*< public >*/

137
  /* Signals */
138 139 140 141 142 143 144 145 146 147 148 149 150 151 152
  void         (* row_changed)           (GtkTreeModel *tree_model,
					  GtkTreePath  *path,
					  GtkTreeIter  *iter);
  void         (* row_inserted)          (GtkTreeModel *tree_model,
					  GtkTreePath  *path,
					  GtkTreeIter  *iter);
  void         (* row_has_child_toggled) (GtkTreeModel *tree_model,
					  GtkTreePath  *path,
					  GtkTreeIter  *iter);
  void         (* row_deleted)           (GtkTreeModel *tree_model,
					  GtkTreePath  *path);
  void         (* rows_reordered)        (GtkTreeModel *tree_model,
					  GtkTreePath  *path,
					  GtkTreeIter  *iter,
					  gint         *new_order);
153

154
  /* Virtual Table */
155
  GtkTreeModelFlags (* get_flags)  (GtkTreeModel *tree_model);
156

157
  gint         (* get_n_columns)   (GtkTreeModel *tree_model);
158
  GType        (* get_column_type) (GtkTreeModel *tree_model,
159
				    gint          index_);
160 161
  gboolean     (* get_iter)        (GtkTreeModel *tree_model,
				    GtkTreeIter  *iter,
162 163
				    GtkTreePath  *path);
  GtkTreePath *(* get_path)        (GtkTreeModel *tree_model,
164
				    GtkTreeIter  *iter);
165
  void         (* get_value)       (GtkTreeModel *tree_model,
166
				    GtkTreeIter  *iter,
167 168
				    gint          column,
				    GValue       *value);
169 170
  gboolean     (* iter_next)       (GtkTreeModel *tree_model,
				    GtkTreeIter  *iter);
171 172
  gboolean     (* iter_previous)   (GtkTreeModel *tree_model,
				    GtkTreeIter  *iter);
173 174
  gboolean     (* iter_children)   (GtkTreeModel *tree_model,
				    GtkTreeIter  *iter,
175
				    GtkTreeIter  *parent);
176 177 178 179 180 181 182
  gboolean     (* iter_has_child)  (GtkTreeModel *tree_model,
				    GtkTreeIter  *iter);
  gint         (* iter_n_children) (GtkTreeModel *tree_model,
				    GtkTreeIter  *iter);
  gboolean     (* iter_nth_child)  (GtkTreeModel *tree_model,
				    GtkTreeIter  *iter,
				    GtkTreeIter  *parent,
183
				    gint          n);
184 185
  gboolean     (* iter_parent)     (GtkTreeModel *tree_model,
				    GtkTreeIter  *iter,
186
				    GtkTreeIter  *child);
187
  void         (* ref_node)        (GtkTreeModel *tree_model,
188
				    GtkTreeIter  *iter);
189
  void         (* unref_node)      (GtkTreeModel *tree_model,
190
				    GtkTreeIter  *iter);
191 192 193
};


194
/* GtkTreePath operations */
195
GDK_AVAILABLE_IN_ALL
196
GtkTreePath *gtk_tree_path_new              (void);
197
GDK_AVAILABLE_IN_ALL
198
GtkTreePath *gtk_tree_path_new_from_string  (const gchar       *path);
199
GDK_AVAILABLE_IN_ALL
200 201
GtkTreePath *gtk_tree_path_new_from_indices (gint               first_index,
					     ...);
202 203 204
GDK_AVAILABLE_IN_3_12
GtkTreePath *gtk_tree_path_new_from_indicesv (gint             *indices,
					      gsize             length);
205
GDK_AVAILABLE_IN_ALL
206
gchar       *gtk_tree_path_to_string        (GtkTreePath       *path);
207
GDK_AVAILABLE_IN_ALL
208
GtkTreePath *gtk_tree_path_new_first        (void);
209
GDK_AVAILABLE_IN_ALL
210
void         gtk_tree_path_append_index     (GtkTreePath       *path,
211
					     gint               index_);
212
GDK_AVAILABLE_IN_ALL
213
void         gtk_tree_path_prepend_index    (GtkTreePath       *path,
214
					     gint               index_);
215
GDK_AVAILABLE_IN_ALL
216
gint         gtk_tree_path_get_depth        (GtkTreePath       *path);
217
GDK_AVAILABLE_IN_ALL
218 219
gint        *gtk_tree_path_get_indices      (GtkTreePath       *path);

220
GDK_AVAILABLE_IN_ALL
221 222
gint        *gtk_tree_path_get_indices_with_depth (GtkTreePath *path,
						   gint        *depth);
223

224
GDK_AVAILABLE_IN_ALL
225
void         gtk_tree_path_free             (GtkTreePath       *path);
226
GDK_AVAILABLE_IN_ALL
227
GtkTreePath *gtk_tree_path_copy             (const GtkTreePath *path);
228
GDK_AVAILABLE_IN_ALL
Matthias Clasen's avatar
Matthias Clasen committed
229
GType        gtk_tree_path_get_type         (void) G_GNUC_CONST;
230
GDK_AVAILABLE_IN_ALL
231 232
gint         gtk_tree_path_compare          (const GtkTreePath *a,
					     const GtkTreePath *b);
233
GDK_AVAILABLE_IN_ALL
234
void         gtk_tree_path_next             (GtkTreePath       *path);
235
GDK_AVAILABLE_IN_ALL
236
gboolean     gtk_tree_path_prev             (GtkTreePath       *path);
237
GDK_AVAILABLE_IN_ALL
238
gboolean     gtk_tree_path_up               (GtkTreePath       *path);
239
GDK_AVAILABLE_IN_ALL
240 241
void         gtk_tree_path_down             (GtkTreePath       *path);

242
GDK_AVAILABLE_IN_ALL
243 244
gboolean     gtk_tree_path_is_ancestor      (GtkTreePath       *path,
                                             GtkTreePath       *descendant);
245
GDK_AVAILABLE_IN_ALL
246 247 248
gboolean     gtk_tree_path_is_descendant    (GtkTreePath       *path,
                                             GtkTreePath       *ancestor);

249 250 251 252 253 254
/**
 * GtkTreeRowReference:
 *
 * A GtkTreeRowReference tracks model changes so that it always refers to the
 * same row (a #GtkTreePath refers to a position, not a fixed row). Create a
 * new GtkTreeRowReference with gtk_tree_row_reference_new().
255 256
 */

257
GDK_AVAILABLE_IN_ALL
Matthias Clasen's avatar
Matthias Clasen committed
258
GType                gtk_tree_row_reference_get_type (void) G_GNUC_CONST;
259
GDK_AVAILABLE_IN_ALL
260 261
GtkTreeRowReference *gtk_tree_row_reference_new       (GtkTreeModel        *model,
						       GtkTreePath         *path);
262
GDK_AVAILABLE_IN_ALL
263 264 265
GtkTreeRowReference *gtk_tree_row_reference_new_proxy (GObject             *proxy,
						       GtkTreeModel        *model,
						       GtkTreePath         *path);
266
GDK_AVAILABLE_IN_ALL
267
GtkTreePath         *gtk_tree_row_reference_get_path  (GtkTreeRowReference *reference);
268
GDK_AVAILABLE_IN_ALL
269
GtkTreeModel        *gtk_tree_row_reference_get_model (GtkTreeRowReference *reference);
270
GDK_AVAILABLE_IN_ALL
271
gboolean             gtk_tree_row_reference_valid     (GtkTreeRowReference *reference);
272
GDK_AVAILABLE_IN_ALL
273
GtkTreeRowReference *gtk_tree_row_reference_copy      (GtkTreeRowReference *reference);
274
GDK_AVAILABLE_IN_ALL
275 276 277
void                 gtk_tree_row_reference_free      (GtkTreeRowReference *reference);
/* These two functions are only needed if you created the row reference with a
 * proxy object */
278
GDK_AVAILABLE_IN_ALL
279 280
void                 gtk_tree_row_reference_inserted  (GObject     *proxy,
						       GtkTreePath *path);
281
GDK_AVAILABLE_IN_ALL
282 283
void                 gtk_tree_row_reference_deleted   (GObject     *proxy,
						       GtkTreePath *path);
284
GDK_AVAILABLE_IN_ALL
285 286 287 288
void                 gtk_tree_row_reference_reordered (GObject     *proxy,
						       GtkTreePath *path,
						       GtkTreeIter *iter,
						       gint        *new_order);
289

290
/* GtkTreeIter operations */
291
GDK_AVAILABLE_IN_ALL
292
GtkTreeIter *     gtk_tree_iter_copy             (GtkTreeIter  *iter);
293
GDK_AVAILABLE_IN_ALL
294
void              gtk_tree_iter_free             (GtkTreeIter  *iter);
295
GDK_AVAILABLE_IN_ALL
Matthias Clasen's avatar
Matthias Clasen committed
296
GType             gtk_tree_iter_get_type         (void) G_GNUC_CONST;
297

298
GDK_AVAILABLE_IN_ALL
Manish Singh's avatar
Manish Singh committed
299
GType             gtk_tree_model_get_type        (void) G_GNUC_CONST;
300
GDK_AVAILABLE_IN_ALL
301
GtkTreeModelFlags gtk_tree_model_get_flags       (GtkTreeModel *tree_model);
302
GDK_AVAILABLE_IN_ALL
303
gint              gtk_tree_model_get_n_columns   (GtkTreeModel *tree_model);
304
GDK_AVAILABLE_IN_ALL
305
GType             gtk_tree_model_get_column_type (GtkTreeModel *tree_model,
306
						  gint          index_);
307 308 309


/* Iterator movement */
310
GDK_AVAILABLE_IN_ALL
311 312
gboolean          gtk_tree_model_get_iter        (GtkTreeModel *tree_model,
						  GtkTreeIter  *iter,
313
						  GtkTreePath  *path);
314
GDK_AVAILABLE_IN_ALL
315 316
gboolean          gtk_tree_model_get_iter_from_string (GtkTreeModel *tree_model,
						       GtkTreeIter  *iter,
317
						       const gchar  *path_string);
318
GDK_AVAILABLE_IN_ALL
319 320
gchar *           gtk_tree_model_get_string_from_iter (GtkTreeModel *tree_model,
                                                       GtkTreeIter  *iter);
321
GDK_AVAILABLE_IN_ALL
322
gboolean          gtk_tree_model_get_iter_first  (GtkTreeModel *tree_model,
323
						  GtkTreeIter  *iter);
324
GDK_AVAILABLE_IN_ALL
325 326
GtkTreePath *     gtk_tree_model_get_path        (GtkTreeModel *tree_model,
						  GtkTreeIter  *iter);
327
GDK_AVAILABLE_IN_ALL
328 329 330 331
void              gtk_tree_model_get_value       (GtkTreeModel *tree_model,
						  GtkTreeIter  *iter,
						  gint          column,
						  GValue       *value);
332
GDK_AVAILABLE_IN_ALL
333 334
gboolean          gtk_tree_model_iter_previous   (GtkTreeModel *tree_model,
						  GtkTreeIter  *iter);
335
GDK_AVAILABLE_IN_ALL
336
gboolean          gtk_tree_model_iter_next       (GtkTreeModel *tree_model,
337
						  GtkTreeIter  *iter);
338
GDK_AVAILABLE_IN_ALL
339 340
gboolean          gtk_tree_model_iter_children   (GtkTreeModel *tree_model,
						  GtkTreeIter  *iter,
341
						  GtkTreeIter  *parent);
342
GDK_AVAILABLE_IN_ALL
343 344
gboolean          gtk_tree_model_iter_has_child  (GtkTreeModel *tree_model,
						  GtkTreeIter  *iter);
345
GDK_AVAILABLE_IN_ALL
346 347
gint              gtk_tree_model_iter_n_children (GtkTreeModel *tree_model,
						  GtkTreeIter  *iter);
348
GDK_AVAILABLE_IN_ALL
349 350 351
gboolean          gtk_tree_model_iter_nth_child  (GtkTreeModel *tree_model,
						  GtkTreeIter  *iter,
						  GtkTreeIter  *parent,
352
						  gint          n);
353
GDK_AVAILABLE_IN_ALL
354 355
gboolean          gtk_tree_model_iter_parent     (GtkTreeModel *tree_model,
						  GtkTreeIter  *iter,
356
						  GtkTreeIter  *child);
357
GDK_AVAILABLE_IN_ALL
358
void              gtk_tree_model_ref_node        (GtkTreeModel *tree_model,
359
						  GtkTreeIter  *iter);
360
GDK_AVAILABLE_IN_ALL
361
void              gtk_tree_model_unref_node      (GtkTreeModel *tree_model,
362
						  GtkTreeIter  *iter);
363
GDK_AVAILABLE_IN_ALL
364 365 366
void              gtk_tree_model_get             (GtkTreeModel *tree_model,
						  GtkTreeIter  *iter,
						  ...);
367
GDK_AVAILABLE_IN_ALL
368 369 370 371
void              gtk_tree_model_get_valist      (GtkTreeModel *tree_model,
						  GtkTreeIter  *iter,
						  va_list       var_args);

372

373
GDK_AVAILABLE_IN_ALL
374 375 376 377
void              gtk_tree_model_foreach         (GtkTreeModel            *model,
						  GtkTreeModelForeachFunc  func,
						  gpointer                 user_data);

378
/* Signals */
379
GDK_AVAILABLE_IN_ALL
380
void gtk_tree_model_row_changed           (GtkTreeModel *tree_model,
Jonathan Blandford's avatar
Jonathan Blandford committed
381 382
					   GtkTreePath  *path,
					   GtkTreeIter  *iter);
383
GDK_AVAILABLE_IN_ALL
384 385 386
void gtk_tree_model_row_inserted          (GtkTreeModel *tree_model,
					   GtkTreePath  *path,
					   GtkTreeIter  *iter);
387
GDK_AVAILABLE_IN_ALL
388 389 390
void gtk_tree_model_row_has_child_toggled (GtkTreeModel *tree_model,
					   GtkTreePath  *path,
					   GtkTreeIter  *iter);
391
GDK_AVAILABLE_IN_ALL
392 393
void gtk_tree_model_row_deleted           (GtkTreeModel *tree_model,
					   GtkTreePath  *path);
394
GDK_AVAILABLE_IN_ALL
395 396 397 398
void gtk_tree_model_rows_reordered        (GtkTreeModel *tree_model,
					   GtkTreePath  *path,
					   GtkTreeIter  *iter,
					   gint         *new_order);
399 400 401 402 403 404
GDK_AVAILABLE_IN_3_10
void gtk_tree_model_rows_reordered_with_length (GtkTreeModel *tree_model,
						GtkTreePath  *path,
						GtkTreeIter  *iter,
						gint         *new_order,
						gint          length);
405

406
G_END_DECLS
407 408

#endif /* __GTK_TREE_MODEL_H__ */