1 /* gtktreemodel.h 2 * Copyright (C) 2000 Red Hat, Inc., Jonathan Blandford <jrb@redhat.com> 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Library General Public 6 * License as published by the Free Software Foundation; either 7 * version 2 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Library General Public License for more details. 13 * 14 * You should have received a copy of the GNU Library General Public 15 * License along with this library. If not, see <http://www.gnu.org/licenses/>. 16 */ 17 18 #ifndef __GTK_TREE_MODEL_H__ 19 #define __GTK_TREE_MODEL_H__ 20 21 #if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION) 22 #error "Only <gtk/gtk.h> can be included directly." 23 #endif 24 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 #define GTK_TREE_MODEL(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_TREE_MODEL, GtkTreeModel)) 32 #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 #define GTK_TYPE_TREE_ITER (gtk_tree_iter_get_type ()) 36 #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 typedef struct _GtkTreeIter GtkTreeIter; 40 typedef struct _GtkTreePath GtkTreePath; 41 typedef struct _GtkTreeRowReference GtkTreeRowReference; 42 typedef struct _GtkTreeModel GtkTreeModel; /* Dummy typedef */ 43 typedef struct _GtkTreeModelIface GtkTreeModelIface; 44 45 /** 46 * GtkTreeModelForeachFunc: 47 * @model: the #GtkTreeModel being iterated 48 * @path: the current #GtkTreePath 49 * @iter: the current #GtkTreeIter 50 * @data: (closure): The user data passed to gtk_tree_model_foreach() 51 * 52 * Type of the callback passed to gtk_tree_model_foreach() to 53 * iterate over the rows in a tree model. 54 * 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 * GtkTreeModelFlags: 62 * @GTK_TREE_MODEL_ITERS_PERSIST: iterators survive all signals 63 * emitted by the tree 64 * @GTK_TREE_MODEL_LIST_ONLY: the model is a list only, and never 65 * has children 66 * 67 * These flags indicate various properties of a #GtkTreeModel. 68 * 69 * They are returned by gtk_tree_model_get_flags(), and must be 70 * static for the lifetime of the object. A more complete description 71 * of #GTK_TREE_MODEL_ITERS_PERSIST can be found in the overview of 72 * this section. 73 */ 74 typedef enum 75 { 76 GTK_TREE_MODEL_ITERS_PERSIST = 1 << 0, 77 GTK_TREE_MODEL_LIST_ONLY = 1 << 1 78 } GtkTreeModelFlags; 79 80 /** 81 * GtkTreeIter: 82 * @stamp: a unique stamp to catch invalid iterators 83 * @user_data: model-specific data 84 * @user_data2: model-specific data 85 * @user_data3: model-specific data 86 * 87 * The #GtkTreeIter is the primary structure 88 * for accessing a #GtkTreeModel. Models are expected to put a unique 89 * integer in the @stamp member, and put 90 * model-specific data in the three @user_data 91 * members. 92 */ 93 struct _GtkTreeIter 94 { 95 gint stamp; 96 gpointer user_data; 97 gpointer user_data2; 98 gpointer user_data3; 99 }; 100 101 /** 102 * GtkTreeModelIface: 103 * @row_changed: Signal emitted when a row in the model has changed. 104 * @row_inserted: Signal emitted when a new row has been inserted in 105 * the model. 106 * @row_has_child_toggled: Signal emitted when a row has gotten the 107 * first child row or lost its last child row. 108 * @row_deleted: Signal emitted when a row has been deleted. 109 * @rows_reordered: Signal emitted when the children of a node in the 110 * GtkTreeModel have been reordered. 111 * @get_flags: Get #GtkTreeModelFlags supported by this interface. 112 * @get_n_columns: Get the number of columns supported by the model. 113 * @get_column_type: Get the type of the column. 114 * @get_iter: Sets iter to a valid iterator pointing to path. 115 * @get_path: Gets a newly-created #GtkTreePath referenced by iter. 116 * @get_value: Initializes and sets value to that at column. 117 * @iter_next: Sets iter to point to the node following it at the 118 * current level. 119 * @iter_previous: Sets iter to point to the previous node at the 120 * current level. 121 * @iter_children: Sets iter to point to the first child of parent. 122 * @iter_has_child: %TRUE if iter has children, %FALSE otherwise. 123 * @iter_n_children: Gets the number of children that iter has. 124 * @iter_nth_child: Sets iter to be the child of parent, using the 125 * given index. 126 * @iter_parent: Sets iter to be the parent of child. 127 * @ref_node: Lets the tree ref the node. 128 * @unref_node: Lets the tree unref the node. 129 */ 130 struct _GtkTreeModelIface 131 { 132 /*< private >*/ 133 GTypeInterface g_iface; 134 135 /*< public >*/ 136 137 /* Signals */ 138 void (* row_changed) (GtkTreeModel *tree_model, 139 GtkTreePath *path, 140 GtkTreeIter *iter); 141 void (* row_inserted) (GtkTreeModel *tree_model, 142 GtkTreePath *path, 143 GtkTreeIter *iter); 144 void (* row_has_child_toggled) (GtkTreeModel *tree_model, 145 GtkTreePath *path, 146 GtkTreeIter *iter); 147 void (* row_deleted) (GtkTreeModel *tree_model, 148 GtkTreePath *path); 149 void (* rows_reordered) (GtkTreeModel *tree_model, 150 GtkTreePath *path, 151 GtkTreeIter *iter, 152 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 gboolean (* get_iter) (GtkTreeModel *tree_model, 161 GtkTreeIter *iter, 162 GtkTreePath *path); 163 GtkTreePath *(* get_path) (GtkTreeModel *tree_model, 164 GtkTreeIter *iter); 165 void (* get_value) (GtkTreeModel *tree_model, 166 GtkTreeIter *iter, 167 gint column, 168 GValue *value); 169 gboolean (* iter_next) (GtkTreeModel *tree_model, 170 GtkTreeIter *iter); 171 gboolean (* iter_previous) (GtkTreeModel *tree_model, 172 GtkTreeIter *iter); 173 gboolean (* iter_children) (GtkTreeModel *tree_model, 174 GtkTreeIter *iter, 175 GtkTreeIter *parent); 176 gboolean (* iter_has_child) (GtkTreeModel *tree_model, 177 GtkTreeIter *iter); 178 gint (* iter_n_children) (GtkTreeModel *tree_model, 179 GtkTreeIter *iter); 180 gboolean (* iter_nth_child) (GtkTreeModel *tree_model, 181 GtkTreeIter *iter, 182 GtkTreeIter *parent, 183 gint n); 184 gboolean (* iter_parent) (GtkTreeModel *tree_model, 185 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 GtkTreePath *gtk_tree_path_new_from_indices (gint first_index, 201 ...); 202 GDK_AVAILABLE_IN_3_12 203 GtkTreePath *gtk_tree_path_new_from_indicesv (gint *indices, 204 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 gint *gtk_tree_path_get_indices (GtkTreePath *path); 219 220 GDK_AVAILABLE_IN_ALL 221 gint *gtk_tree_path_get_indices_with_depth (GtkTreePath *path, 222 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 229 GType gtk_tree_path_get_type (void) G_GNUC_CONST; 230 GDK_AVAILABLE_IN_ALL 231 gint gtk_tree_path_compare (const GtkTreePath *a, 232 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 void gtk_tree_path_down (GtkTreePath *path); 241 242 GDK_AVAILABLE_IN_ALL 243 gboolean gtk_tree_path_is_ancestor (GtkTreePath *path, 244 GtkTreePath *descendant); 245 GDK_AVAILABLE_IN_ALL 246 gboolean gtk_tree_path_is_descendant (GtkTreePath *path, 247 GtkTreePath *ancestor); 248 249 /** 250 * GtkTreeRowReference: 251 * 252 * A GtkTreeRowReference tracks model changes so that it always refers to the 253 * same row (a #GtkTreePath refers to a position, not a fixed row). Create a 254 * new GtkTreeRowReference with gtk_tree_row_reference_new(). 255 */ 256 257 GDK_AVAILABLE_IN_ALL 258 GType gtk_tree_row_reference_get_type (void) G_GNUC_CONST; 259 GDK_AVAILABLE_IN_ALL 260 GtkTreeRowReference *gtk_tree_row_reference_new (GtkTreeModel *model, 261 GtkTreePath *path); 262 GDK_AVAILABLE_IN_ALL 263 GtkTreeRowReference *gtk_tree_row_reference_new_proxy (GObject *proxy, 264 GtkTreeModel *model, 265 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 void gtk_tree_row_reference_free (GtkTreeRowReference *reference); 276 /* These two functions are only needed if you created the row reference with a 277 * proxy object */ 278 GDK_AVAILABLE_IN_ALL 279 void gtk_tree_row_reference_inserted (GObject *proxy, 280 GtkTreePath *path); 281 GDK_AVAILABLE_IN_ALL 282 void gtk_tree_row_reference_deleted (GObject *proxy, 283 GtkTreePath *path); 284 GDK_AVAILABLE_IN_ALL 285 void gtk_tree_row_reference_reordered (GObject *proxy, 286 GtkTreePath *path, 287 GtkTreeIter *iter, 288 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 296 GType gtk_tree_iter_get_type (void) G_GNUC_CONST; 297 298 GDK_AVAILABLE_IN_ALL 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 gboolean gtk_tree_model_get_iter (GtkTreeModel *tree_model, 312 GtkTreeIter *iter, 313 GtkTreePath *path); 314 GDK_AVAILABLE_IN_ALL 315 gboolean gtk_tree_model_get_iter_from_string (GtkTreeModel *tree_model, 316 GtkTreeIter *iter, 317 const gchar *path_string); 318 GDK_AVAILABLE_IN_ALL 319 gchar * gtk_tree_model_get_string_from_iter (GtkTreeModel *tree_model, 320 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 GtkTreePath * gtk_tree_model_get_path (GtkTreeModel *tree_model, 326 GtkTreeIter *iter); 327 GDK_AVAILABLE_IN_ALL 328 void gtk_tree_model_get_value (GtkTreeModel *tree_model, 329 GtkTreeIter *iter, 330 gint column, 331 GValue *value); 332 GDK_AVAILABLE_IN_ALL 333 gboolean gtk_tree_model_iter_previous (GtkTreeModel *tree_model, 334 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 gboolean gtk_tree_model_iter_children (GtkTreeModel *tree_model, 340 GtkTreeIter *iter, 341 GtkTreeIter *parent); 342 GDK_AVAILABLE_IN_ALL 343 gboolean gtk_tree_model_iter_has_child (GtkTreeModel *tree_model, 344 GtkTreeIter *iter); 345 GDK_AVAILABLE_IN_ALL 346 gint gtk_tree_model_iter_n_children (GtkTreeModel *tree_model, 347 GtkTreeIter *iter); 348 GDK_AVAILABLE_IN_ALL 349 gboolean gtk_tree_model_iter_nth_child (GtkTreeModel *tree_model, 350 GtkTreeIter *iter, 351 GtkTreeIter *parent, 352 gint n); 353 GDK_AVAILABLE_IN_ALL 354 gboolean gtk_tree_model_iter_parent (GtkTreeModel *tree_model, 355 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 void gtk_tree_model_get (GtkTreeModel *tree_model, 365 GtkTreeIter *iter, 366 ...); 367 GDK_AVAILABLE_IN_ALL 368 void gtk_tree_model_get_valist (GtkTreeModel *tree_model, 369 GtkTreeIter *iter, 370 va_list var_args); 371 372 373 GDK_AVAILABLE_IN_ALL 374 void gtk_tree_model_foreach (GtkTreeModel *model, 375 GtkTreeModelForeachFunc func, 376 gpointer user_data); 377 378 /* Signals */ 379 GDK_AVAILABLE_IN_ALL 380 void gtk_tree_model_row_changed (GtkTreeModel *tree_model, 381 GtkTreePath *path, 382 GtkTreeIter *iter); 383 GDK_AVAILABLE_IN_ALL 384 void gtk_tree_model_row_inserted (GtkTreeModel *tree_model, 385 GtkTreePath *path, 386 GtkTreeIter *iter); 387 GDK_AVAILABLE_IN_ALL 388 void gtk_tree_model_row_has_child_toggled (GtkTreeModel *tree_model, 389 GtkTreePath *path, 390 GtkTreeIter *iter); 391 GDK_AVAILABLE_IN_ALL 392 void gtk_tree_model_row_deleted (GtkTreeModel *tree_model, 393 GtkTreePath *path); 394 GDK_AVAILABLE_IN_ALL 395 void gtk_tree_model_rows_reordered (GtkTreeModel *tree_model, 396 GtkTreePath *path, 397 GtkTreeIter *iter, 398 gint *new_order); 399 GDK_AVAILABLE_IN_3_10 400 void gtk_tree_model_rows_reordered_with_length (GtkTreeModel *tree_model, 401 GtkTreePath *path, 402 GtkTreeIter *iter, 403 gint *new_order, 404 gint length); 405 406 G_END_DECLS 407 408 #endif /* __GTK_TREE_MODEL_H__ */ 409