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