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 = TreeRowReference 29 * strct = GtkTreeRowReference 30 * realStrct= 31 * ctorStrct= 32 * clss = TreeRowReference 33 * interf = 34 * class Code: No 35 * interface Code: No 36 * template for: 37 * extend = 38 * implements: 39 * prefixes: 40 * - gtk_tree_row_reference_ 41 * omit structs: 42 * omit prefixes: 43 * omit code: 44 * omit signals: 45 * - row-changed 46 * - row-deleted 47 * - row-has-child-toggled 48 * - row-inserted 49 * - rows-reordered 50 * imports: 51 * - gobject.ObjectG 52 * - gtk.TreeIter 53 * - gtk.TreeModel 54 * - gtk.TreeModelIF 55 * - gtk.TreePath 56 * structWrap: 57 * - GObject* -> ObjectG 58 * - GtkTreeIter* -> TreeIter 59 * - GtkTreeModel* -> TreeModelIF 60 * - GtkTreePath* -> TreePath 61 * - GtkTreeRowReference* -> TreeRowReference 62 * module aliases: 63 * local aliases: 64 * overrides: 65 */ 66 67 module gtk.TreeRowReference; 68 69 public import gtkc.gtktypes; 70 71 private import gtkc.gtk; 72 private import glib.ConstructionException; 73 private import gobject.ObjectG; 74 75 private import gobject.Signals; 76 public import gtkc.gdktypes; 77 private import gobject.ObjectG; 78 private import gtk.TreeIter; 79 private import gtk.TreeModel; 80 private import gtk.TreeModelIF; 81 private import gtk.TreePath; 82 83 84 85 /** 86 * The GtkTreeModel interface defines a generic tree interface for 87 * use by the GtkTreeView widget. It is an abstract interface, and 88 * is designed to be usable with any appropriate data structure. The 89 * programmer just has to implement this interface on their own data 90 * type for it to be viewable by a GtkTreeView widget. 91 * 92 * The model is represented as a hierarchical tree of strongly-typed, 93 * columned data. In other words, the model can be seen as a tree where 94 * every node has different values depending on which column is being 95 * queried. The type of data found in a column is determined by using 96 * the GType system (ie. G_TYPE_INT, GTK_TYPE_BUTTON, G_TYPE_POINTER, 97 * etc). The types are homogeneous per column across all nodes. It is 98 * important to note that this interface only provides a way of examining 99 * a model and observing changes. The implementation of each individual 100 * model decides how and if changes are made. 101 * 102 * In order to make life simpler for programmers who do not need to 103 * write their own specialized model, two generic models are provided 104 * — the GtkTreeStore and the GtkListStore. To use these, the 105 * developer simply pushes data into these models as necessary. These 106 * models provide the data structure as well as all appropriate tree 107 * interfaces. As a result, implementing drag and drop, sorting, and 108 * storing data is trivial. For the vast majority of trees and lists, 109 * these two models are sufficient. 110 * 111 * Models are accessed on a node/column level of granularity. One can 112 * query for the value of a model at a certain node and a certain 113 * column on that node. There are two structures used to reference 114 * a particular node in a model. They are the GtkTreePath and the 115 * GtkTreeIter[4]. Most of the interface 116 * consists of operations on a GtkTreeIter. 117 * 118 * A path is essentially a potential node. It is a location on a model 119 * that may or may not actually correspond to a node on a specific 120 * model. The GtkTreePath struct can be converted into either an 121 * array of unsigned integers or a string. The string form is a list 122 * of numbers separated by a colon. Each number refers to the offset 123 * at that level. Thus, the path “0” refers to the root 124 * node and the path “2:4” refers to the fifth child of 125 * the third node. 126 * 127 * By contrast, a GtkTreeIter is a reference to a specific node on 128 * a specific model. It is a generic struct with an integer and three 129 * generic pointers. These are filled in by the model in a model-specific 130 * way. One can convert a path to an iterator by calling 131 * gtk_tree_model_get_iter(). These iterators are the primary way 132 * of accessing a model and are similar to the iterators used by 133 * GtkTextBuffer. They are generally statically allocated on the 134 * stack and only used for a short time. The model interface defines 135 * a set of operations using them for navigating the model. 136 * 137 * It is expected that models fill in the iterator with private data. 138 * For example, the GtkListStore model, which is internally a simple 139 * linked list, stores a list node in one of the pointers. The 140 * GtkTreeModelSort stores an array and an offset in two of the 141 * pointers. Additionally, there is an integer field. This field is 142 * generally filled with a unique stamp per model. This stamp is for 143 * catching errors resulting from using invalid iterators with a model. 144 * 145 * The lifecycle of an iterator can be a little confusing at first. 146 * Iterators are expected to always be valid for as long as the model 147 * is unchanged (and doesn't emit a signal). The model is considered 148 * to own all outstanding iterators and nothing needs to be done to 149 * free them from the user's point of view. Additionally, some models 150 * guarantee that an iterator is valid for as long as the node it refers 151 * to is valid (most notably the GtkTreeStore and GtkListStore). 152 * Although generally uninteresting, as one always has to allow for 153 * the case where iterators do not persist beyond a signal, some very 154 * important performance enhancements were made in the sort model. 155 * As a result, the GTK_TREE_MODEL_ITERS_PERSIST flag was added to 156 * indicate this behavior. 157 * 158 * To help show some common operation of a model, some examples are 159 * provided. The first example shows three ways of getting the iter at 160 * the location “3:2:5”. While the first method shown is 161 * easier, the second is much more common, as you often get paths from 162 * callbacks. 163 * 164 * $(DDOC_COMMENT example) 165 * 166 * This second example shows a quick way of iterating through a list 167 * and getting a string and an integer from each row. The 168 * populate_model function used below is not 169 * shown, as it is specific to the GtkListStore. For information on 170 * how to write such a function, see the GtkListStore documentation. 171 * 172 * $(DDOC_COMMENT example) 173 * 174 * The GtkTreeModel interface contains two methods for reference 175 * counting: gtk_tree_model_ref_node() and gtk_tree_model_unref_node(). 176 * These two methods are optional to implement. The reference counting 177 * is meant as a way for views to let models know when nodes are being 178 * displayed. GtkTreeView will take a reference on a node when it is 179 * visible, which means the node is either in the toplevel or expanded. 180 * Being displayed does not mean that the node is currently directly 181 * visible to the user in the viewport. Based on this reference counting 182 * scheme a caching model, for example, can decide whether or not to cache 183 * a node based on the reference count. A file-system based model would 184 * not want to keep the entire file hierarchy in memory, but just the 185 * folders that are currently expanded in every current view. 186 * 187 * When working with reference counting, the following rules must be taken 188 * into account: 189 * 190 * Never take a reference on a node without owning a 191 * reference on its parent. This means that all parent nodes of a referenced 192 * node must be referenced as well. 193 * 194 * Outstanding references on a deleted node are not released. 195 * This is not possible because the node has already been deleted by the 196 * time the row-deleted signal is received. 197 * 198 * Models are not obligated to emit a signal on rows of 199 * which none of its siblings are referenced. To phrase this differently, 200 * signals are only required for levels in which nodes are referenced. For 201 * the root level however, signals must be emitted at all times (however the 202 * root level is always referenced when any view is attached). 203 */ 204 public class TreeRowReference 205 { 206 207 /** the main Gtk struct */ 208 protected GtkTreeRowReference* gtkTreeRowReference; 209 210 211 /** Get the main Gtk struct */ 212 public GtkTreeRowReference* getTreeRowReferenceStruct() 213 { 214 return gtkTreeRowReference; 215 } 216 217 218 /** the main Gtk struct as a void* */ 219 protected void* getStruct() 220 { 221 return cast(void*)gtkTreeRowReference; 222 } 223 224 /** 225 * Sets our main struct and passes it to the parent class 226 */ 227 public this (GtkTreeRowReference* gtkTreeRowReference) 228 { 229 this.gtkTreeRowReference = gtkTreeRowReference; 230 } 231 232 /** 233 */ 234 235 /** 236 * Creates a row reference based on path. 237 * This reference will keep pointing to the node pointed to 238 * by path, so long as it exists. Any changes that occur on model are 239 * propagated, and the path is updated appropriately. If 240 * path isn't a valid path in model, then NULL is returned. 241 * Params: 242 * model = a GtkTreeModel 243 * path = a valid GtkTreePath to monitor 244 * Throws: ConstructionException GTK+ fails to create the object. 245 */ 246 public this (TreeModelIF model, TreePath path) 247 { 248 // GtkTreeRowReference * gtk_tree_row_reference_new (GtkTreeModel *model, GtkTreePath *path); 249 auto p = gtk_tree_row_reference_new((model is null) ? null : model.getTreeModelTStruct(), (path is null) ? null : path.getTreePathStruct()); 250 if(p is null) 251 { 252 throw new ConstructionException("null returned by gtk_tree_row_reference_new((model is null) ? null : model.getTreeModelTStruct(), (path is null) ? null : path.getTreePathStruct())"); 253 } 254 this(cast(GtkTreeRowReference*) p); 255 } 256 257 /** 258 * You do not need to use this function. 259 * Creates a row reference based on path. 260 * This reference will keep pointing to the node pointed to 261 * by path, so long as it exists. If path isn't a valid 262 * path in model, then NULL is returned. However, unlike 263 * references created with gtk_tree_row_reference_new(), it 264 * does not listen to the model for changes. The creator of 265 * the row reference must do this explicitly using 266 * gtk_tree_row_reference_inserted(), gtk_tree_row_reference_deleted(), 267 * gtk_tree_row_reference_reordered(). 268 * These functions must be called exactly once per proxy when the 269 * corresponding signal on the model is emitted. This single call 270 * updates all row references for that proxy. Since built-in GTK+ 271 * objects like GtkTreeView already use this mechanism internally, 272 * using them as the proxy object will produce unpredictable results. 273 * Further more, passing the same object as model and proxy 274 * doesn't work for reasons of internal implementation. 275 * This type of row reference is primarily meant by structures that 276 * need to carefully monitor exactly when a row reference updates 277 * itself, and is not generally needed by most applications. 278 * Params: 279 * proxy = a proxy GObject 280 * model = a GtkTreeModel 281 * path = a valid GtkTreePath to monitor 282 * Throws: ConstructionException GTK+ fails to create the object. 283 */ 284 public this (ObjectG proxy, TreeModelIF model, TreePath path) 285 { 286 // GtkTreeRowReference * gtk_tree_row_reference_new_proxy (GObject *proxy, GtkTreeModel *model, GtkTreePath *path); 287 auto p = gtk_tree_row_reference_new_proxy((proxy is null) ? null : proxy.getObjectGStruct(), (model is null) ? null : model.getTreeModelTStruct(), (path is null) ? null : path.getTreePathStruct()); 288 if(p is null) 289 { 290 throw new ConstructionException("null returned by gtk_tree_row_reference_new_proxy((proxy is null) ? null : proxy.getObjectGStruct(), (model is null) ? null : model.getTreeModelTStruct(), (path is null) ? null : path.getTreePathStruct())"); 291 } 292 this(cast(GtkTreeRowReference*) p); 293 } 294 295 /** 296 * Returns the model that the row reference is monitoring. 297 * Since 2.8 298 * Returns: the model. [transfer none] 299 */ 300 public TreeModelIF getModel() 301 { 302 // GtkTreeModel * gtk_tree_row_reference_get_model (GtkTreeRowReference *reference); 303 auto p = gtk_tree_row_reference_get_model(gtkTreeRowReference); 304 305 if(p is null) 306 { 307 return null; 308 } 309 310 return ObjectG.getDObject!(TreeModel, TreeModelIF)(cast(GtkTreeModel*) p); 311 } 312 313 /** 314 * Returns a path that the row reference currently points to, 315 * or NULL if the path pointed to is no longer valid. 316 * Returns: a current path, or NULL 317 */ 318 public TreePath getPath() 319 { 320 // GtkTreePath * gtk_tree_row_reference_get_path (GtkTreeRowReference *reference); 321 auto p = gtk_tree_row_reference_get_path(gtkTreeRowReference); 322 323 if(p is null) 324 { 325 return null; 326 } 327 328 return ObjectG.getDObject!(TreePath)(cast(GtkTreePath*) p); 329 } 330 331 /** 332 * Returns TRUE if the reference is non-NULL and refers to 333 * a current valid path. 334 * Returns: TRUE if reference points to a valid path 335 */ 336 public int valid() 337 { 338 // gboolean gtk_tree_row_reference_valid (GtkTreeRowReference *reference); 339 return gtk_tree_row_reference_valid(gtkTreeRowReference); 340 } 341 342 /** 343 * Free's reference. reference may be NULL 344 */ 345 public void free() 346 { 347 // void gtk_tree_row_reference_free (GtkTreeRowReference *reference); 348 gtk_tree_row_reference_free(gtkTreeRowReference); 349 } 350 351 /** 352 * Copies a GtkTreeRowReference. 353 * Since 2.2 354 * Returns: a copy of reference 355 */ 356 public TreeRowReference copy() 357 { 358 // GtkTreeRowReference * gtk_tree_row_reference_copy (GtkTreeRowReference *reference); 359 auto p = gtk_tree_row_reference_copy(gtkTreeRowReference); 360 361 if(p is null) 362 { 363 return null; 364 } 365 366 return ObjectG.getDObject!(TreeRowReference)(cast(GtkTreeRowReference*) p); 367 } 368 369 /** 370 * Lets a set of row reference created by 371 * gtk_tree_row_reference_new_proxy() know that the 372 * model emitted the "row-inserted" signal. 373 * Params: 374 * proxy = a GObject 375 * path = the row position that was inserted 376 */ 377 public static void inserted(ObjectG proxy, TreePath path) 378 { 379 // void gtk_tree_row_reference_inserted (GObject *proxy, GtkTreePath *path); 380 gtk_tree_row_reference_inserted((proxy is null) ? null : proxy.getObjectGStruct(), (path is null) ? null : path.getTreePathStruct()); 381 } 382 383 /** 384 * Lets a set of row reference created by 385 * gtk_tree_row_reference_new_proxy() know that the 386 * model emitted the "row-deleted" signal. 387 * Params: 388 * proxy = a GObject 389 * path = the path position that was deleted 390 */ 391 public static void deleted(ObjectG proxy, TreePath path) 392 { 393 // void gtk_tree_row_reference_deleted (GObject *proxy, GtkTreePath *path); 394 gtk_tree_row_reference_deleted((proxy is null) ? null : proxy.getObjectGStruct(), (path is null) ? null : path.getTreePathStruct()); 395 } 396 397 /** 398 * Lets a set of row reference created by 399 * gtk_tree_row_reference_new_proxy() know that the 400 * model emitted the "rows-reordered" signal. 401 * Params: 402 * proxy = a GObject 403 * path = the parent path of the reordered signal 404 * iter = the iter pointing to the parent of the reordered 405 * newOrder = the new order of rows 406 */ 407 public static void reordered(ObjectG proxy, TreePath path, TreeIter iter, int[] newOrder) 408 { 409 // void gtk_tree_row_reference_reordered (GObject *proxy, GtkTreePath *path, GtkTreeIter *iter, gint *new_order); 410 gtk_tree_row_reference_reordered((proxy is null) ? null : proxy.getObjectGStruct(), (path is null) ? null : path.getTreePathStruct(), (iter is null) ? null : iter.getTreeIterStruct(), newOrder.ptr); 411 } 412 }