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