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.RecentFilter;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gtk.BuildableIF;
31 private import gtk.BuildableT;
32 private import gtk.c.functions;
33 public  import gtk.c.types;
34 public  import gtkc.gtktypes;
35 
36 
37 /**
38  * A #GtkRecentFilter can be used to restrict the files being shown
39  * in a #GtkRecentChooser.  Files can be filtered based on their name
40  * (with gtk_recent_filter_add_pattern()), on their mime type (with
41  * gtk_file_filter_add_mime_type()), on the application that has
42  * registered them (with gtk_recent_filter_add_application()), or by
43  * a custom filter function (with gtk_recent_filter_add_custom()).
44  * 
45  * Filtering by mime type handles aliasing and subclassing of mime
46  * types; e.g. a filter for text/plain also matches a file with mime
47  * type application/rtf, since application/rtf is a subclass of text/plain.
48  * Note that #GtkRecentFilter allows wildcards for the subtype of a
49  * mime type, so you can e.g. filter for image/\*.
50  * 
51  * Normally, filters are used by adding them to a #GtkRecentChooser,
52  * see gtk_recent_chooser_add_filter(), but it is also possible to
53  * manually use a filter on a file with gtk_recent_filter_filter().
54  * 
55  * Recently used files are supported since GTK+ 2.10.
56  * 
57  * ## GtkRecentFilter as GtkBuildable
58  * 
59  * The GtkRecentFilter implementation of the GtkBuildable interface
60  * supports adding rules using the <mime-types>, <patterns> and
61  * <applications> elements and listing the rules within. Specifying
62  * a <mime-type>, <pattern> or <application> has the same effect as
63  * calling gtk_recent_filter_add_mime_type(),
64  * gtk_recent_filter_add_pattern() or gtk_recent_filter_add_application().
65  * 
66  * An example of a UI definition fragment specifying GtkRecentFilter rules:
67  * |[
68  * <object class="GtkRecentFilter">
69  * <mime-types>
70  * <mime-type>text/plain</mime-type>
71  * <mime-type>image/png</mime-type>
72  * </mime-types>
73  * <patterns>
74  * <pattern>*.txt</pattern>
75  * <pattern>*.png</pattern>
76  * </patterns>
77  * <applications>
78  * <application>gimp</application>
79  * <application>gedit</application>
80  * <application>glade</application>
81  * </applications>
82  * </object>
83  * ]|
84  */
85 public class RecentFilter : ObjectG, BuildableIF
86 {
87 	/** the main Gtk struct */
88 	protected GtkRecentFilter* gtkRecentFilter;
89 
90 	/** Get the main Gtk struct */
91 	public GtkRecentFilter* getRecentFilterStruct(bool transferOwnership = false)
92 	{
93 		if (transferOwnership)
94 			ownedRef = false;
95 		return gtkRecentFilter;
96 	}
97 
98 	/** the main Gtk struct as a void* */
99 	protected override void* getStruct()
100 	{
101 		return cast(void*)gtkRecentFilter;
102 	}
103 
104 	protected override void setStruct(GObject* obj)
105 	{
106 		gtkRecentFilter = cast(GtkRecentFilter*)obj;
107 		super.setStruct(obj);
108 	}
109 
110 	/**
111 	 * Sets our main struct and passes it to the parent class.
112 	 */
113 	public this (GtkRecentFilter* gtkRecentFilter, bool ownedRef = false)
114 	{
115 		this.gtkRecentFilter = gtkRecentFilter;
116 		super(cast(GObject*)gtkRecentFilter, ownedRef);
117 	}
118 
119 	// add the Buildable capabilities
120 	mixin BuildableT!(GtkRecentFilter);
121 
122 
123 	/** */
124 	public static GType getType()
125 	{
126 		return gtk_recent_filter_get_type();
127 	}
128 
129 	/**
130 	 * Creates a new #GtkRecentFilter with no rules added to it.
131 	 * Such filter does not accept any recently used resources, so is not
132 	 * particularly useful until you add rules with
133 	 * gtk_recent_filter_add_pattern(), gtk_recent_filter_add_mime_type(),
134 	 * gtk_recent_filter_add_application(), gtk_recent_filter_add_age().
135 	 * To create a filter that accepts any recently used resource, use:
136 	 * |[<!-- language="C" -->
137 	 * GtkRecentFilter *filter = gtk_recent_filter_new ();
138 	 * gtk_recent_filter_add_pattern (filter, "*");
139 	 * ]|
140 	 *
141 	 * Returns: a new #GtkRecentFilter
142 	 *
143 	 * Since: 2.10
144 	 *
145 	 * Throws: ConstructionException GTK+ fails to create the object.
146 	 */
147 	public this()
148 	{
149 		auto p = gtk_recent_filter_new();
150 
151 		if(p is null)
152 		{
153 			throw new ConstructionException("null returned by new");
154 		}
155 
156 		this(cast(GtkRecentFilter*) p);
157 	}
158 
159 	/**
160 	 * Adds a rule that allows resources based on their age - that is, the number
161 	 * of days elapsed since they were last modified.
162 	 *
163 	 * Params:
164 	 *     days = number of days
165 	 *
166 	 * Since: 2.10
167 	 */
168 	public void addAge(int days)
169 	{
170 		gtk_recent_filter_add_age(gtkRecentFilter, days);
171 	}
172 
173 	/**
174 	 * Adds a rule that allows resources based on the name of the application
175 	 * that has registered them.
176 	 *
177 	 * Params:
178 	 *     application = an application name
179 	 *
180 	 * Since: 2.10
181 	 */
182 	public void addApplication(string application)
183 	{
184 		gtk_recent_filter_add_application(gtkRecentFilter, Str.toStringz(application));
185 	}
186 
187 	/**
188 	 * Adds a rule to a filter that allows resources based on a custom callback
189 	 * function. The bitfield @needed which is passed in provides information
190 	 * about what sorts of information that the filter function needs;
191 	 * this allows GTK+ to avoid retrieving expensive information when
192 	 * it isn’t needed by the filter.
193 	 *
194 	 * Params:
195 	 *     needed = bitfield of flags indicating the information that the custom
196 	 *         filter function needs.
197 	 *     func = callback function; if the function returns %TRUE, then
198 	 *         the file will be displayed.
199 	 *     data = data to pass to @func
200 	 *     dataDestroy = function to call to free @data when it is no longer needed.
201 	 *
202 	 * Since: 2.10
203 	 */
204 	public void addCustom(GtkRecentFilterFlags needed, GtkRecentFilterFunc func, void* data, GDestroyNotify dataDestroy)
205 	{
206 		gtk_recent_filter_add_custom(gtkRecentFilter, needed, func, data, dataDestroy);
207 	}
208 
209 	/**
210 	 * Adds a rule that allows resources based on the name of the group
211 	 * to which they belong
212 	 *
213 	 * Params:
214 	 *     group = a group name
215 	 *
216 	 * Since: 2.10
217 	 */
218 	public void addGroup(string group)
219 	{
220 		gtk_recent_filter_add_group(gtkRecentFilter, Str.toStringz(group));
221 	}
222 
223 	/**
224 	 * Adds a rule that allows resources based on their registered MIME type.
225 	 *
226 	 * Params:
227 	 *     mimeType = a MIME type
228 	 *
229 	 * Since: 2.10
230 	 */
231 	public void addMimeType(string mimeType)
232 	{
233 		gtk_recent_filter_add_mime_type(gtkRecentFilter, Str.toStringz(mimeType));
234 	}
235 
236 	/**
237 	 * Adds a rule that allows resources based on a pattern matching their
238 	 * display name.
239 	 *
240 	 * Params:
241 	 *     pattern = a file pattern
242 	 *
243 	 * Since: 2.10
244 	 */
245 	public void addPattern(string pattern)
246 	{
247 		gtk_recent_filter_add_pattern(gtkRecentFilter, Str.toStringz(pattern));
248 	}
249 
250 	/**
251 	 * Adds a rule allowing image files in the formats supported
252 	 * by GdkPixbuf.
253 	 *
254 	 * Since: 2.10
255 	 */
256 	public void addPixbufFormats()
257 	{
258 		gtk_recent_filter_add_pixbuf_formats(gtkRecentFilter);
259 	}
260 
261 	/**
262 	 * Tests whether a file should be displayed according to @filter.
263 	 * The #GtkRecentFilterInfo @filter_info should include
264 	 * the fields returned from gtk_recent_filter_get_needed(), and
265 	 * must set the #GtkRecentFilterInfo.contains field of @filter_info
266 	 * to indicate which fields have been set.
267 	 *
268 	 * This function will not typically be used by applications; it
269 	 * is intended principally for use in the implementation of
270 	 * #GtkRecentChooser.
271 	 *
272 	 * Params:
273 	 *     filterInfo = a #GtkRecentFilterInfo containing information
274 	 *         about a recently used resource
275 	 *
276 	 * Returns: %TRUE if the file should be displayed
277 	 *
278 	 * Since: 2.10
279 	 */
280 	public bool filter(GtkRecentFilterInfo* filterInfo)
281 	{
282 		return gtk_recent_filter_filter(gtkRecentFilter, filterInfo) != 0;
283 	}
284 
285 	/**
286 	 * Gets the human-readable name for the filter.
287 	 * See gtk_recent_filter_set_name().
288 	 *
289 	 * Returns: the name of the filter, or %NULL.  The returned string
290 	 *     is owned by the filter object and should not be freed.
291 	 *
292 	 * Since: 2.10
293 	 */
294 	public string getName()
295 	{
296 		return Str.toString(gtk_recent_filter_get_name(gtkRecentFilter));
297 	}
298 
299 	/**
300 	 * Gets the fields that need to be filled in for the #GtkRecentFilterInfo
301 	 * passed to gtk_recent_filter_filter()
302 	 *
303 	 * This function will not typically be used by applications; it
304 	 * is intended principally for use in the implementation of
305 	 * #GtkRecentChooser.
306 	 *
307 	 * Returns: bitfield of flags indicating needed fields when
308 	 *     calling gtk_recent_filter_filter()
309 	 *
310 	 * Since: 2.10
311 	 */
312 	public GtkRecentFilterFlags getNeeded()
313 	{
314 		return gtk_recent_filter_get_needed(gtkRecentFilter);
315 	}
316 
317 	/**
318 	 * Sets the human-readable name of the filter; this is the string
319 	 * that will be displayed in the recently used resources selector
320 	 * user interface if there is a selectable list of filters.
321 	 *
322 	 * Params:
323 	 *     name = then human readable name of @filter
324 	 *
325 	 * Since: 2.10
326 	 */
327 	public void setName(string name)
328 	{
329 		gtk_recent_filter_set_name(gtkRecentFilter, Str.toStringz(name));
330 	}
331 }