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