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