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 = GtkTreeModelFilter.html 27 * outPack = gtk 28 * outFile = TreeModelFilter 29 * strct = GtkTreeModelFilter 30 * realStrct= 31 * ctorStrct=GtkTreeModel 32 * clss = TreeModelFilter 33 * interf = 34 * class Code: Yes 35 * interface Code: No 36 * template for: 37 * extend = 38 * implements: 39 * - TreeModelIF 40 * - TreeDragSourceIF 41 * prefixes: 42 * - gtk_tree_model_filter_ 43 * omit structs: 44 * omit prefixes: 45 * omit code: 46 * omit signals: 47 * imports: 48 * - gtk.TreeIter 49 * - gtk.TreeModel 50 * - gtk.TreeModelIF 51 * - gtk.TreePath 52 * - gtk.TreeModelT 53 * - gtk.TreeDragSourceT 54 * - gtk.TreeDragSourceIF 55 * structWrap: 56 * - GtkTreeIter* -> TreeIter 57 * - GtkTreeModel* -> TreeModelIF 58 * - GtkTreePath* -> TreePath 59 * module aliases: 60 * local aliases: 61 * overrides: 62 */ 63 64 module gtk.TreeModelFilter; 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 gtk.TreeIter; 73 private import gtk.TreeModel; 74 private import gtk.TreeModelIF; 75 private import gtk.TreePath; 76 private import gtk.TreeModelT; 77 private import gtk.TreeDragSourceT; 78 private import gtk.TreeDragSourceIF; 79 80 81 private import gobject.ObjectG; 82 83 /** 84 * A GtkTreeModelFilter is a tree model which wraps another tree model, 85 * and can do the following things: 86 * 87 * Filter specific rows, based on data from a "visible column", a column 88 * storing booleans indicating whether the row should be filtered or not, 89 * or based on the return value of a "visible function", which gets a 90 * model, iter and user_data and returns a boolean indicating whether the 91 * row should be filtered or not. 92 * 93 * Modify the "appearance" of the model, using a modify function. 94 * This is extremely powerful and allows for just changing 95 * some values and also for creating a completely different model based on 96 * the given child model. 97 * 98 * Set a different root node, also known as a "virtual root". You can pass in 99 * a GtkTreePath indicating the root node for the filter at construction time. 100 * 101 * The basic API is similar to GtkTreeModelSort. For an example on its usage, 102 * see the section on GtkTreeModelSort. 103 * 104 * When using GtkTreeModelFilter, it is important to realize that 105 * GtkTreeModelFilter maintains an internal cache of all nodes which are 106 * visible in its clients. The cache is likely to be a subtree of the tree 107 * exposed by the child model. GtkTreeModelFilter will not cache the entire 108 * child model when unnecessary to not compromise the caching mechanism 109 * that is exposed by the reference counting scheme. If the child model 110 * implements reference counting, unnecessary signals may not be emitted 111 * because of reference counting rule 3, see the GtkTreeModel 112 * documentation. (Note that e.g. GtkTreeStore does not implement 113 * reference counting and will always emit all signals, even when 114 * the receiving node is not visible). 115 * 116 * Because of this, limitations for possible visible functions do apply. 117 * In general, visible functions should only use data or properties from 118 * the node for which the visibility state must be determined, its siblings 119 * or its parents. Usually, having a dependency on the state of any child 120 * node is not possible, unless references are taken on these explicitly. 121 * When no such reference exists, no signals may be received for these child 122 * nodes (see reference couting rule number 3 in the GtkTreeModel section). 123 * 124 * Determining the visibility state of a given node based on the state 125 * of its child nodes is a frequently occurring use case. Therefore, 126 * GtkTreeModelFilter explicitly supports this. For example, when a node 127 * does not have any children, you might not want the node to be visible. 128 * As soon as the first row is added to the node's child level (or the 129 * last row removed), the node's visibility should be updated. 130 * 131 * This introduces a dependency from the node on its child nodes. In order 132 * to accommodate this, GtkTreeModelFilter must make sure the necesary 133 * signals are received from the child model. This is achieved by building, 134 * for all nodes which are exposed as visible nodes to GtkTreeModelFilter's 135 * clients, the child level (if any) and take a reference on the first node 136 * in this level. Furthermore, for every row-inserted, row-changed or 137 * row-deleted signal (also these which were not handled because the node 138 * was not cached), GtkTreeModelFilter will check if the visibility state 139 * of any parent node has changed. 140 * 141 * Beware, however, that this explicit support is limited to these two 142 * cases. For example, if you want a node to be visible only if two nodes 143 * in a child's child level (2 levels deeper) are visible, you are on your 144 * own. In this case, either rely on GtkTreeStore to emit all signals 145 * because it does not implement reference counting, or for models that 146 * do implement reference counting, obtain references on these child levels 147 * yourself. 148 */ 149 public class TreeModelFilter : ObjectG, TreeModelIF, TreeDragSourceIF 150 { 151 152 /** the main Gtk struct */ 153 protected GtkTreeModelFilter* gtkTreeModelFilter; 154 155 156 /** Get the main Gtk struct */ 157 public GtkTreeModelFilter* getTreeModelFilterStruct() 158 { 159 return gtkTreeModelFilter; 160 } 161 162 163 /** the main Gtk struct as a void* */ 164 protected override void* getStruct() 165 { 166 return cast(void*)gtkTreeModelFilter; 167 } 168 169 /** 170 * Sets our main struct and passes it to the parent class 171 */ 172 public this (GtkTreeModelFilter* gtkTreeModelFilter) 173 { 174 super(cast(GObject*)gtkTreeModelFilter); 175 this.gtkTreeModelFilter = gtkTreeModelFilter; 176 } 177 178 protected override void setStruct(GObject* obj) 179 { 180 super.setStruct(obj); 181 gtkTreeModelFilter = cast(GtkTreeModelFilter*)obj; 182 } 183 184 // add the TreeModel capabilities 185 mixin TreeModelT!(GtkTreeModelFilter); 186 187 // add the TreeDragSource capabilities 188 mixin TreeDragSourceT!(GtkTreeModelFilter); 189 190 /** 191 */ 192 193 /** 194 * Creates a new GtkTreeModel, with child_model as the child_model 195 * and root as the virtual root. 196 * Since 2.4 197 * Params: 198 * childModel = A GtkTreeModel. 199 * root = A GtkTreePath or NULL. [allow-none] 200 * Throws: ConstructionException GTK+ fails to create the object. 201 */ 202 public this (TreeModelIF childModel, TreePath root) 203 { 204 // GtkTreeModel * gtk_tree_model_filter_new (GtkTreeModel *child_model, GtkTreePath *root); 205 auto p = gtk_tree_model_filter_new((childModel is null) ? null : childModel.getTreeModelTStruct(), (root is null) ? null : root.getTreePathStruct()); 206 if(p is null) 207 { 208 throw new ConstructionException("null returned by gtk_tree_model_filter_new((childModel is null) ? null : childModel.getTreeModelTStruct(), (root is null) ? null : root.getTreePathStruct())"); 209 } 210 this(cast(GtkTreeModelFilter*) p); 211 } 212 213 /** 214 * Sets the visible function used when filtering the filter to be func. The 215 * function should return TRUE if the given row should be visible and 216 * FALSE otherwise. 217 * If the condition calculated by the function changes over time (e.g. because 218 * it depends on some global parameters), you must call 219 * gtk_tree_model_filter_refilter() to keep the visibility information of 220 * the model uptodate. 221 * Note that func is called whenever a row is inserted, when it may still be 222 * empty. The visible function should therefore take special care of empty 223 * rows, like in the example below. 224 * $(DDOC_COMMENT example) 225 * Since 2.4 226 * Params: 227 * func = A GtkTreeModelFilterVisibleFunc, the visible function. 228 * data = User data to pass to the visible function, or NULL. [allow-none] 229 * destroy = Destroy notifier of data, or NULL. [allow-none] 230 */ 231 public void setVisibleFunc(GtkTreeModelFilterVisibleFunc func, void* data, GDestroyNotify destroy) 232 { 233 // void gtk_tree_model_filter_set_visible_func (GtkTreeModelFilter *filter, GtkTreeModelFilterVisibleFunc func, gpointer data, GDestroyNotify destroy); 234 gtk_tree_model_filter_set_visible_func(gtkTreeModelFilter, func, data, destroy); 235 } 236 237 /** 238 * With the n_columns and types parameters, you give an array of column 239 * types for this model (which will be exposed to the parent model/view). 240 * The func, data and destroy parameters are for specifying the modify 241 * function. The modify function will get called for each 242 * data access, the goal of the modify function is to return the data which 243 * should be displayed at the location specified using the parameters of the 244 * modify function. 245 * Since 2.4 246 * Params: 247 * types = The GTypes of the columns. [array length=n_columns] 248 * func = A GtkTreeModelFilterModifyFunc 249 * data = User data to pass to the modify function, or NULL. [allow-none] 250 * destroy = Destroy notifier of data, or NULL. [allow-none] 251 */ 252 public void setModifyFunc(GType[] types, GtkTreeModelFilterModifyFunc func, void* data, GDestroyNotify destroy) 253 { 254 // void gtk_tree_model_filter_set_modify_func (GtkTreeModelFilter *filter, gint n_columns, GType *types, GtkTreeModelFilterModifyFunc func, gpointer data, GDestroyNotify destroy); 255 gtk_tree_model_filter_set_modify_func(gtkTreeModelFilter, cast(int) types.length, types.ptr, func, data, destroy); 256 } 257 258 /** 259 * Sets column of the child_model to be the column where filter should 260 * look for visibility information. columns should be a column of type 261 * G_TYPE_BOOLEAN, where TRUE means that a row is visible, and FALSE 262 * if not. 263 * Since 2.4 264 * Params: 265 * column = A gint which is the column containing the visible information. 266 */ 267 public void setVisibleColumn(int column) 268 { 269 // void gtk_tree_model_filter_set_visible_column (GtkTreeModelFilter *filter, gint column); 270 gtk_tree_model_filter_set_visible_column(gtkTreeModelFilter, column); 271 } 272 273 /** 274 * Returns a pointer to the child model of filter. 275 * Since 2.4 276 * Returns: A pointer to a GtkTreeModel. [transfer none] 277 */ 278 public TreeModelIF getModel() 279 { 280 // GtkTreeModel * gtk_tree_model_filter_get_model (GtkTreeModelFilter *filter); 281 auto p = gtk_tree_model_filter_get_model(gtkTreeModelFilter); 282 283 if(p is null) 284 { 285 return null; 286 } 287 288 return ObjectG.getDObject!(TreeModel, TreeModelIF)(cast(GtkTreeModel*) p); 289 } 290 291 /** 292 * Sets filter_iter to point to the row in filter that corresponds to the 293 * row pointed at by child_iter. If filter_iter was not set, FALSE is 294 * returned. 295 * Since 2.4 296 * Params: 297 * filter = A GtkTreeModelFilter. 298 * filterIter = An uninitialized GtkTreeIter. [out] 299 * childIter = A valid GtkTreeIter pointing to a row on the child model. 300 * Returns: TRUE, if filter_iter was set, i.e. if child_iter is a valid iterator pointing to a visible row in child model. 301 */ 302 public int convertChildIterToIter(TreeIter filterIter, TreeIter childIter) 303 { 304 // gboolean gtk_tree_model_filter_convert_child_iter_to_iter (GtkTreeModelFilter *filter, GtkTreeIter *filter_iter, GtkTreeIter *child_iter); 305 return gtk_tree_model_filter_convert_child_iter_to_iter(gtkTreeModelFilter, (filterIter is null) ? null : filterIter.getTreeIterStruct(), (childIter is null) ? null : childIter.getTreeIterStruct()); 306 } 307 308 /** 309 * Sets child_iter to point to the row pointed to by filter_iter. 310 * Since 2.4 311 * Params: 312 * filter = A GtkTreeModelFilter. 313 * childIter = An uninitialized GtkTreeIter. [out] 314 * filterIter = A valid GtkTreeIter pointing to a row on filter. 315 */ 316 public void convertIterToChildIter(TreeIter childIter, TreeIter filterIter) 317 { 318 // void gtk_tree_model_filter_convert_iter_to_child_iter (GtkTreeModelFilter *filter, GtkTreeIter *child_iter, GtkTreeIter *filter_iter); 319 gtk_tree_model_filter_convert_iter_to_child_iter(gtkTreeModelFilter, (childIter is null) ? null : childIter.getTreeIterStruct(), (filterIter is null) ? null : filterIter.getTreeIterStruct()); 320 } 321 322 /** 323 * Converts child_path to a path relative to filter. That is, child_path 324 * points to a path in the child model. The rerturned path will point to the 325 * same row in the filtered model. If child_path isn't a valid path on the 326 * child model or points to a row which is not visible in filter, then NULL 327 * is returned. 328 * Since 2.4 329 * Params: 330 * childPath = A GtkTreePath to convert. 331 * Returns: A newly allocated GtkTreePath, or NULL. 332 */ 333 public TreePath convertChildPathToPath(TreePath childPath) 334 { 335 // GtkTreePath * gtk_tree_model_filter_convert_child_path_to_path (GtkTreeModelFilter *filter, GtkTreePath *child_path); 336 auto p = gtk_tree_model_filter_convert_child_path_to_path(gtkTreeModelFilter, (childPath is null) ? null : childPath.getTreePathStruct()); 337 338 if(p is null) 339 { 340 return null; 341 } 342 343 return ObjectG.getDObject!(TreePath)(cast(GtkTreePath*) p); 344 } 345 346 /** 347 * Converts filter_path to a path on the child model of filter. That is, 348 * filter_path points to a location in filter. The returned path will 349 * point to the same location in the model not being filtered. If filter_path 350 * does not point to a location in the child model, NULL is returned. 351 * Since 2.4 352 * Params: 353 * filter = A GtkTreeModelFilter. 354 * filterPath = A GtkTreePath to convert. 355 * Returns: A newly allocated GtkTreePath, or NULL. 356 */ 357 public TreePath convertPathToChildPath(TreePath filterPath) 358 { 359 // GtkTreePath * gtk_tree_model_filter_convert_path_to_child_path (GtkTreeModelFilter *filter, GtkTreePath *filter_path); 360 auto p = gtk_tree_model_filter_convert_path_to_child_path(gtkTreeModelFilter, (filterPath is null) ? null : filterPath.getTreePathStruct()); 361 362 if(p is null) 363 { 364 return null; 365 } 366 367 return ObjectG.getDObject!(TreePath)(cast(GtkTreePath*) p); 368 } 369 370 /** 371 * Emits ::row_changed for each row in the child model, which causes 372 * the filter to re-evaluate whether a row is visible or not. 373 * Since 2.4 374 * Params: 375 * filter = A GtkTreeModelFilter. 376 */ 377 public void refilter() 378 { 379 // void gtk_tree_model_filter_refilter (GtkTreeModelFilter *filter); 380 gtk_tree_model_filter_refilter(gtkTreeModelFilter); 381 } 382 383 /** 384 * This function should almost never be called. It clears the filter 385 * of any cached iterators that haven't been reffed with 386 * gtk_tree_model_ref_node(). This might be useful if the child model 387 * being filtered is static (and doesn't change often) and there has been 388 * a lot of unreffed access to nodes. As a side effect of this function, 389 * all unreffed iters will be invalid. 390 * Since 2.4 391 */ 392 public void clearCache() 393 { 394 // void gtk_tree_model_filter_clear_cache (GtkTreeModelFilter *filter); 395 gtk_tree_model_filter_clear_cache(gtkTreeModelFilter); 396 } 397 }