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 }