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