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.RecentManager;
26 
27 private import glib.ConstructionException;
28 private import glib.ErrorG;
29 private import glib.GException;
30 private import glib.ListG;
31 private import glib.Str;
32 private import gobject.ObjectG;
33 private import gobject.Signals;
34 private import gtk.RecentInfo;
35 private import gtk.c.functions;
36 public  import gtk.c.types;
37 public  import gtkc.gtktypes;
38 private import std.algorithm;
39 
40 
41 /**
42  * #GtkRecentManager provides a facility for adding, removing and
43  * looking up recently used files. Each recently used file is
44  * identified by its URI, and has meta-data associated to it, like
45  * the names and command lines of the applications that have
46  * registered it, the number of time each application has registered
47  * the same file, the mime type of the file and whether the file
48  * should be displayed only by the applications that have
49  * registered it.
50  * 
51  * The recently used files list is per user.
52  * 
53  * The #GtkRecentManager acts like a database of all the recently
54  * used files. You can create new #GtkRecentManager objects, but
55  * it is more efficient to use the default manager created by GTK+.
56  * 
57  * Adding a new recently used file is as simple as:
58  * 
59  * |[<!-- language="C" -->
60  * GtkRecentManager *manager;
61  * 
62  * manager = gtk_recent_manager_get_default ();
63  * gtk_recent_manager_add_item (manager, file_uri);
64  * ]|
65  * 
66  * The #GtkRecentManager will try to gather all the needed information
67  * from the file itself through GIO.
68  * 
69  * Looking up the meta-data associated with a recently used file
70  * given its URI requires calling gtk_recent_manager_lookup_item():
71  * 
72  * |[<!-- language="C" -->
73  * GtkRecentManager *manager;
74  * GtkRecentInfo *info;
75  * GError *error = NULL;
76  * 
77  * manager = gtk_recent_manager_get_default ();
78  * info = gtk_recent_manager_lookup_item (manager, file_uri, &error);
79  * if (error)
80  * {
81  * g_warning ("Could not find the file: %s", error->message);
82  * g_error_free (error);
83  * }
84  * else
85  * {
86  * // Use the info object
87  * gtk_recent_info_unref (info);
88  * }
89  * ]|
90  * 
91  * In order to retrieve the list of recently used files, you can use
92  * gtk_recent_manager_get_items(), which returns a list of #GtkRecentInfo-structs.
93  * 
94  * A #GtkRecentManager is the model used to populate the contents of
95  * one, or more #GtkRecentChooser implementations.
96  * 
97  * Note that the maximum age of the recently used files list is
98  * controllable through the #GtkSettings:gtk-recent-files-max-age
99  * property.
100  * 
101  * Recently used files are supported since GTK+ 2.10.
102  *
103  * Since: 2.10
104  */
105 public class RecentManager : ObjectG
106 {
107 	/** the main Gtk struct */
108 	protected GtkRecentManager* gtkRecentManager;
109 
110 	/** Get the main Gtk struct */
111 	public GtkRecentManager* getRecentManagerStruct(bool transferOwnership = false)
112 	{
113 		if (transferOwnership)
114 			ownedRef = false;
115 		return gtkRecentManager;
116 	}
117 
118 	/** the main Gtk struct as a void* */
119 	protected override void* getStruct()
120 	{
121 		return cast(void*)gtkRecentManager;
122 	}
123 
124 	protected override void setStruct(GObject* obj)
125 	{
126 		gtkRecentManager = cast(GtkRecentManager*)obj;
127 		super.setStruct(obj);
128 	}
129 
130 	/**
131 	 * Sets our main struct and passes it to the parent class.
132 	 */
133 	public this (GtkRecentManager* gtkRecentManager, bool ownedRef = false)
134 	{
135 		this.gtkRecentManager = gtkRecentManager;
136 		super(cast(GObject*)gtkRecentManager, ownedRef);
137 	}
138 
139 
140 	/** */
141 	public static GType getType()
142 	{
143 		return gtk_recent_manager_get_type();
144 	}
145 
146 	/**
147 	 * Creates a new recent manager object. Recent manager objects are used to
148 	 * handle the list of recently used resources. A #GtkRecentManager object
149 	 * monitors the recently used resources list, and emits the “changed” signal
150 	 * each time something inside the list changes.
151 	 *
152 	 * #GtkRecentManager objects are expensive: be sure to create them only when
153 	 * needed. You should use gtk_recent_manager_get_default() instead.
154 	 *
155 	 * Returns: A newly created #GtkRecentManager object
156 	 *
157 	 * Since: 2.10
158 	 *
159 	 * Throws: ConstructionException GTK+ fails to create the object.
160 	 */
161 	public this()
162 	{
163 		auto p = gtk_recent_manager_new();
164 
165 		if(p is null)
166 		{
167 			throw new ConstructionException("null returned by new");
168 		}
169 
170 		this(cast(GtkRecentManager*) p, true);
171 	}
172 
173 	/**
174 	 * Gets a unique instance of #GtkRecentManager, that you can share
175 	 * in your application without caring about memory management.
176 	 *
177 	 * Returns: A unique #GtkRecentManager. Do not ref or
178 	 *     unref it.
179 	 *
180 	 * Since: 2.10
181 	 */
182 	public static RecentManager getDefault()
183 	{
184 		auto p = gtk_recent_manager_get_default();
185 
186 		if(p is null)
187 		{
188 			return null;
189 		}
190 
191 		return ObjectG.getDObject!(RecentManager)(cast(GtkRecentManager*) p);
192 	}
193 
194 	/**
195 	 * Adds a new resource, pointed by @uri, into the recently used
196 	 * resources list, using the metadata specified inside the
197 	 * #GtkRecentData-struct passed in @recent_data.
198 	 *
199 	 * The passed URI will be used to identify this resource inside the
200 	 * list.
201 	 *
202 	 * In order to register the new recently used resource, metadata about
203 	 * the resource must be passed as well as the URI; the metadata is
204 	 * stored in a #GtkRecentData-struct, which must contain the MIME
205 	 * type of the resource pointed by the URI; the name of the application
206 	 * that is registering the item, and a command line to be used when
207 	 * launching the item.
208 	 *
209 	 * Optionally, a #GtkRecentData-struct might contain a UTF-8 string
210 	 * to be used when viewing the item instead of the last component of
211 	 * the URI; a short description of the item; whether the item should
212 	 * be considered private - that is, should be displayed only by the
213 	 * applications that have registered it.
214 	 *
215 	 * Params:
216 	 *     uri = a valid URI
217 	 *     recentData = metadata of the resource
218 	 *
219 	 * Returns: %TRUE if the new item was successfully added to the
220 	 *     recently used resources list, %FALSE otherwise
221 	 *
222 	 * Since: 2.10
223 	 */
224 	public bool addFull(string uri, GtkRecentData* recentData)
225 	{
226 		return gtk_recent_manager_add_full(gtkRecentManager, Str.toStringz(uri), recentData) != 0;
227 	}
228 
229 	/**
230 	 * Adds a new resource, pointed by @uri, into the recently used
231 	 * resources list.
232 	 *
233 	 * This function automatically retrieves some of the needed
234 	 * metadata and setting other metadata to common default values;
235 	 * it then feeds the data to gtk_recent_manager_add_full().
236 	 *
237 	 * See gtk_recent_manager_add_full() if you want to explicitly
238 	 * define the metadata for the resource pointed by @uri.
239 	 *
240 	 * Params:
241 	 *     uri = a valid URI
242 	 *
243 	 * Returns: %TRUE if the new item was successfully added
244 	 *     to the recently used resources list
245 	 *
246 	 * Since: 2.10
247 	 */
248 	public bool addItem(string uri)
249 	{
250 		return gtk_recent_manager_add_item(gtkRecentManager, Str.toStringz(uri)) != 0;
251 	}
252 
253 	/**
254 	 * Gets the list of recently used resources.
255 	 *
256 	 * Returns: a list of
257 	 *     newly allocated #GtkRecentInfo objects. Use
258 	 *     gtk_recent_info_unref() on each item inside the list, and then
259 	 *     free the list itself using g_list_free().
260 	 *
261 	 * Since: 2.10
262 	 */
263 	public ListG getItems()
264 	{
265 		auto p = gtk_recent_manager_get_items(gtkRecentManager);
266 
267 		if(p is null)
268 		{
269 			return null;
270 		}
271 
272 		return new ListG(cast(GList*) p, true);
273 	}
274 
275 	/**
276 	 * Checks whether there is a recently used resource registered
277 	 * with @uri inside the recent manager.
278 	 *
279 	 * Params:
280 	 *     uri = a URI
281 	 *
282 	 * Returns: %TRUE if the resource was found, %FALSE otherwise
283 	 *
284 	 * Since: 2.10
285 	 */
286 	public bool hasItem(string uri)
287 	{
288 		return gtk_recent_manager_has_item(gtkRecentManager, Str.toStringz(uri)) != 0;
289 	}
290 
291 	/**
292 	 * Searches for a URI inside the recently used resources list, and
293 	 * returns a #GtkRecentInfo-struct containing informations about the resource
294 	 * like its MIME type, or its display name.
295 	 *
296 	 * Params:
297 	 *     uri = a URI
298 	 *
299 	 * Returns: a #GtkRecentInfo-struct containing information
300 	 *     about the resource pointed by @uri, or %NULL if the URI was
301 	 *     not registered in the recently used resources list. Free with
302 	 *     gtk_recent_info_unref().
303 	 *
304 	 * Since: 2.10
305 	 *
306 	 * Throws: GException on failure.
307 	 */
308 	public RecentInfo lookupItem(string uri)
309 	{
310 		GError* err = null;
311 
312 		auto p = gtk_recent_manager_lookup_item(gtkRecentManager, Str.toStringz(uri), &err);
313 
314 		if (err !is null)
315 		{
316 			throw new GException( new ErrorG(err) );
317 		}
318 
319 		if(p is null)
320 		{
321 			return null;
322 		}
323 
324 		return ObjectG.getDObject!(RecentInfo)(cast(GtkRecentInfo*) p, true);
325 	}
326 
327 	/**
328 	 * Changes the location of a recently used resource from @uri to @new_uri.
329 	 *
330 	 * Please note that this function will not affect the resource pointed
331 	 * by the URIs, but only the URI used in the recently used resources list.
332 	 *
333 	 * Params:
334 	 *     uri = the URI of a recently used resource
335 	 *     newUri = the new URI of the recently used resource, or
336 	 *         %NULL to remove the item pointed by @uri in the list
337 	 *
338 	 * Returns: %TRUE on success
339 	 *
340 	 * Since: 2.10
341 	 *
342 	 * Throws: GException on failure.
343 	 */
344 	public bool moveItem(string uri, string newUri)
345 	{
346 		GError* err = null;
347 
348 		auto p = gtk_recent_manager_move_item(gtkRecentManager, Str.toStringz(uri), Str.toStringz(newUri), &err) != 0;
349 
350 		if (err !is null)
351 		{
352 			throw new GException( new ErrorG(err) );
353 		}
354 
355 		return p;
356 	}
357 
358 	/**
359 	 * Purges every item from the recently used resources list.
360 	 *
361 	 * Returns: the number of items that have been removed from the
362 	 *     recently used resources list
363 	 *
364 	 * Since: 2.10
365 	 *
366 	 * Throws: GException on failure.
367 	 */
368 	public int purgeItems()
369 	{
370 		GError* err = null;
371 
372 		auto p = gtk_recent_manager_purge_items(gtkRecentManager, &err);
373 
374 		if (err !is null)
375 		{
376 			throw new GException( new ErrorG(err) );
377 		}
378 
379 		return p;
380 	}
381 
382 	/**
383 	 * Removes a resource pointed by @uri from the recently used resources
384 	 * list handled by a recent manager.
385 	 *
386 	 * Params:
387 	 *     uri = the URI of the item you wish to remove
388 	 *
389 	 * Returns: %TRUE if the item pointed by @uri has been successfully
390 	 *     removed by the recently used resources list, and %FALSE otherwise
391 	 *
392 	 * Since: 2.10
393 	 *
394 	 * Throws: GException on failure.
395 	 */
396 	public bool removeItem(string uri)
397 	{
398 		GError* err = null;
399 
400 		auto p = gtk_recent_manager_remove_item(gtkRecentManager, Str.toStringz(uri), &err) != 0;
401 
402 		if (err !is null)
403 		{
404 			throw new GException( new ErrorG(err) );
405 		}
406 
407 		return p;
408 	}
409 
410 	protected class OnChangedDelegateWrapper
411 	{
412 		void delegate(RecentManager) dlg;
413 		gulong handlerId;
414 
415 		this(void delegate(RecentManager) dlg)
416 		{
417 			this.dlg = dlg;
418 			onChangedListeners ~= this;
419 		}
420 
421 		void remove(OnChangedDelegateWrapper source)
422 		{
423 			foreach(index, wrapper; onChangedListeners)
424 			{
425 				if (wrapper.handlerId == source.handlerId)
426 				{
427 					onChangedListeners[index] = null;
428 					onChangedListeners = std.algorithm.remove(onChangedListeners, index);
429 					break;
430 				}
431 			}
432 		}
433 	}
434 	OnChangedDelegateWrapper[] onChangedListeners;
435 
436 	/**
437 	 * Emitted when the current recently used resources manager changes
438 	 * its contents, either by calling gtk_recent_manager_add_item() or
439 	 * by another application.
440 	 *
441 	 * Since: 2.10
442 	 */
443 	gulong addOnChanged(void delegate(RecentManager) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
444 	{
445 		auto wrapper = new OnChangedDelegateWrapper(dlg);
446 		wrapper.handlerId = Signals.connectData(
447 			this,
448 			"changed",
449 			cast(GCallback)&callBackChanged,
450 			cast(void*)wrapper,
451 			cast(GClosureNotify)&callBackChangedDestroy,
452 			connectFlags);
453 		return wrapper.handlerId;
454 	}
455 
456 	extern(C) static void callBackChanged(GtkRecentManager* recentmanagerStruct, OnChangedDelegateWrapper wrapper)
457 	{
458 		wrapper.dlg(wrapper.outer);
459 	}
460 
461 	extern(C) static void callBackChangedDestroy(OnChangedDelegateWrapper wrapper, GClosure* closure)
462 	{
463 		wrapper.remove(wrapper);
464 	}
465 }