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.TreeModel; 33 private import gtk.TreeModelIF; 34 private import gtk.TreeModelT; 35 private import gtk.TreePath; 36 private import gtkc.gtk; 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() 114 { 115 return gtkTreeModelFilter; 116 } 117 118 /** the main Gtk struct as a void* */ 119 protected override void* getStruct() 120 { 121 return cast(void*)gtkTreeModelFilter; 122 } 123 124 protected override void setStruct(GObject* obj) 125 { 126 gtkTreeModelFilter = cast(GtkTreeModelFilter*)obj; 127 super.setStruct(obj); 128 } 129 130 /** 131 * Sets our main struct and passes it to the parent class. 132 */ 133 public this (GtkTreeModelFilter* gtkTreeModelFilter, bool ownedRef = false) 134 { 135 this.gtkTreeModelFilter = gtkTreeModelFilter; 136 super(cast(GObject*)gtkTreeModelFilter, ownedRef); 137 } 138 139 // add the TreeDragSource capabilities 140 mixin TreeDragSourceT!(GtkTreeModelFilter); 141 142 // add the TreeModel capabilities 143 mixin TreeModelT!(GtkTreeModelFilter); 144 145 /** 146 * Creates a new TreeModel, with childModel as the child model 147 * and root as the virtual _root. 148 * 149 * Params: 150 * childModel = A TreeModel. 151 * root = A TreePath or null. 152 * 153 * Throws: A ConstructionException if GTK+ fails to create the object. 154 * 155 * Since: 2.4 156 */ 157 public this(TreeModelIF childModel, TreePath root) 158 { 159 auto p = gtk_tree_model_filter_new(childModel.getTreeModelStruct(), (root is null) ? null : root.getTreePathStruct()); 160 161 if(p is null) 162 { 163 throw new ConstructionException("null returned by gtk_tree_model_filter_new"); 164 } 165 166 this(cast(GtkTreeModelFilter*) p, true); 167 } 168 169 /** 170 */ 171 172 public static GType getType() 173 { 174 return gtk_tree_model_filter_get_type(); 175 } 176 177 /** 178 * This function should almost never be called. It clears the @filter 179 * of any cached iterators that haven’t been reffed with 180 * gtk_tree_model_ref_node(). This might be useful if the child model 181 * being filtered is static (and doesn’t change often) and there has been 182 * a lot of unreffed access to nodes. As a side effect of this function, 183 * all unreffed iters will be invalid. 184 * 185 * Since: 2.4 186 */ 187 public void clearCache() 188 { 189 gtk_tree_model_filter_clear_cache(gtkTreeModelFilter); 190 } 191 192 /** 193 * Sets @filter_iter to point to the row in @filter that corresponds to the 194 * row pointed at by @child_iter. If @filter_iter was not set, %FALSE is 195 * returned. 196 * 197 * Params: 198 * filterIter = An uninitialized #GtkTreeIter. 199 * childIter = A valid #GtkTreeIter pointing to a row on the child model. 200 * 201 * Return: %TRUE, if @filter_iter was set, i.e. if @child_iter is a 202 * valid iterator pointing to a visible row in child model. 203 * 204 * Since: 2.4 205 */ 206 public bool convertChildIterToIter(out TreeIter filterIter, TreeIter childIter) 207 { 208 GtkTreeIter* outfilterIter = new GtkTreeIter; 209 210 auto p = gtk_tree_model_filter_convert_child_iter_to_iter(gtkTreeModelFilter, outfilterIter, (childIter is null) ? null : childIter.getTreeIterStruct()) != 0; 211 212 filterIter = ObjectG.getDObject!(TreeIter)(outfilterIter); 213 214 return p; 215 } 216 217 /** 218 * Converts @child_path to a path relative to @filter. That is, @child_path 219 * points to a path in the child model. The rerturned path will point to the 220 * same row in the filtered model. If @child_path isn’t a valid path on the 221 * child model or points to a row which is not visible in @filter, then %NULL 222 * is returned. 223 * 224 * Params: 225 * childPath = A #GtkTreePath to convert. 226 * 227 * Return: A newly allocated #GtkTreePath, or %NULL. 228 * 229 * Since: 2.4 230 */ 231 public TreePath convertChildPathToPath(TreePath childPath) 232 { 233 auto p = gtk_tree_model_filter_convert_child_path_to_path(gtkTreeModelFilter, (childPath is null) ? null : childPath.getTreePathStruct()); 234 235 if(p is null) 236 { 237 return null; 238 } 239 240 return ObjectG.getDObject!(TreePath)(cast(GtkTreePath*) p); 241 } 242 243 /** 244 * Sets @child_iter to point to the row pointed to by @filter_iter. 245 * 246 * Params: 247 * childIter = An uninitialized #GtkTreeIter. 248 * filterIter = A valid #GtkTreeIter pointing to a row on @filter. 249 * 250 * Since: 2.4 251 */ 252 public void convertIterToChildIter(out TreeIter childIter, TreeIter filterIter) 253 { 254 GtkTreeIter* outchildIter = new GtkTreeIter; 255 256 gtk_tree_model_filter_convert_iter_to_child_iter(gtkTreeModelFilter, outchildIter, (filterIter is null) ? null : filterIter.getTreeIterStruct()); 257 258 childIter = ObjectG.getDObject!(TreeIter)(outchildIter); 259 } 260 261 /** 262 * Converts @filter_path to a path on the child model of @filter. That is, 263 * @filter_path points to a location in @filter. The returned path will 264 * point to the same location in the model not being filtered. If @filter_path 265 * does not point to a location in the child model, %NULL is returned. 266 * 267 * Params: 268 * filterPath = A #GtkTreePath to convert. 269 * 270 * Return: A newly allocated #GtkTreePath, or %NULL. 271 * 272 * Since: 2.4 273 */ 274 public TreePath convertPathToChildPath(TreePath filterPath) 275 { 276 auto p = gtk_tree_model_filter_convert_path_to_child_path(gtkTreeModelFilter, (filterPath is null) ? null : filterPath.getTreePathStruct()); 277 278 if(p is null) 279 { 280 return null; 281 } 282 283 return ObjectG.getDObject!(TreePath)(cast(GtkTreePath*) p); 284 } 285 286 /** 287 * Returns a pointer to the child model of @filter. 288 * 289 * Return: A pointer to a #GtkTreeModel. 290 * 291 * Since: 2.4 292 */ 293 public TreeModelIF getModel() 294 { 295 auto p = gtk_tree_model_filter_get_model(gtkTreeModelFilter); 296 297 if(p is null) 298 { 299 return null; 300 } 301 302 return ObjectG.getDObject!(TreeModel, TreeModelIF)(cast(GtkTreeModel*) p); 303 } 304 305 /** 306 * Emits ::row_changed for each row in the child model, which causes 307 * the filter to re-evaluate whether a row is visible or not. 308 * 309 * Since: 2.4 310 */ 311 public void refilter() 312 { 313 gtk_tree_model_filter_refilter(gtkTreeModelFilter); 314 } 315 316 /** 317 * With the @n_columns and @types parameters, you give an array of column 318 * types for this model (which will be exposed to the parent model/view). 319 * The @func, @data and @destroy parameters are for specifying the modify 320 * function. The modify function will get called for each 321 * data access, the goal of the modify function is to return the data which 322 * should be displayed at the location specified using the parameters of the 323 * modify function. 324 * 325 * Note that gtk_tree_model_filter_set_modify_func() 326 * can only be called once for a given filter model. 327 * 328 * Params: 329 * nColumns = The number of columns in the filter model. 330 * types = The #GTypes of the columns. 331 * func = A #GtkTreeModelFilterModifyFunc 332 * data = User data to pass to the modify function, or %NULL. 333 * destroy = Destroy notifier of @data, or %NULL. 334 * 335 * Since: 2.4 336 */ 337 public void setModifyFunc(GType[] types, GtkTreeModelFilterModifyFunc func, void* data, GDestroyNotify destroy) 338 { 339 gtk_tree_model_filter_set_modify_func(gtkTreeModelFilter, cast(int)types.length, types.ptr, func, data, destroy); 340 } 341 342 /** 343 * Sets @column of the child_model to be the column where @filter should 344 * look for visibility information. @columns should be a column of type 345 * %G_TYPE_BOOLEAN, where %TRUE means that a row is visible, and %FALSE 346 * if not. 347 * 348 * Note that gtk_tree_model_filter_set_visible_func() or 349 * gtk_tree_model_filter_set_visible_column() can only be called 350 * once for a given filter model. 351 * 352 * Params: 353 * column = A #gint which is the column containing the visible information 354 * 355 * Since: 2.4 356 */ 357 public void setVisibleColumn(int column) 358 { 359 gtk_tree_model_filter_set_visible_column(gtkTreeModelFilter, column); 360 } 361 362 /** 363 * Sets the visible function used when filtering the @filter to be @func. 364 * The function should return %TRUE if the given row should be visible and 365 * %FALSE otherwise. 366 * 367 * If the condition calculated by the function changes over time (e.g. 368 * because it depends on some global parameters), you must call 369 * gtk_tree_model_filter_refilter() to keep the visibility information 370 * of the model up-to-date. 371 * 372 * Note that @func is called whenever a row is inserted, when it may still 373 * be empty. The visible function should therefore take special care of empty 374 * rows, like in the example below. 375 * 376 * |[<!-- language="C" --> 377 * static gboolean 378 * visible_func (GtkTreeModel *model, 379 * GtkTreeIter *iter, 380 * gpointer data) 381 * { 382 * // Visible if row is non-empty and first column is “HI” 383 * gchar *str; 384 * gboolean visible = FALSE; 385 * 386 * gtk_tree_model_get (model, iter, 0, &str, -1); 387 * if (str && strcmp (str, "HI") == 0) 388 * visible = TRUE; 389 * g_free (str); 390 * 391 * return visible; 392 * } 393 * ]| 394 * 395 * Note that gtk_tree_model_filter_set_visible_func() or 396 * gtk_tree_model_filter_set_visible_column() can only be called 397 * once for a given filter model. 398 * 399 * Params: 400 * func = A #GtkTreeModelFilterVisibleFunc, the visible function 401 * data = User data to pass to the visible function, or %NULL 402 * destroy = Destroy notifier of @data, or %NULL 403 * 404 * Since: 2.4 405 */ 406 public void setVisibleFunc(GtkTreeModelFilterVisibleFunc func, void* data, GDestroyNotify destroy) 407 { 408 gtk_tree_model_filter_set_visible_func(gtkTreeModelFilter, func, data, destroy); 409 } 410 }