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:
51 * - GtkTreeIter* -> TreeIter
62 import tango
.io
.Stdout
; // use the tango loging?
66 private import gtkc
.gtktypes
;
68 private import gtkc
.gtk
;
71 private import glib
.Str
;
72 private import gtk
.TreeIter
;
73 private import gtk
.TreeModel
;
74 private import gtk
.TreePath
;
75 private import gtk
.TreeIterError
;
76 private import gobject
.Value
;;
83 * The GtkTreeModel interface defines a generic tree interface for use by
84 * the GtkTreeView widget. It is an abstract interface, and is designed
85 * to be usable with any appropriate data structure. The programmer just
86 * has to implement this interface on their own data type for it to be
87 * viewable by a GtkTreeView widget.
88 * The model is represented as a hierarchical tree of strongly-typed,
89 * columned data. In other words, the model can be seen as a tree where
90 * every node has different values depending on which column is being
91 * queried. The type of data found in a column is determined by using the
92 * GType system (ie. G_TYPE_INT, GTK_TYPE_BUTTON, G_TYPE_POINTER, etc.).
93 * The types are homogeneous per column across all nodes. It is important
94 * to note that this interface only provides a way of examining a model and
95 * observing changes. The implementation of each individual model decides
96 * how and if changes are made.
97 * In order to make life simpler for programmers who do not need to write
98 * their own specialized model, two generic models are provided the
99 * GtkTreeStore and the GtkListStore. To use these, the developer simply
100 * pushes data into these models as necessary. These models provide the
101 * data structure as well as all appropriate tree interfaces. As a result,
102 * implementing drag and drop, sorting, and storing data is trivial. For
103 * the vast majority of trees and lists, these two models are sufficient.
104 * Models are accessed on a node/column level of granularity. One can
105 * query for the value of a model at a certain node and a certain column
106 * on that node. There are two structures used to reference a particular
107 * node in a model. They are the GtkTreePath and the GtkTreeIter
109 * Most of the interface consists of operations on a GtkTreeIter.
110 * A path is essentially a potential node. It is a location on a model
111 * that may or may not actually correspond to a node on a specific model.
112 * The GtkTreePath struct can be converted into either an array of
113 * unsigned integers or a string. The string form is a list of numbers
114 * separated by a colon. Each number refers to the offset at that level.
115 * Thus, the path 0 refers to the root node and the path
116 * 2:4 refers to the fifth child of the third node.
117 * By contrast, a GtkTreeIter is a reference to a specific node on a
118 * specific model. It is a generic struct with an integer and three
119 * generic pointers. These are filled in by the model in a model-specific
120 * way. One can convert a path to an iterator by calling
121 * gtk_tree_model_get_iter(). These iterators are the primary way of
122 * accessing a model and are similar to the iterators used by
123 * GtkTextBuffer. They are generally statically allocated on the stack and
124 * only used for a short time. The model interface defines a set of
125 * operations using them for navigating the model.
126 * It is expected that models fill in the iterator with private data. For
127 * example, the GtkListStore model, which is internally a simple linked
128 * list, stores a list node in one of the pointers. The GtkTreeModelSort
129 * stores an array and an offset in two of the pointers. Additionally,
130 * there is an integer field. This field is generally filled with a unique
131 * stamp per model. This stamp is for catching errors resulting from using
132 * invalid iterators with a model.
133 * The lifecycle of an iterator can be a little confusing at first.
134 * Iterators are expected to always be valid for as long as the model is
135 * unchanged (and doesn't emit a signal). The model is considered to own
136 * all outstanding iterators and nothing needs to be done to free them from
137 * the user's point of view. Additionally, some models guarantee that an
138 * iterator is valid for as long as the node it refers to is valid (most
139 * notably the GtkTreeStore and GtkListStore). Although generally
140 * uninteresting, as one always has to allow for the case where iterators
141 * do not persist beyond a signal, some very important performance
142 * enhancements were made in the sort model. As a result, the
143 * GTK_TREE_MODEL_ITERS_PERSIST flag was added to indicate this behavior.
144 * To help show some common operation of a model, some examples are
145 * provided. The first example shows three ways of getting the iter at the
146 * location 3:2:5. While the first method shown is easier,
147 * the second is much more common, as you often get paths from callbacks.
148 * Example1.Acquiring a GtkTreeIter
149 * /+* Three ways of getting the iter pointing to the location
154 * GtkTreeIter parent_iter;
155 * /+* get the iterator from a string +/
156 * gtk_tree_model_get_iter_from_string (model, iter, "3:2:5");
157 * /+* get the iterator from a path +/
158 * path = gtk_tree_path_new_from_string ("3:2:5");
159 * gtk_tree_model_get_iter (model, iter, path);
160 * gtk_tree_path_free (path);
161 * /+* walk the tree to find the iterator +/
162 * gtk_tree_model_iter_nth_child (model, iter, NULL, 3);
163 * parent_iter = iter;
164 * gtk_tree_model_iter_nth_child (model, iter, parent_iter, 2);
165 * parent_iter = iter;
166 * gtk_tree_model_iter_nth_child (model, iter, parent_iter, 5);
168 * This second example shows a quick way of iterating through a list and
169 * getting a string and an integer from each row. The
170 * populate_model function used below is not shown, as
171 * it is specific to the GtkListStore. For information on how to write
172 * such a function, see the GtkListStore documentation.
173 * Example2.Reading data from a GtkTreeModel
181 * GtkTreeModel *list_store;
184 * gint row_count = 0;
185 * /+* make a new list_store +/
186 * list_store = gtk_list_store_new (N_COLUMNS, G_TYPE_STRING, G_TYPE_INT);
187 * /+* Fill the list store with data +/
188 * populate_model (list_store);
189 * /+* Get the first iter in the list +/
190 * valid = gtk_tree_model_get_iter_first (list_store, iter);
193 * /+* Walk through the list, reading each row +/
196 * /+* Make sure you terminate calls to gtk_tree_model_get()
197 * * with a '-1' value
199 * gtk_tree_model_get (list_store, iter,
200 * STRING_COLUMN, str_data,
201 * INT_COLUMN, int_data,
203 * /+* Do something with the data +/
204 * g_print ("Row %d: (%s,%d)\n", row_count, str_data, int_data);
207 * valid = gtk_tree_model_iter_next (list_store, iter);
211 public class TreeIter
214 /** the main Gtk struct */
215 protected GtkTreeIter
* gtkTreeIter
;
218 public GtkTreeIter
* getTreeIterStruct()
224 /** the main Gtk struct as a void* */
225 protected void* getStruct()
227 return cast(void*)gtkTreeIter
;
231 * Sets our main struct and passes it to the parent class
233 public this (GtkTreeIter
* gtkTreeIter
)
237 if ( gtkTreeIter
is null )
242 Stdout("struct gtkTreeIter is null on constructor").newline
;
246 printf("struct gtkTreeIter is null on constructor");
253 assert(gtkTreeIter
!is null, "struct gtkTreeIter is null on constructor");
255 this.gtkTreeIter
= gtkTreeIter
;
259 * this will be set only when the iter
260 * is created from the model.
262 GtkTreeModel
*gtkTreeModel
;
264 public void setModel(GtkTreeModel
*gtkTreeModel
)
266 this.gtkTreeModel
= gtkTreeModel
;
269 public void setModel(TreeModel treeModel
)
271 this.gtkTreeModel
= treeModel
.getTreeModelStruct();
274 public this(TreeModel treeModel
, TreePath treePath
)
278 if ( gtk_tree_model_get_iter_from_string(
279 treeModel
.getTreeModelStruct(),
280 getTreeIterStruct(), Str
.toStringz(treePath
.toString())) )
287 * creates a new tree iteractor.
288 * used TreeView.createIter and TreeView.append() to create iteractor for a tree or list
292 this(new GtkTreeIter
);
302 void getValue(int column
, Value value
)
304 if ( gtkTreeModel
is null )
306 throw new TreeIterError("getValue","Tree model not set");
308 gtk_tree_model_get_value(gtkTreeModel
, gtkTreeIter
, column
, value
.getValueStruct());
312 * Get the value of a column as a string
313 * @para column the column number
314 * @return a string representing the value of the column
316 char[] getValueString(int column
)
318 if ( gtkTreeModel
is null )
320 throw new TreeIterError("getValueString","Tree model not set");
322 Value value
= new Value();
323 gtk_tree_model_get_value(gtkTreeModel
, gtkTreeIter
, column
, value
.getValueStruct());
324 //printf("TreeIter.getValuaString = %.*s\n", value.getString().toString());
325 return value
.getString();
329 * Get the value of a column as an int
330 * @para column the column number
331 * @return a string representing the value of the column
333 int getValueInt(int column
)
335 if ( gtkTreeModel
is null )
337 throw new TreeIterError("getValueInt", "Tree model not set");
339 Value value
= new Value();
340 gtk_tree_model_get_value(gtkTreeModel
, gtkTreeIter
, column
, value
.getValueStruct());
341 return value
.getInt();
344 TreePath
getTreePath()
346 if ( gtkTreeModel
is null )
348 throw new TreeIterError("getTreePath","Tree model not set");
350 return new TreePath(gtk_tree_model_get_path(gtkTreeModel
, gtkTreeIter
));
354 * This return the path visible to the user.
356 char[] getVisiblePath(char[] separator
)
359 if ( gtkTreeModel
is null )
361 throw new TreeIterError("getVisiblePath", "Tree model not set");
364 vPath
= getValueString(0);
365 TreeIter parent
= getParent();
366 while ( parent
!is null )
368 //printf("TreeIter.getVisiblePath parent = %.*s\n",parent.getValueString(0).toString());
369 vPath
= parent
.getValueString(0) ~ separator
~ vPath
;
370 parent
= parent
.getParent();
373 //printf("TreeIter.getVisiblePath = %.*s\n", vPath.toString());
379 * Gets the parent of this iter
381 * @return the parent iter or null if can't get parent or an error occured
385 if ( gtkTreeModel
is null )
387 throw new TreeIterError("getParent", "Tree model not set");
389 TreeIter parent
= new TreeIter();
390 bool gotParent
= gtk_tree_model_iter_parent(gtkTreeModel
, parent
.getTreeIterStruct(), gtkTreeIter
) == 0 ?
false : true;
395 parent
.setModel(gtkTreeModel
);
400 TreeIter
getGrandParent()
402 if ( gtkTreeModel
is null )
404 throw new TreeIterError("getGrandParent", "Tree model not set");
406 TreeIter grandParent
= this;
407 TreeIter parent
= grandParent
.getParent();
408 while ( parent
!is null )
410 grandParent
= parent
;
411 parent
= grandParent
.getParent();
424 // imports for the signal processing
425 private import gobject
.Signals
;
426 private import gtkc
.gdktypes
;
427 int[char[]] connectedSignals
;
429 void delegate(GtkTreePath
*, TreeIter
, TreeIter
)[] onRowChangedListeners
;
430 void addOnRowChanged(void delegate(GtkTreePath
*, TreeIter
, TreeIter
) dlg
, ConnectFlags connectFlags
=cast(ConnectFlags
)0)
432 if ( !("row-changed" in connectedSignals
) )
437 cast(GCallback
)&callBackRowChanged
,
441 connectedSignals
["row-changed"] = 1;
443 onRowChangedListeners
~= dlg
;
445 extern(C
) static void callBackRowChanged(GtkTreeModel
* treeModelStruct
, GtkTreePath
* path
, GtkTreeIter
* iter
, TreeIter treeIter
)
447 bool consumed
= false;
449 foreach ( void delegate(GtkTreePath
*, TreeIter
, TreeIter
) dlg
; treeIter
.onRowChangedListeners
)
451 dlg(path
, new TreeIter(iter
), treeIter
);
457 void delegate(GtkTreePath
*, TreeIter
)[] onRowDeletedListeners
;
458 void addOnRowDeleted(void delegate(GtkTreePath
*, TreeIter
) dlg
, ConnectFlags connectFlags
=cast(ConnectFlags
)0)
460 if ( !("row-deleted" in connectedSignals
) )
465 cast(GCallback
)&callBackRowDeleted
,
469 connectedSignals
["row-deleted"] = 1;
471 onRowDeletedListeners
~= dlg
;
473 extern(C
) static void callBackRowDeleted(GtkTreeModel
* treeModelStruct
, GtkTreePath
* path
, TreeIter treeIter
)
475 bool consumed
= false;
477 foreach ( void delegate(GtkTreePath
*, TreeIter
) dlg
; treeIter
.onRowDeletedListeners
)
485 void delegate(GtkTreePath
*, TreeIter
, TreeIter
)[] onRowHasChildToggledListeners
;
486 void addOnRowHasChildToggled(void delegate(GtkTreePath
*, TreeIter
, TreeIter
) dlg
, ConnectFlags connectFlags
=cast(ConnectFlags
)0)
488 if ( !("row-has-child-toggled" in connectedSignals
) )
492 "row-has-child-toggled",
493 cast(GCallback
)&callBackRowHasChildToggled
,
497 connectedSignals
["row-has-child-toggled"] = 1;
499 onRowHasChildToggledListeners
~= dlg
;
501 extern(C
) static void callBackRowHasChildToggled(GtkTreeModel
* treeModelStruct
, GtkTreePath
* path
, GtkTreeIter
* iter
, TreeIter treeIter
)
503 bool consumed
= false;
505 foreach ( void delegate(GtkTreePath
*, TreeIter
, TreeIter
) dlg
; treeIter
.onRowHasChildToggledListeners
)
507 dlg(path
, new TreeIter(iter
), treeIter
);
513 void delegate(GtkTreePath
*, TreeIter
, TreeIter
)[] onRowInsertedListeners
;
514 void addOnRowInserted(void delegate(GtkTreePath
*, TreeIter
, TreeIter
) dlg
, ConnectFlags connectFlags
=cast(ConnectFlags
)0)
516 if ( !("row-inserted" in connectedSignals
) )
521 cast(GCallback
)&callBackRowInserted
,
525 connectedSignals
["row-inserted"] = 1;
527 onRowInsertedListeners
~= dlg
;
529 extern(C
) static void callBackRowInserted(GtkTreeModel
* treeModelStruct
, GtkTreePath
* path
, GtkTreeIter
* iter
, TreeIter treeIter
)
531 bool consumed
= false;
533 foreach ( void delegate(GtkTreePath
*, TreeIter
, TreeIter
) dlg
; treeIter
.onRowInsertedListeners
)
535 dlg(path
, new TreeIter(iter
), treeIter
);
541 void delegate(GtkTreePath
*, TreeIter
, gpointer
, TreeIter
)[] onRowsReorderedListeners
;
542 void addOnRowsReordered(void delegate(GtkTreePath
*, TreeIter
, gpointer
, TreeIter
) dlg
, ConnectFlags connectFlags
=cast(ConnectFlags
)0)
544 if ( !("rows-reordered" in connectedSignals
) )
549 cast(GCallback
)&callBackRowsReordered
,
553 connectedSignals
["rows-reordered"] = 1;
555 onRowsReorderedListeners
~= dlg
;
557 extern(C
) static void callBackRowsReordered(GtkTreeModel
* treeModelStruct
, GtkTreePath
* path
, GtkTreeIter
* iter
, gpointer arg3
, TreeIter treeIter
)
559 bool consumed
= false;
561 foreach ( void delegate(GtkTreePath
*, TreeIter
, gpointer
, TreeIter
) dlg
; treeIter
.onRowsReorderedListeners
)
563 dlg(path
, new TreeIter(iter
), arg3
, treeIter
);
607 * Creates a dynamically allocated tree iterator as a copy of iter. This
608 * function is not intended for use in applications, because you can just copy
609 * the structs by value (GtkTreeIter new_iter = iter;). You
610 * must free this iter with gtk_tree_iter_free().
614 * a newly-allocated copy of iter.
616 public TreeIter
copy()
618 // GtkTreeIter* gtk_tree_iter_copy (GtkTreeIter *iter);
619 return new TreeIter( gtk_tree_iter_copy(gtkTreeIter
) );
623 * Frees an iterator that has been allocated on the heap. This function is
624 * mainly used for language bindings.
626 * A dynamically allocated tree iterator.
630 // void gtk_tree_iter_free (GtkTreeIter *iter);
631 gtk_tree_iter_free(gtkTreeIter
);