2 * This file is part of gtkD.
4 * gtkD is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation; either version 2.1 of the License, or
7 * (at your option) any later version.
9 * gtkD 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
12 * GNU Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with gtkD; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 // generated automatically - do not change
20 // find conversion definition on APILookup.txt
21 // implement new conversion functionalities on the wrap.utils pakage
24 * Conversion parameters:
44 * - gtk_tree_path_new_first
50 * - GtkTreePath* -> TreePath
61 import tango
.io
.Stdout
; // use the tango loging?
65 private import gtkc
.gtktypes
;
67 private import gtkc
.gtk
;
70 private import glib
.Str
;
71 private import gtk
.TreePath
;
72 private import glib
.Str
;
79 * The GtkTreeModel interface defines a generic tree interface for use by
80 * the GtkTreeView widget. It is an abstract interface, and is designed
81 * to be usable with any appropriate data structure. The programmer just
82 * has to implement this interface on their own data type for it to be
83 * viewable by a GtkTreeView widget.
84 * The model is represented as a hierarchical tree of strongly-typed,
85 * columned data. In other words, the model can be seen as a tree where
86 * every node has different values depending on which column is being
87 * queried. The type of data found in a column is determined by using the
88 * GType system (ie. G_TYPE_INT, GTK_TYPE_BUTTON, G_TYPE_POINTER, etc.).
89 * The types are homogeneous per column across all nodes. It is important
90 * to note that this interface only provides a way of examining a model and
91 * observing changes. The implementation of each individual model decides
92 * how and if changes are made.
93 * In order to make life simpler for programmers who do not need to write
94 * their own specialized model, two generic models are provided the
95 * GtkTreeStore and the GtkListStore. To use these, the developer simply
96 * pushes data into these models as necessary. These models provide the
97 * data structure as well as all appropriate tree interfaces. As a result,
98 * implementing drag and drop, sorting, and storing data is trivial. For
99 * the vast majority of trees and lists, these two models are sufficient.
100 * Models are accessed on a node/column level of granularity. One can
101 * query for the value of a model at a certain node and a certain column
102 * on that node. There are two structures used to reference a particular
103 * node in a model. They are the GtkTreePath and the GtkTreeIter
105 * Most of the interface consists of operations on a GtkTreeIter.
106 * A path is essentially a potential node. It is a location on a model
107 * that may or may not actually correspond to a node on a specific model.
108 * The GtkTreePath struct can be converted into either an array of
109 * unsigned integers or a string. The string form is a list of numbers
110 * separated by a colon. Each number refers to the offset at that level.
111 * Thus, the path 0 refers to the root node and the path
112 * 2:4 refers to the fifth child of the third node.
113 * By contrast, a GtkTreeIter is a reference to a specific node on a
114 * specific model. It is a generic struct with an integer and three
115 * generic pointers. These are filled in by the model in a model-specific
116 * way. One can convert a path to an iterator by calling
117 * gtk_tree_model_get_iter(). These iterators are the primary way of
118 * accessing a model and are similar to the iterators used by
119 * GtkTextBuffer. They are generally statically allocated on the stack and
120 * only used for a short time. The model interface defines a set of
121 * operations using them for navigating the model.
122 * It is expected that models fill in the iterator with private data. For
123 * example, the GtkListStore model, which is internally a simple linked
124 * list, stores a list node in one of the pointers. The GtkTreeModelSort
125 * stores an array and an offset in two of the pointers. Additionally,
126 * there is an integer field. This field is generally filled with a unique
127 * stamp per model. This stamp is for catching errors resulting from using
128 * invalid iterators with a model.
129 * The lifecycle of an iterator can be a little confusing at first.
130 * Iterators are expected to always be valid for as long as the model is
131 * unchanged (and doesn't emit a signal). The model is considered to own
132 * all outstanding iterators and nothing needs to be done to free them from
133 * the user's point of view. Additionally, some models guarantee that an
134 * iterator is valid for as long as the node it refers to is valid (most
135 * notably the GtkTreeStore and GtkListStore). Although generally
136 * uninteresting, as one always has to allow for the case where iterators
137 * do not persist beyond a signal, some very important performance
138 * enhancements were made in the sort model. As a result, the
139 * GTK_TREE_MODEL_ITERS_PERSIST flag was added to indicate this behavior.
140 * To help show some common operation of a model, some examples are
141 * provided. The first example shows three ways of getting the iter at the
142 * location 3:2:5. While the first method shown is easier,
143 * the second is much more common, as you often get paths from callbacks.
144 * Example1.Acquiring a GtkTreeIter
145 * /+* Three ways of getting the iter pointing to the location
150 * GtkTreeIter parent_iter;
151 * /+* get the iterator from a string +/
152 * gtk_tree_model_get_iter_from_string (model, iter, "3:2:5");
153 * /+* get the iterator from a path +/
154 * path = gtk_tree_path_new_from_string ("3:2:5");
155 * gtk_tree_model_get_iter (model, iter, path);
156 * gtk_tree_path_free (path);
157 * /+* walk the tree to find the iterator +/
158 * gtk_tree_model_iter_nth_child (model, iter, NULL, 3);
159 * parent_iter = iter;
160 * gtk_tree_model_iter_nth_child (model, iter, parent_iter, 2);
161 * parent_iter = iter;
162 * gtk_tree_model_iter_nth_child (model, iter, parent_iter, 5);
164 * This second example shows a quick way of iterating through a list and
165 * getting a string and an integer from each row. The
166 * populate_model function used below is not shown, as
167 * it is specific to the GtkListStore. For information on how to write
168 * such a function, see the GtkListStore documentation.
169 * Example2.Reading data from a GtkTreeModel
177 * GtkTreeModel *list_store;
180 * gint row_count = 0;
181 * /+* make a new list_store +/
182 * list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT);
183 * /+* Fill the list store with data +/
184 * populate_model (list_store);
185 * /+* Get the first iter in the list +/
186 * valid = gtk_tree_model_get_iter_first (list_store, iter);
189 * /+* Walk through the list, reading each row +/
192 * /+* Make sure you terminate calls to gtk_tree_model_get()
193 * * with a '-1' value
195 * gtk_tree_model_get (list_store, iter,
196 * STRING_COLUMN, str_data,
197 * INT_COLUMN, int_data,
199 * /+* Do something with the data +/
200 * g_print ("Row %d: (%s,%d)\n", row_count, str_data, int_data);
203 * valid = gtk_tree_model_iter_next (list_store, iter);
207 public class TreePath
210 /** the main Gtk struct */
211 protected GtkTreePath
* gtkTreePath
;
214 public GtkTreePath
* getTreePathStruct()
220 /** the main Gtk struct as a void* */
221 protected void* getStruct()
223 return cast(void*)gtkTreePath
;
227 * Sets our main struct and passes it to the parent class
229 public this (GtkTreePath
* gtkTreePath
)
233 if ( gtkTreePath
is null )
238 Stdout("struct gtkTreePath is null on constructor").newline
;
242 printf("struct gtkTreePath is null on constructor");
249 assert(gtkTreePath
!is null, "struct gtkTreePath is null on constructor");
251 this.gtkTreePath
= gtkTreePath
;
255 * Creates a new GtkTreePath. This structure refers to a row.
256 * if firstRow is true this is the string representation of this path is "0"
258 * A newly created GtkTreePath.
260 public this (bool firstRow
=false)
264 // GtkTreePath* gtk_tree_path_new_first (void);
265 this(cast(GtkTreePath
*)gtk_tree_path_new_first() );
269 // GtkTreePath* gtk_tree_path_new (void);
270 this(cast(GtkTreePath
*)gtk_tree_path_new() );
277 // imports for the signal processing
278 private import gobject
.Signals
;
279 private import gtkc
.gdktypes
;
280 int[char[]] connectedSignals
;
282 void delegate(TreePath
, GtkTreeIter
*, TreePath
)[] onRowChangedListeners
;
283 void addOnRowChanged(void delegate(TreePath
, GtkTreeIter
*, TreePath
) dlg
, ConnectFlags connectFlags
=cast(ConnectFlags
)0)
285 if ( !("row-changed" in connectedSignals
) )
290 cast(GCallback
)&callBackRowChanged
,
294 connectedSignals
["row-changed"] = 1;
296 onRowChangedListeners
~= dlg
;
298 extern(C
) static void callBackRowChanged(GtkTreeModel
* treeModelStruct
, GtkTreePath
* path
, GtkTreeIter
* iter
, TreePath treePath
)
300 bool consumed
= false;
302 foreach ( void delegate(TreePath
, GtkTreeIter
*, TreePath
) dlg
; treePath
.onRowChangedListeners
)
304 dlg(new TreePath(path
), iter
, treePath
);
310 void delegate(TreePath
, TreePath
)[] onRowDeletedListeners
;
311 void addOnRowDeleted(void delegate(TreePath
, TreePath
) dlg
, ConnectFlags connectFlags
=cast(ConnectFlags
)0)
313 if ( !("row-deleted" in connectedSignals
) )
318 cast(GCallback
)&callBackRowDeleted
,
322 connectedSignals
["row-deleted"] = 1;
324 onRowDeletedListeners
~= dlg
;
326 extern(C
) static void callBackRowDeleted(GtkTreeModel
* treeModelStruct
, GtkTreePath
* path
, TreePath treePath
)
328 bool consumed
= false;
330 foreach ( void delegate(TreePath
, TreePath
) dlg
; treePath
.onRowDeletedListeners
)
332 dlg(new TreePath(path
), treePath
);
338 void delegate(TreePath
, GtkTreeIter
*, TreePath
)[] onRowHasChildToggledListeners
;
339 void addOnRowHasChildToggled(void delegate(TreePath
, GtkTreeIter
*, TreePath
) dlg
, ConnectFlags connectFlags
=cast(ConnectFlags
)0)
341 if ( !("row-has-child-toggled" in connectedSignals
) )
345 "row-has-child-toggled",
346 cast(GCallback
)&callBackRowHasChildToggled
,
350 connectedSignals
["row-has-child-toggled"] = 1;
352 onRowHasChildToggledListeners
~= dlg
;
354 extern(C
) static void callBackRowHasChildToggled(GtkTreeModel
* treeModelStruct
, GtkTreePath
* path
, GtkTreeIter
* iter
, TreePath treePath
)
356 bool consumed
= false;
358 foreach ( void delegate(TreePath
, GtkTreeIter
*, TreePath
) dlg
; treePath
.onRowHasChildToggledListeners
)
360 dlg(new TreePath(path
), iter
, treePath
);
366 void delegate(TreePath
, GtkTreeIter
*, TreePath
)[] onRowInsertedListeners
;
367 void addOnRowInserted(void delegate(TreePath
, GtkTreeIter
*, TreePath
) dlg
, ConnectFlags connectFlags
=cast(ConnectFlags
)0)
369 if ( !("row-inserted" in connectedSignals
) )
374 cast(GCallback
)&callBackRowInserted
,
378 connectedSignals
["row-inserted"] = 1;
380 onRowInsertedListeners
~= dlg
;
382 extern(C
) static void callBackRowInserted(GtkTreeModel
* treeModelStruct
, GtkTreePath
* path
, GtkTreeIter
* iter
, TreePath treePath
)
384 bool consumed
= false;
386 foreach ( void delegate(TreePath
, GtkTreeIter
*, TreePath
) dlg
; treePath
.onRowInsertedListeners
)
388 dlg(new TreePath(path
), iter
, treePath
);
394 void delegate(TreePath
, GtkTreeIter
*, gpointer
, TreePath
)[] onRowsReorderedListeners
;
395 void addOnRowsReordered(void delegate(TreePath
, GtkTreeIter
*, gpointer
, TreePath
) dlg
, ConnectFlags connectFlags
=cast(ConnectFlags
)0)
397 if ( !("rows-reordered" in connectedSignals
) )
402 cast(GCallback
)&callBackRowsReordered
,
406 connectedSignals
["rows-reordered"] = 1;
408 onRowsReorderedListeners
~= dlg
;
410 extern(C
) static void callBackRowsReordered(GtkTreeModel
* treeModelStruct
, GtkTreePath
* path
, GtkTreeIter
* iter
, gpointer arg3
, TreePath treePath
)
412 bool consumed
= false;
414 foreach ( void delegate(TreePath
, GtkTreeIter
*, gpointer
, TreePath
) dlg
; treePath
.onRowsReorderedListeners
)
416 dlg(new TreePath(path
), iter
, arg3
, treePath
);
432 * Creates a new GtkTreePath initialized to path. path is expected to be a
433 * colon separated list of numbers. For example, the string "10:4:0" would
434 * create a path of depth 3 pointing to the 11th child of the root node, the 5th
435 * child of that 11th child, and the 1st child of that 5th child. If an invalid
436 * path string is passed in, NULL is returned.
438 * The string representation of a path.
440 * A newly-created GtkTreePath, or NULL
442 public this (char[] path
)
444 // GtkTreePath* gtk_tree_path_new_from_string (const gchar *path);
445 this(cast(GtkTreePath
*)gtk_tree_path_new_from_string(Str
.toStringz(path
)) );
449 * Creates a new path with first_index and varargs as indices.
453 * list of integers terminated by -1
455 * A newly created GtkTreePath.
458 public this (int firstIndex
, ... )
460 // GtkTreePath* gtk_tree_path_new_from_indices (gint first_index, ...);
461 this(cast(GtkTreePath
*)gtk_tree_path_new_from_indices(firstIndex
) );
465 * Generates a string representation of the path. This string is a ':'
466 * separated list of numbers. For example, "4:10:0:3" would be an acceptable return value for this string.
470 * A newly-allocated string. Must be freed with g_free().
472 public char[] toString()
474 // gchar* gtk_tree_path_to_string (GtkTreePath *path);
475 return Str
.toString(gtk_tree_path_to_string(gtkTreePath
) );
481 * Appends a new index to a path. As a result, the depth of the path is
488 public void appendIndex(int index
)
490 // void gtk_tree_path_append_index (GtkTreePath *path, gint index_);
491 gtk_tree_path_append_index(gtkTreePath
, index
);
495 * Prepends a new index to a path. As a result, the depth of the path is
502 public void prependIndex(int index
)
504 // void gtk_tree_path_prepend_index (GtkTreePath *path, gint index_);
505 gtk_tree_path_prepend_index(gtkTreePath
, index
);
509 * Returns the current depth of path.
515 public int getDepth()
517 // gint gtk_tree_path_get_depth (GtkTreePath *path);
518 return gtk_tree_path_get_depth(gtkTreePath
);
522 * Returns the current indices of path. This is an array of integers, each
523 * representing a node in a tree. This value should not be freed.
527 * The current indices, or NULL.
529 public int* getIndices()
531 // gint* gtk_tree_path_get_indices (GtkTreePath *path);
532 return gtk_tree_path_get_indices(gtkTreePath
);
542 // void gtk_tree_path_free (GtkTreePath *path);
543 gtk_tree_path_free(gtkTreePath
);
547 * Creates a new GtkTreePath as a copy of path.
553 public TreePath
copy()
555 // GtkTreePath* gtk_tree_path_copy (const GtkTreePath *path);
556 return new TreePath( gtk_tree_path_copy(gtkTreePath
) );
560 * Compares two paths. If a appears before b in a tree, then -1 is returned.
561 * If b appears before a, then 1 is returned. If the two nodes are equal,
562 * then 0 is returned.
566 * A GtkTreePath to compare with.
568 * The relative positions of a and b
570 public int compare(TreePath b
)
572 // gint gtk_tree_path_compare (const GtkTreePath *a, const GtkTreePath *b);
573 return gtk_tree_path_compare(gtkTreePath
, (b
is null) ?
null : b
.getTreePathStruct());
577 * Moves the path to point to the next node at the current depth.
583 // void gtk_tree_path_next (GtkTreePath *path);
584 gtk_tree_path_next(gtkTreePath
);
588 * Moves the path to point to the previous node at the current depth,
593 * TRUE if path has a previous node, and the move was made.
597 // gboolean gtk_tree_path_prev (GtkTreePath *path);
598 return gtk_tree_path_prev(gtkTreePath
);
602 * Moves the path to point to its parent node, if it has a parent.
606 * TRUE if path has a parent, and the move was made.
610 // gboolean gtk_tree_path_up (GtkTreePath *path);
611 return gtk_tree_path_up(gtkTreePath
);
615 * Moves path to point to the first child of the current path.
621 // void gtk_tree_path_down (GtkTreePath *path);
622 gtk_tree_path_down(gtkTreePath
);
626 * Returns TRUE if descendant is a descendant of path.
630 * another GtkTreePath
632 * TRUE if descendant is contained inside path
634 public int isAncestor(TreePath descendant
)
636 // gboolean gtk_tree_path_is_ancestor (GtkTreePath *path, GtkTreePath *descendant);
637 return gtk_tree_path_is_ancestor(gtkTreePath
, (descendant
is null) ?
null : descendant
.getTreePathStruct());
641 * Returns TRUE if path is a descendant of ancestor.
645 * another GtkTreePath
647 * TRUE if ancestor contains path somewhere below it
649 public int isDescendant(TreePath ancestor
)
651 // gboolean gtk_tree_path_is_descendant (GtkTreePath *path, GtkTreePath *ancestor);
652 return gtk_tree_path_is_descendant(gtkTreePath
, (ancestor
is null) ?
null : ancestor
.getTreePathStruct());