1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19  
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 /*
25  * Conversion parameters:
26  * inFile  = 
27  * outPack = gtk
28  * outFile = TreeModelIF
29  * strct   = GtkTreeModel
30  * realStrct=
31  * ctorStrct=
32  * clss    = TreeModelT
33  * interf  = TreeModelIF
34  * class Code: Yes
35  * interface Code: Yes
36  * template for:
37  * extend  = 
38  * implements:
39  * prefixes:
40  * 	- gtk_tree_model_
41  * omit structs:
42  * omit prefixes:
43  * 	- gtk_tree_row_reference_
44  * 	- gtk_tree_path_
45  * 	- gtk_tree_iter_
46  * omit code:
47  * 	- gtk_tree_model_get_value
48  * 	- gtk_tree_model_get_iter
49  * omit signals:
50  * imports:
51  * 	- glib.Str
52  * 	- gtk.TreeIter
53  * 	- gtk.TreePath
54  * 	- gobject.Value
55  * structWrap:
56  * 	- GValue* -> Value
57  * 	- GtkTreeIter* -> TreeIter
58  * 	- GtkTreePath* -> TreePath
59  * module aliases:
60  * local aliases:
61  * overrides:
62  */
63 
64 module gtk.TreeModelIF;
65 
66 public  import gtkc.gtktypes;
67 
68 private import gtkc.gtk;
69 private import glib.ConstructionException;
70 private import gobject.ObjectG;
71 
72 private import gobject.Signals;
73 public  import gtkc.gdktypes;
74 
75 private import glib.Str;
76 private import gtk.TreeIter;
77 private import gtk.TreePath;
78 private import gobject.Value;
79 
80 
81 
82 
83 /**
84  * Description
85  * The GtkTreeModel interface defines a generic tree interface for use by
86  * the GtkTreeView widget. It is an abstract interface, and is designed
87  * to be usable with any appropriate data structure. The programmer just
88  * has to implement this interface on their own data type for it to be
89  * viewable by a GtkTreeView widget.
90  * The model is represented as a hierarchical tree of strongly-typed,
91  * columned data. In other words, the model can be seen as a tree where
92  * every node has different values depending on which column is being
93  * queried. The type of data found in a column is determined by using the
94  * GType system (ie. G_TYPE_INT, GTK_TYPE_BUTTON, G_TYPE_POINTER, etc.).
95  * The types are homogeneous per column across all nodes. It is important
96  * to note that this interface only provides a way of examining a model and
97  * observing changes. The implementation of each individual model decides
98  * how and if changes are made.
99  * In order to make life simpler for programmers who do not need to write
100  * their own specialized model, two generic models are provided — the
101  * GtkTreeStore and the GtkListStore. To use these, the developer simply
102  * pushes data into these models as necessary. These models provide the
103  * data structure as well as all appropriate tree interfaces. As a result,
104  * implementing drag and drop, sorting, and storing data is trivial. For
105  * the vast majority of trees and lists, these two models are sufficient.
106  * Models are accessed on a node/column level of granularity. One can
107  * query for the value of a model at a certain node and a certain column
108  * on that node. There are two structures used to reference a particular
109  * node in a model. They are the GtkTreePath and the GtkTreeIter
110  * [4]
111  * Most of the interface consists of operations on a GtkTreeIter.
112  * A path is essentially a potential node. It is a location on a model
113  * that may or may not actually correspond to a node on a specific model.
114  * The GtkTreePath struct can be converted into either an array of
115  * unsigned integers or a string. The string form is a list of numbers
116  * separated by a colon. Each number refers to the offset at that level.
117  * Thus, the path “0” refers to the root node and the path
118  * “2:4” refers to the fifth child of the third node.
119  * By contrast, a GtkTreeIter is a reference to a specific node on a
120  * specific model. It is a generic struct with an integer and three
121  * generic pointers. These are filled in by the model in a model-specific
122  * way. One can convert a path to an iterator by calling
123  * gtk_tree_model_get_iter(). These iterators are the primary way of
124  * accessing a model and are similar to the iterators used by
125  * GtkTextBuffer. They are generally statically allocated on the stack and
126  * only used for a short time. The model interface defines a set of
127  * operations using them for navigating the model.
128  * It is expected that models fill in the iterator with private data. For
129  * example, the GtkListStore model, which is internally a simple linked
130  * list, stores a list node in one of the pointers. The GtkTreeModelSort
131  * stores an array and an offset in two of the pointers. Additionally,
132  * there is an integer field. This field is generally filled with a unique
133  * stamp per model. This stamp is for catching errors resulting from using
134  * invalid iterators with a model.
135  * The lifecycle of an iterator can be a little confusing at first.
136  * Iterators are expected to always be valid for as long as the model is
137  * unchanged (and doesn't emit a signal). The model is considered to own
138  * all outstanding iterators and nothing needs to be done to free them from
139  * the user's point of view. Additionally, some models guarantee that an
140  * iterator is valid for as long as the node it refers to is valid (most
141  * notably the GtkTreeStore and GtkListStore). Although generally
142  * uninteresting, as one always has to allow for the case where iterators
143  * do not persist beyond a signal, some very important performance
144  * enhancements were made in the sort model. As a result, the
145  * GTK_TREE_MODEL_ITERS_PERSIST flag was added to indicate this behavior.
146  * To help show some common operation of a model, some examples are
147  * provided. The first example shows three ways of getting the iter at the
148  * location “3:2:5”. While the first method shown is easier,
149  * the second is much more common, as you often get paths from callbacks.
150  * $(DDOC_COMMENT example)
151  * This second example shows a quick way of iterating through a list and
152  * getting a string and an integer from each row. The
153  * populate_model function used below is not shown, as
154  * it is specific to the GtkListStore. For information on how to write
155  * such a function, see the GtkListStore documentation.
156  * $(DDOC_COMMENT example)
157  */
158 public interface TreeModelIF
159 {
160 	
161 	
162 	public GtkTreeModel* getTreeModelTStruct();
163 	
164 	/** the main Gtk struct as a void* */
165 	protected void* getStruct();
166 	
167 	
168 	/**
169 	 * Get the value of a column as a char array.
170 	 * this is the same calling getValue and get the string from the value object
171 	 */
172 	string getValueString(TreeIter iter, int column);
173 	
174 	/**
175 	 * Get the value of a column as a char array.
176 	 * this is the same calling getValue and get the int from the value object
177 	 */
178 	int getValueInt(TreeIter iter, int column);
179 	
180 	/**
181 	 * Sets iter to a valid iterator pointing to path.
182 	 * Params:
183 	 *  iter = The uninitialized GtkTreeIter.
184 	 *  path = The GtkTreePath.
185 	 * Returns:
186 	 *  TRUE, if iter was set.
187 	 */
188 	public int getIter(TreeIter iter, TreePath path);
189 	
190 	/**
191 	 * Initializes and sets value to that at column.
192 	 * When done with value, g_value_unset() needs to be called
193 	 * to free any allocated memory.
194 	 * Params:
195 	 * iter = The GtkTreeIter.
196 	 * column = The column to lookup the value at.
197 	 * value = (inout) (transfer none) An empty GValue to set.
198 	 */
199 	public Value getValue(TreeIter iter, int column, Value value = null);
200 	
201 	/**
202 	 */
203 	
204 	void delegate(TreePath, TreeIter, TreeModelIF)[] onRowChangedListeners();
205 	/**
206 	 * This signal is emitted when a row in the model has changed.
207 	 */
208 	void addOnRowChanged(void delegate(TreePath, TreeIter, TreeModelIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0);
209 	void delegate(TreePath, TreeModelIF)[] onRowDeletedListeners();
210 	/**
211 	 * This signal is emitted when a row has been deleted.
212 	 * Note that no iterator is passed to the signal handler,
213 	 * since the row is already deleted.
214 	 * This should be called by models after a row has been removed.
215 	 * The location pointed to by path should be the location that
216 	 * the row previously was at. It may not be a valid location anymore.
217 	 */
218 	void addOnRowDeleted(void delegate(TreePath, TreeModelIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0);
219 	void delegate(TreePath, TreeIter, TreeModelIF)[] onRowHasChildToggledListeners();
220 	/**
221 	 * This signal is emitted when a row has gotten the first child row or lost
222 	 * its last child row.
223 	 */
224 	void addOnRowHasChildToggled(void delegate(TreePath, TreeIter, TreeModelIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0);
225 	void delegate(TreePath, TreeIter, TreeModelIF)[] onRowInsertedListeners();
226 	/**
227 	 * This signal is emitted when a new row has been inserted in the model.
228 	 * Note that the row may still be empty at this point, since
229 	 * it is a common pattern to first insert an empty row, and
230 	 * then fill it with the desired values.
231 	 */
232 	void addOnRowInserted(void delegate(TreePath, TreeIter, TreeModelIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0);
233 	void delegate(TreePath, TreeIter, void*, TreeModelIF)[] onRowsReorderedListeners();
234 	/**
235 	 * This signal is emitted when the children of a node in the GtkTreeModel
236 	 * have been reordered.
237 	 * Note that this signal is not emitted
238 	 * when rows are reordered by DND, since this is implemented
239 	 * by removing and then reinserting the row.
240 	 * See Also
241 	 * GtkTreeView, GtkTreeStore, GtkListStore, GtkTreeDnd, GtkTreeSortable
242 	 * [4]
243 	 * Here, iter is short for “iterator”
244 	 */
245 	void addOnRowsReordered(void delegate(TreePath, TreeIter, void*, TreeModelIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0);
246 	
247 	/**
248 	 * Returns a set of flags supported by this interface. The flags are a bitwise
249 	 * combination of GtkTreeModelFlags. The flags supported should not change
250 	 * during the lifecycle of the tree_model.
251 	 * Returns: The flags supported by this interface.
252 	 */
253 	public GtkTreeModelFlags getFlags();
254 	
255 	/**
256 	 * Returns the number of columns supported by tree_model.
257 	 * Returns: The number of columns.
258 	 */
259 	public int getNColumns();
260 	
261 	/**
262 	 * Returns the type of the column.
263 	 * Params:
264 	 * index = The column index.
265 	 * Returns: The type of the column. [transfer none]
266 	 */
267 	public GType getColumnType(int index);
268 	
269 	/**
270 	 * Sets iter to a valid iterator pointing to path_string, if it
271 	 * exists. Otherwise, iter is left invalid and FALSE is returned.
272 	 * Params:
273 	 * iter = An uninitialized GtkTreeIter. [out]
274 	 * pathString = A string representation of a GtkTreePath.
275 	 * Returns: TRUE, if iter was set.
276 	 */
277 	public int getIterFromString(TreeIter iter, string pathString);
278 	
279 	/**
280 	 * Initializes iter with the first iterator in the tree (the one at the path
281 	 * "0") and returns TRUE. Returns FALSE if the tree is empty.
282 	 * Params:
283 	 * iter = The uninitialized GtkTreeIter. [out]
284 	 * Returns: TRUE, if iter was set.
285 	 */
286 	public int getIterFirst(TreeIter iter);
287 	
288 	/**
289 	 * Returns a newly-created GtkTreePath referenced by iter. This path should
290 	 * be freed with gtk_tree_path_free().
291 	 * Params:
292 	 * iter = The GtkTreeIter.
293 	 * Returns: a newly-created GtkTreePath.
294 	 */
295 	public TreePath getPath(TreeIter iter);
296 	
297 	/**
298 	 * Sets iter to point to the node following it at the current level. If there
299 	 * is no next iter, FALSE is returned and iter is set to be invalid.
300 	 * Params:
301 	 * iter = The GtkTreeIter. [in]
302 	 * Returns: TRUE if iter has been changed to the next node.
303 	 */
304 	public int iterNext(TreeIter iter);
305 	
306 	/**
307 	 * Sets iter to point to the first child of parent. If parent has no
308 	 * children, FALSE is returned and iter is set to be invalid. parent
309 	 * will remain a valid node after this function has been called.
310 	 * If parent is NULL returns the first node, equivalent to
311 	 * gtk_tree_model_get_iter_first (tree_model, iter);
312 	 * Params:
313 	 * iter = The new GtkTreeIter to be set to the child. [out]
314 	 * parent = The GtkTreeIter, or NULL. [allow-none]
315 	 * Returns: TRUE, if child has been set to the first child.
316 	 */
317 	public int iterChildren(TreeIter iter, TreeIter parent);
318 	
319 	/**
320 	 * Returns TRUE if iter has children, FALSE otherwise.
321 	 * Params:
322 	 * iter = The GtkTreeIter to test for children.
323 	 * Returns: TRUE if iter has children.
324 	 */
325 	public int iterHasChild(TreeIter iter);
326 	
327 	/**
328 	 * Returns the number of children that iter has. As a special case, if iter
329 	 * is NULL, then the number of toplevel nodes is returned.
330 	 * Params:
331 	 * iter = The GtkTreeIter, or NULL. [allow-none]
332 	 * Returns: The number of children of iter.
333 	 */
334 	public int iterNChildren(TreeIter iter);
335 	
336 	/**
337 	 * Sets iter to be the child of parent, using the given index. The first
338 	 * index is 0. If n is too big, or parent has no children, iter is set
339 	 * to an invalid iterator and FALSE is returned. parent will remain a valid
340 	 * node after this function has been called. As a special case, if parent is
341 	 * NULL, then the nth root node is set.
342 	 * Params:
343 	 * iter = The GtkTreeIter to set to the nth child. [out]
344 	 * parent = The GtkTreeIter to get the child from, or NULL. [allow-none]
345 	 * n = Then index of the desired child.
346 	 * Returns: TRUE, if parent has an nth child.
347 	 */
348 	public int iterNthChild(TreeIter iter, TreeIter parent, int n);
349 	
350 	/**
351 	 * Sets iter to be the parent of child. If child is at the toplevel, and
352 	 * doesn't have a parent, then iter is set to an invalid iterator and FALSE
353 	 * is returned. child will remain a valid node after this function has been
354 	 * called.
355 	 * Params:
356 	 * iter = The new GtkTreeIter to set to the parent. [out]
357 	 * child = The GtkTreeIter.
358 	 * Returns: TRUE, if iter is set to the parent of child.
359 	 */
360 	public int iterParent(TreeIter iter, TreeIter child);
361 	
362 	/**
363 	 * Generates a string representation of the iter. This string is a ':'
364 	 * separated list of numbers. For example, "4:10:0:3" would be an
365 	 * acceptable return value for this string.
366 	 * Since 2.2
367 	 * Params:
368 	 * iter = An GtkTreeIter.
369 	 * Returns: A newly-allocated string. Must be freed with g_free().
370 	 */
371 	public string getStringFromIter(TreeIter iter);
372 	
373 	/**
374 	 * Lets the tree ref the node. This is an optional method for models to
375 	 * implement. To be more specific, models may ignore this call as it exists
376 	 * primarily for performance reasons.
377 	 * This function is primarily meant as a way for views to let caching model
378 	 * know when nodes are being displayed (and hence, whether or not to cache that
379 	 * node.) For example, a file-system based model would not want to keep the
380 	 * entire file-hierarchy in memory, just the sections that are currently being
381 	 * displayed by every current view.
382 	 * A model should be expected to be able to get an iter independent of its
383 	 * reffed state.
384 	 * Params:
385 	 * iter = The GtkTreeIter.
386 	 */
387 	public void refNode(TreeIter iter);
388 	
389 	/**
390 	 * Lets the tree unref the node. This is an optional method for models to
391 	 * implement. To be more specific, models may ignore this call as it exists
392 	 * primarily for performance reasons.
393 	 * For more information on what this means, see gtk_tree_model_ref_node().
394 	 * Please note that nodes that are deleted are not unreffed.
395 	 * Params:
396 	 * iter = The GtkTreeIter.
397 	 */
398 	public void unrefNode(TreeIter iter);
399 	
400 	/**
401 	 * See gtk_tree_model_get(), this version takes a va_list
402 	 * for language bindings to use.
403 	 * Params:
404 	 * iter = a row in tree_model
405 	 * varArgs = va_list of column/return location pairs
406 	 */
407 	public void getValist(TreeIter iter, void* varArgs);
408 	
409 	/**
410 	 * Calls func on each node in model in a depth-first fashion.
411 	 * If func returns TRUE, then the tree ceases to be walked, and
412 	 * gtk_tree_model_foreach() returns.
413 	 * Params:
414 	 * func = A function to be called on each row. [scope call]
415 	 * userData = User data to passed to func.
416 	 */
417 	public void foreac(GtkTreeModelForeachFunc func, void* userData);
418 	
419 	/**
420 	 * Emits the "row-changed" signal on tree_model.
421 	 * Params:
422 	 * path = A GtkTreePath pointing to the changed row
423 	 * iter = A valid GtkTreeIter pointing to the changed row
424 	 */
425 	public void rowChanged(TreePath path, TreeIter iter);
426 	
427 	/**
428 	 * Emits the "row-inserted" signal on tree_model
429 	 * Params:
430 	 * path = A GtkTreePath pointing to the inserted row
431 	 * iter = A valid GtkTreeIter pointing to the inserted row
432 	 */
433 	public void rowInserted(TreePath path, TreeIter iter);
434 	
435 	/**
436 	 * Emits the "row-has-child-toggled" signal on tree_model. This should be
437 	 * called by models after the child state of a node changes.
438 	 * Params:
439 	 * path = A GtkTreePath pointing to the changed row
440 	 * iter = A valid GtkTreeIter pointing to the changed row
441 	 */
442 	public void rowHasChildToggled(TreePath path, TreeIter iter);
443 	
444 	/**
445 	 * Emits the "row-deleted" signal on tree_model. This should be called by
446 	 * models after a row has been removed. The location pointed to by path
447 	 * should be the location that the row previously was at. It may not be a
448 	 * valid location anymore.
449 	 * Params:
450 	 * path = A GtkTreePath pointing to the previous location of the deleted row.
451 	 */
452 	public void rowDeleted(TreePath path);
453 	
454 	/**
455 	 * Emits the "rows-reordered" signal on tree_model. This should be called by
456 	 * models when their rows have been reordered.
457 	 * Params:
458 	 * path = A GtkTreePath pointing to the tree node whose children have been
459 	 * reordered
460 	 * iter = A valid GtkTreeIter pointing to the node whose children have been
461 	 * reordered, or NULL if the depth of path is 0.
462 	 * newOrder = an array of integers mapping the current position of each child
463 	 * to its old position before the re-ordering,
464 	 * i.e. new_order[newpos] = oldpos.
465 	 * Signal Details
466 	 * The "row-changed" signal
467 	 * void user_function (GtkTreeModel *tree_model,
468 	 *  GtkTreePath *path,
469 	 *  GtkTreeIter *iter,
470 	 *  gpointer user_data) : Run Last
471 	 * This signal is emitted when a row in the model has changed.
472 	 * path = a GtkTreePath identifying the changed row
473 	 * iter = a valid GtkTreeIter pointing to the changed row
474 	 */
475 	public void rowsReordered(TreePath path, TreeIter iter, int[] newOrder);
476 }