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