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