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 module gtk.ListStore;
26 
27 private import glib.ConstructionException;
28 private import gobject.ObjectG;
29 private import gobject.Value;
30 private import gtk.BuildableIF;
31 private import gtk.BuildableT;
32 private import gtk.TreeDragDestIF;
33 private import gtk.TreeDragDestT;
34 private import gtk.TreeDragSourceIF;
35 private import gtk.TreeDragSourceT;
36 private import gtk.TreeIter;
37 private import gtk.TreeModelIF;
38 private import gtk.TreeModelT;
39 private import gtk.TreeSortableIF;
40 private import gtk.TreeSortableT;
41 private import gtkc.gtk;
42 public  import gtkc.gtktypes;
43 
44 
45 /**
46  * The #GtkListStore object is a list model for use with a #GtkTreeView
47  * widget.  It implements the #GtkTreeModel interface, and consequentialy,
48  * can use all of the methods available there.  It also implements the
49  * #GtkTreeSortable interface so it can be sorted by the view.
50  * Finally, it also implements the tree
51  * [drag and drop][gtk3-GtkTreeView-drag-and-drop]
52  * interfaces.
53  * 
54  * The #GtkListStore can accept most GObject types as a column type, though
55  * it can’t accept all custom types.  Internally, it will keep a copy of
56  * data passed in (such as a string or a boxed pointer).  Columns that
57  * accept #GObjects are handled a little differently.  The
58  * #GtkListStore will keep a reference to the object instead of copying the
59  * value.  As a result, if the object is modified, it is up to the
60  * application writer to call gtk_tree_model_row_changed() to emit the
61  * #GtkTreeModel::row_changed signal.  This most commonly affects lists with
62  * #GdkPixbufs stored.
63  * 
64  * An example for creating a simple list store:
65  * |[<!-- language="C" -->
66  * enum {
67  * COLUMN_STRING,
68  * COLUMN_INT,
69  * COLUMN_BOOLEAN,
70  * N_COLUMNS
71  * };
72  * 
73  * {
74  * GtkListStore *list_store;
75  * GtkTreePath *path;
76  * GtkTreeIter iter;
77  * gint i;
78  * 
79  * list_store = gtk_list_store_new (N_COLUMNS,
80  * G_TYPE_STRING,
81  * G_TYPE_INT,
82  * G_TYPE_BOOLEAN);
83  * 
84  * for (i = 0; i < 10; i++)
85  * {
86  * gchar *some_data;
87  * 
88  * some_data = get_some_data (i);
89  * 
90  * // Add a new row to the model
91  * gtk_list_store_append (list_store, &iter);
92  * gtk_list_store_set (list_store, &iter,
93  * COLUMN_STRING, some_data,
94  * COLUMN_INT, i,
95  * COLUMN_BOOLEAN,  FALSE,
96  * -1);
97  * 
98  * // As the store will keep a copy of the string internally,
99  * // we free some_data.
100  * g_free (some_data);
101  * }
102  * 
103  * // Modify a particular row
104  * path = gtk_tree_path_new_from_string ("4");
105  * gtk_tree_model_get_iter (GTK_TREE_MODEL (list_store),
106  * &iter,
107  * path);
108  * gtk_tree_path_free (path);
109  * gtk_list_store_set (list_store, &iter,
110  * COLUMN_BOOLEAN, TRUE,
111  * -1);
112  * }
113  * ]|
114  * 
115  * # Performance Considerations
116  * 
117  * Internally, the #GtkListStore was implemented with a linked list with
118  * a tail pointer prior to GTK+ 2.6.  As a result, it was fast at data
119  * insertion and deletion, and not fast at random data access.  The
120  * #GtkListStore sets the #GTK_TREE_MODEL_ITERS_PERSIST flag, which means
121  * that #GtkTreeIters can be cached while the row exists.  Thus, if
122  * access to a particular row is needed often and your code is expected to
123  * run on older versions of GTK+, it is worth keeping the iter around.
124  * 
125  * # Atomic Operations
126  * 
127  * It is important to note that only the methods
128  * gtk_list_store_insert_with_values() and gtk_list_store_insert_with_valuesv()
129  * are atomic, in the sense that the row is being appended to the store and the
130  * values filled in in a single operation with regard to #GtkTreeModel signaling.
131  * In contrast, using e.g. gtk_list_store_append() and then gtk_list_store_set()
132  * will first create a row, which triggers the #GtkTreeModel::row-inserted signal
133  * on #GtkListStore. The row, however, is still empty, and any signal handler
134  * connecting to #GtkTreeModel::row-inserted on this particular store should be prepared
135  * for the situation that the row might be empty. This is especially important
136  * if you are wrapping the #GtkListStore inside a #GtkTreeModelFilter and are
137  * using a #GtkTreeModelFilterVisibleFunc. Using any of the non-atomic operations
138  * to append rows to the #GtkListStore will cause the
139  * #GtkTreeModelFilterVisibleFunc to be visited with an empty row first; the
140  * function must be prepared for that.
141  * 
142  * # GtkListStore as GtkBuildable
143  * 
144  * The GtkListStore implementation of the GtkBuildable interface allows
145  * to specify the model columns with a <columns> element that may contain
146  * multiple <column> elements, each specifying one model column. The “type”
147  * attribute specifies the data type for the column.
148  * 
149  * Additionally, it is possible to specify content for the list store
150  * in the UI definition, with the <data> element. It can contain multiple
151  * <row> elements, each specifying to content for one row of the list model.
152  * Inside a <row>, the <col> elements specify the content for individual cells.
153  * 
154  * Note that it is probably more common to define your models in the code,
155  * and one might consider it a layering violation to specify the content of
156  * a list store in a UI definition, data, not presentation, and common wisdom
157  * is to separate the two, as far as possible.
158  * 
159  * An example of a UI Definition fragment for a list store:
160  * |[<!-- language="C" -->
161  * <object class="GtkListStore">
162  * <columns>
163  * <column type="gchararray"/>
164  * <column type="gchararray"/>
165  * <column type="gint"/>
166  * </columns>
167  * <data>
168  * <row>
169  * <col id="0">John</col>
170  * <col id="1">Doe</col>
171  * <col id="2">25</col>
172  * </row>
173  * <row>
174  * <col id="0">Johan</col>
175  * <col id="1">Dahlin</col>
176  * <col id="2">50</col>
177  * </row>
178  * </data>
179  * </object>
180  * ]|
181  */
182 public class ListStore : ObjectG, BuildableIF, TreeDragDestIF, TreeDragSourceIF, TreeModelIF, TreeSortableIF
183 {
184 	/** the main Gtk struct */
185 	protected GtkListStore* gtkListStore;
186 
187 	/** Get the main Gtk struct */
188 	public GtkListStore* getListStoreStruct()
189 	{
190 		return gtkListStore;
191 	}
192 
193 	/** the main Gtk struct as a void* */
194 	protected override void* getStruct()
195 	{
196 		return cast(void*)gtkListStore;
197 	}
198 
199 	protected override void setStruct(GObject* obj)
200 	{
201 		gtkListStore = cast(GtkListStore*)obj;
202 		super.setStruct(obj);
203 	}
204 
205 	/**
206 	 * Sets our main struct and passes it to the parent class.
207 	 */
208 	public this (GtkListStore* gtkListStore, bool ownedRef = false)
209 	{
210 		this.gtkListStore = gtkListStore;
211 		super(cast(GObject*)gtkListStore, ownedRef);
212 	}
213 
214 	// add the Buildable capabilities
215 	mixin BuildableT!(GtkListStore);
216 
217 	// add the TreeDragDest capabilities
218 	mixin TreeDragDestT!(GtkListStore);
219 
220 	// add the TreeDragSource capabilities
221 	mixin TreeDragSourceT!(GtkListStore);
222 
223 	// add the TreeModel capabilities
224 	mixin TreeModelT!(GtkListStore);
225 
226 	// add the TreeSortable capabilities
227 	mixin TreeSortableT!(GtkListStore);
228 
229 	/**
230 	 * Creates a top level iteractor.
231 	 * I don't think lists have but the top level iteractor
232 	 */
233 	TreeIter createIter()
234 	{
235 		GtkTreeIter* iter = new GtkTreeIter;
236 		gtk_list_store_append(getListStoreStruct(), iter);
237 		return new TreeIter(iter);
238 	}
239 	
240 	/**
241 	 * sets the values for one row
242 	 * Params:
243 	 *  iter = the row iteractor
244 	 *  columns = an arrays with the columns to set
245 	 *  values = an arrays with the values
246 	 */
247 	void set(TreeIter iter, int[] columns, char*[] values)
248 	{
249 		for ( int i=0 ; i<columns.length && i<values.length; i++ )
250 		{
251 			gtk_list_store_set(
252 				gtkListStore,
253 				iter.getTreeIterStruct(),
254 				columns[i],
255 				values[i],-1);
256 		}
257 	}
258 	
259 	/** ditto */
260 	void set(TreeIter iter, int[] columns, string[] values)
261 	{
262 		for ( int i=0 ; i<columns.length && i<values.length; i++ )
263 		{
264 			gtk_list_store_set(
265 				gtkListStore,
266 				iter.getTreeIterStruct(),
267 				columns[i],
268 				Str.toStringz(values[i]),-1);
269 		}
270 	}
271 	
272 	/** */
273 	void setValue(TreeIter iter, int column, string value)
274 	{
275 		Value v = new Value(value);
276 		gtk_list_store_set_value(gtkListStore, iter.getTreeIterStruct(), column, v.getValueStruct());
277 		//gtk_list_store_set_value(obj(), iter.getIter(), column, (GValue*)cChar(value));
278 	}
279 	
280 	/** */
281 	void setValue(TreeIter iter, int column, int value)
282 	{
283 		Value v = new Value(value);
284 		gtk_list_store_set_value(gtkListStore, iter.getTreeIterStruct(), column, v.getValueStruct());
285 	}
286 
287 	/**
288 	 */
289 
290 	public static GType getType()
291 	{
292 		return gtk_list_store_get_type();
293 	}
294 
295 	/**
296 	 * Non-vararg creation function.  Used primarily by language bindings.
297 	 *
298 	 * Params:
299 	 *     nColumns = number of columns in the list store
300 	 *     types = an array of #GType types for the columns, from first to last
301 	 *
302 	 * Return: a new #GtkListStore
303 	 *
304 	 * Throws: ConstructionException GTK+ fails to create the object.
305 	 */
306 	public this(GType[] types)
307 	{
308 		auto p = gtk_list_store_newv(cast(int)types.length, types.ptr);
309 		
310 		if(p is null)
311 		{
312 			throw new ConstructionException("null returned by newv");
313 		}
314 		
315 		this(cast(GtkListStore*) p, true);
316 	}
317 
318 	/**
319 	 * Appends a new row to @list_store.  @iter will be changed to point to this new
320 	 * row.  The row will be empty after this function is called.  To fill in
321 	 * values, you need to call gtk_list_store_set() or gtk_list_store_set_value().
322 	 *
323 	 * Params:
324 	 *     iter = An unset #GtkTreeIter to set to the appended row
325 	 */
326 	public void append(out TreeIter iter)
327 	{
328 		GtkTreeIter* outiter = new GtkTreeIter;
329 		
330 		gtk_list_store_append(gtkListStore, outiter);
331 		
332 		iter = ObjectG.getDObject!(TreeIter)(outiter);
333 	}
334 
335 	/**
336 	 * Removes all rows from the list store.
337 	 */
338 	public void clear()
339 	{
340 		gtk_list_store_clear(gtkListStore);
341 	}
342 
343 	/**
344 	 * Creates a new row at @position.  @iter will be changed to point to this new
345 	 * row.  If @position is -1 or is larger than the number of rows on the list,
346 	 * then the new row will be appended to the list. The row will be empty after
347 	 * this function is called.  To fill in values, you need to call
348 	 * gtk_list_store_set() or gtk_list_store_set_value().
349 	 *
350 	 * Params:
351 	 *     iter = An unset #GtkTreeIter to set to the new row
352 	 *     position = position to insert the new row, or -1 for last
353 	 */
354 	public void insert(out TreeIter iter, int position)
355 	{
356 		GtkTreeIter* outiter = new GtkTreeIter;
357 		
358 		gtk_list_store_insert(gtkListStore, outiter, position);
359 		
360 		iter = ObjectG.getDObject!(TreeIter)(outiter);
361 	}
362 
363 	/**
364 	 * Inserts a new row after @sibling. If @sibling is %NULL, then the row will be
365 	 * prepended to the beginning of the list. @iter will be changed to point to
366 	 * this new row. The row will be empty after this function is called. To fill
367 	 * in values, you need to call gtk_list_store_set() or gtk_list_store_set_value().
368 	 *
369 	 * Params:
370 	 *     iter = An unset #GtkTreeIter to set to the new row
371 	 *     sibling = A valid #GtkTreeIter, or %NULL
372 	 */
373 	public void insertAfter(out TreeIter iter, TreeIter sibling)
374 	{
375 		GtkTreeIter* outiter = new GtkTreeIter;
376 		
377 		gtk_list_store_insert_after(gtkListStore, outiter, (sibling is null) ? null : sibling.getTreeIterStruct());
378 		
379 		iter = ObjectG.getDObject!(TreeIter)(outiter);
380 	}
381 
382 	/**
383 	 * Inserts a new row before @sibling. If @sibling is %NULL, then the row will
384 	 * be appended to the end of the list. @iter will be changed to point to this
385 	 * new row. The row will be empty after this function is called. To fill in
386 	 * values, you need to call gtk_list_store_set() or gtk_list_store_set_value().
387 	 *
388 	 * Params:
389 	 *     iter = An unset #GtkTreeIter to set to the new row
390 	 *     sibling = A valid #GtkTreeIter, or %NULL
391 	 */
392 	public void insertBefore(out TreeIter iter, TreeIter sibling)
393 	{
394 		GtkTreeIter* outiter = new GtkTreeIter;
395 		
396 		gtk_list_store_insert_before(gtkListStore, outiter, (sibling is null) ? null : sibling.getTreeIterStruct());
397 		
398 		iter = ObjectG.getDObject!(TreeIter)(outiter);
399 	}
400 
401 	/**
402 	 * A variant of gtk_list_store_insert_with_values() which
403 	 * takes the columns and values as two arrays, instead of
404 	 * varargs. This function is mainly intended for
405 	 * language-bindings.
406 	 *
407 	 * Params:
408 	 *     iter = An unset #GtkTreeIter to set to the new row, or %NULL.
409 	 *     position = position to insert the new row, or -1 for last
410 	 *     columns = an array of column numbers
411 	 *     values = an array of GValues
412 	 *     nValues = the length of the @columns and @values arrays
413 	 *
414 	 * Since: 2.6
415 	 */
416 	public void insertWithValuesv(out TreeIter iter, int position, int[] columns, Value[] values)
417 	{
418 		GtkTreeIter* outiter = new GtkTreeIter;
419 		
420 		GValue[] valuesArray = new GValue[values.length];
421 		for ( int i = 0; i < values.length; i++ )
422 		{
423 			valuesArray[i] = *(values[i].getValueStruct());
424 		}
425 		
426 		gtk_list_store_insert_with_valuesv(gtkListStore, outiter, position, columns.ptr, valuesArray.ptr, cast(int)values.length);
427 		
428 		iter = ObjectG.getDObject!(TreeIter)(outiter);
429 	}
430 
431 	/**
432 	 * > This function is slow. Only use it for debugging and/or testing
433 	 * > purposes.
434 	 *
435 	 * Checks if the given iter is a valid iter for this #GtkListStore.
436 	 *
437 	 * Params:
438 	 *     iter = A #GtkTreeIter.
439 	 *
440 	 * Return: %TRUE if the iter is valid, %FALSE if the iter is invalid.
441 	 *
442 	 * Since: 2.2
443 	 */
444 	public bool iterIsValid(TreeIter iter)
445 	{
446 		return gtk_list_store_iter_is_valid(gtkListStore, (iter is null) ? null : iter.getTreeIterStruct()) != 0;
447 	}
448 
449 	/**
450 	 * Moves @iter in @store to the position after @position. Note that this
451 	 * function only works with unsorted stores. If @position is %NULL, @iter
452 	 * will be moved to the start of the list.
453 	 *
454 	 * Params:
455 	 *     iter = A #GtkTreeIter.
456 	 *     position = A #GtkTreeIter or %NULL.
457 	 *
458 	 * Since: 2.2
459 	 */
460 	public void moveAfter(TreeIter iter, TreeIter position)
461 	{
462 		gtk_list_store_move_after(gtkListStore, (iter is null) ? null : iter.getTreeIterStruct(), (position is null) ? null : position.getTreeIterStruct());
463 	}
464 
465 	/**
466 	 * Moves @iter in @store to the position before @position. Note that this
467 	 * function only works with unsorted stores. If @position is %NULL, @iter
468 	 * will be moved to the end of the list.
469 	 *
470 	 * Params:
471 	 *     iter = A #GtkTreeIter.
472 	 *     position = A #GtkTreeIter, or %NULL.
473 	 *
474 	 * Since: 2.2
475 	 */
476 	public void moveBefore(TreeIter iter, TreeIter position)
477 	{
478 		gtk_list_store_move_before(gtkListStore, (iter is null) ? null : iter.getTreeIterStruct(), (position is null) ? null : position.getTreeIterStruct());
479 	}
480 
481 	/**
482 	 * Prepends a new row to @list_store. @iter will be changed to point to this new
483 	 * row. The row will be empty after this function is called. To fill in
484 	 * values, you need to call gtk_list_store_set() or gtk_list_store_set_value().
485 	 *
486 	 * Params:
487 	 *     iter = An unset #GtkTreeIter to set to the prepend row
488 	 */
489 	public void prepend(out TreeIter iter)
490 	{
491 		GtkTreeIter* outiter = new GtkTreeIter;
492 		
493 		gtk_list_store_prepend(gtkListStore, outiter);
494 		
495 		iter = ObjectG.getDObject!(TreeIter)(outiter);
496 	}
497 
498 	/**
499 	 * Removes the given row from the list store.  After being removed,
500 	 * @iter is set to be the next valid row, or invalidated if it pointed
501 	 * to the last row in @list_store.
502 	 *
503 	 * Params:
504 	 *     iter = A valid #GtkTreeIter
505 	 *
506 	 * Return: %TRUE if @iter is valid, %FALSE if not.
507 	 */
508 	public bool remove(TreeIter iter)
509 	{
510 		return gtk_list_store_remove(gtkListStore, (iter is null) ? null : iter.getTreeIterStruct()) != 0;
511 	}
512 
513 	/**
514 	 * Reorders @store to follow the order indicated by @new_order. Note that
515 	 * this function only works with unsorted stores.
516 	 *
517 	 * Params:
518 	 *     newOrder = an array of integers mapping the new
519 	 *         position of each child to its old position before the re-ordering,
520 	 *         i.e. @new_order`[newpos] = oldpos`. It must have
521 	 *         exactly as many items as the list store’s length.
522 	 *
523 	 * Since: 2.2
524 	 */
525 	public void reorder(int[] newOrder)
526 	{
527 		gtk_list_store_reorder(gtkListStore, newOrder.ptr);
528 	}
529 
530 	/**
531 	 * This function is meant primarily for #GObjects that inherit from #GtkListStore,
532 	 * and should only be used when constructing a new #GtkListStore.  It will not
533 	 * function after a row has been added, or a method on the #GtkTreeModel
534 	 * interface is called.
535 	 *
536 	 * Params:
537 	 *     nColumns = Number of columns for the list store
538 	 *     types = An array length n of #GTypes
539 	 */
540 	public void setColumnTypes(GType[] types)
541 	{
542 		gtk_list_store_set_column_types(gtkListStore, cast(int)types.length, types.ptr);
543 	}
544 
545 	/**
546 	 * See gtk_list_store_set(); this version takes a va_list for use by language
547 	 * bindings.
548 	 *
549 	 * Params:
550 	 *     iter = A valid #GtkTreeIter for the row being modified
551 	 *     varArgs = va_list of column/value pairs
552 	 */
553 	public void setValist(TreeIter iter, void* varArgs)
554 	{
555 		gtk_list_store_set_valist(gtkListStore, (iter is null) ? null : iter.getTreeIterStruct(), varArgs);
556 	}
557 
558 	/**
559 	 * Sets the data in the cell specified by @iter and @column.
560 	 * The type of @value must be convertible to the type of the
561 	 * column.
562 	 *
563 	 * Params:
564 	 *     iter = A valid #GtkTreeIter for the row being modified
565 	 *     column = column number to modify
566 	 *     value = new value for the cell
567 	 */
568 	public void setValue(TreeIter iter, int column, Value value)
569 	{
570 		gtk_list_store_set_value(gtkListStore, (iter is null) ? null : iter.getTreeIterStruct(), column, (value is null) ? null : value.getValueStruct());
571 	}
572 
573 	/**
574 	 * A variant of gtk_list_store_set_valist() which
575 	 * takes the columns and values as two arrays, instead of
576 	 * varargs. This function is mainly intended for
577 	 * language-bindings and in case the number of columns to
578 	 * change is not known until run-time.
579 	 *
580 	 * Params:
581 	 *     iter = A valid #GtkTreeIter for the row being modified
582 	 *     columns = an array of column numbers
583 	 *     values = an array of GValues
584 	 *     nValues = the length of the @columns and @values arrays
585 	 *
586 	 * Since: 2.12
587 	 */
588 	public void setValuesv(TreeIter iter, int[] columns, Value[] values)
589 	{
590 		GValue[] valuesArray = new GValue[values.length];
591 		for ( int i = 0; i < values.length; i++ )
592 		{
593 			valuesArray[i] = *(values[i].getValueStruct());
594 		}
595 		
596 		gtk_list_store_set_valuesv(gtkListStore, (iter is null) ? null : iter.getTreeIterStruct(), columns.ptr, valuesArray.ptr, cast(int)values.length);
597 	}
598 
599 	/**
600 	 * Swaps @a and @b in @store. Note that this function only works with
601 	 * unsorted stores.
602 	 *
603 	 * Params:
604 	 *     a = A #GtkTreeIter.
605 	 *     b = Another #GtkTreeIter.
606 	 *
607 	 * Since: 2.2
608 	 */
609 	public void swap(TreeIter a, TreeIter b)
610 	{
611 		gtk_list_store_swap(gtkListStore, (a is null) ? null : a.getTreeIterStruct(), (b is null) ? null : b.getTreeIterStruct());
612 	}
613 }