1/* GTK - The GIMP Toolkit
2 * gtkrecentmanager.h: a manager for the recently used resources
3 *
4 * Copyright (C) 2006 Emmanuele Bassi
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20#ifndef __GTK_RECENT_MANAGER_H__
21#define __GTK_RECENT_MANAGER_H__
22
23#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
24#error "Only <gtk/gtk.h> can be included directly."
25#endif
26
27#include <gdk-pixbuf/gdk-pixbuf.h>
28#include <gdk/gdk.h>
29#include <time.h>
30
31G_BEGIN_DECLS
32
33#define GTK_TYPE_RECENT_INFO (gtk_recent_info_get_type ())
34
35#define GTK_TYPE_RECENT_MANAGER (gtk_recent_manager_get_type ())
36#define GTK_RECENT_MANAGER(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_RECENT_MANAGER, GtkRecentManager))
37#define GTK_IS_RECENT_MANAGER(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_RECENT_MANAGER))
38#define GTK_RECENT_MANAGER_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GTK_TYPE_RECENT_MANAGER, GtkRecentManagerClass))
39#define GTK_IS_RECENT_MANAGER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_RECENT_MANAGER))
40#define GTK_RECENT_MANAGER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_RECENT_MANAGER, GtkRecentManagerClass))
41
42typedef struct _GtkRecentInfo GtkRecentInfo;
43typedef struct _GtkRecentData GtkRecentData;
44typedef struct _GtkRecentManager GtkRecentManager;
45typedef struct _GtkRecentManagerClass GtkRecentManagerClass;
46typedef struct _GtkRecentManagerPrivate GtkRecentManagerPrivate;
47
48/**
49 * GtkRecentData:
50 * @display_name: a UTF-8 encoded string, containing the name of the recently
51 * used resource to be displayed, or %NULL;
52 * @description: a UTF-8 encoded string, containing a short description of
53 * the resource, or %NULL;
54 * @mime_type: the MIME type of the resource;
55 * @app_name: the name of the application that is registering this recently
56 * used resource;
57 * @app_exec: command line used to launch this resource; may contain the
58 * “\%f” and “\%u” escape characters which will be expanded
59 * to the resource file path and URI respectively when the command line
60 * is retrieved;
61 * @groups: (array zero-terminated=1): a vector of strings containing
62 * groups names;
63 * @is_private: whether this resource should be displayed only by the
64 * applications that have registered it or not.
65 *
66 * Meta-data to be passed to gtk_recent_manager_add_full() when
67 * registering a recently used resource.
68 **/
69struct _GtkRecentData
70{
71 gchar *display_name;
72 gchar *description;
73
74 gchar *mime_type;
75
76 gchar *app_name;
77 gchar *app_exec;
78
79 gchar **groups;
80
81 gboolean is_private;
82};
83
84/**
85 * GtkRecentManager:
86 *
87 * #GtkRecentManager-struct contains only private data
88 * and should be accessed using the provided API.
89 *
90 * Since: 2.10
91 */
92struct _GtkRecentManager
93{
94 /*< private >*/
95 GObject parent_instance;
96
97 GtkRecentManagerPrivate *priv;
98};
99
100/**
101 * GtkRecentManagerClass:
102 *
103 * #GtkRecentManagerClass contains only private data.
104 *
105 * Since: 2.10
106 */
107struct _GtkRecentManagerClass
108{
109 /*< private >*/
110 GObjectClass parent_class;
111
112 void (*changed) (GtkRecentManager *manager);
113
114 /* padding for future expansion */
115 void (*_gtk_recent1) (void);
116 void (*_gtk_recent2) (void);
117 void (*_gtk_recent3) (void);
118 void (*_gtk_recent4) (void);
119};
120
121/**
122 * GtkRecentManagerError:
123 * @GTK_RECENT_MANAGER_ERROR_NOT_FOUND: the URI specified does not exists in
124 * the recently used resources list.
125 * @GTK_RECENT_MANAGER_ERROR_INVALID_URI: the URI specified is not valid.
126 * @GTK_RECENT_MANAGER_ERROR_INVALID_ENCODING: the supplied string is not
127 * UTF-8 encoded.
128 * @GTK_RECENT_MANAGER_ERROR_NOT_REGISTERED: no application has registered
129 * the specified item.
130 * @GTK_RECENT_MANAGER_ERROR_READ: failure while reading the recently used
131 * resources file.
132 * @GTK_RECENT_MANAGER_ERROR_WRITE: failure while writing the recently used
133 * resources file.
134 * @GTK_RECENT_MANAGER_ERROR_UNKNOWN: unspecified error.
135 *
136 * Error codes for #GtkRecentManager operations
137 *
138 * Since: 2.10
139 */
140typedef enum
141{
142 GTK_RECENT_MANAGER_ERROR_NOT_FOUND,
143 GTK_RECENT_MANAGER_ERROR_INVALID_URI,
144 GTK_RECENT_MANAGER_ERROR_INVALID_ENCODING,
145 GTK_RECENT_MANAGER_ERROR_NOT_REGISTERED,
146 GTK_RECENT_MANAGER_ERROR_READ,
147 GTK_RECENT_MANAGER_ERROR_WRITE,
148 GTK_RECENT_MANAGER_ERROR_UNKNOWN
149} GtkRecentManagerError;
150
151/**
152 * GTK_RECENT_MANAGER_ERROR:
153 *
154 * The #GError domain for #GtkRecentManager errors.
155 *
156 * Since: 2.10
157 */
158#define GTK_RECENT_MANAGER_ERROR (gtk_recent_manager_error_quark ())
159GDK_AVAILABLE_IN_ALL
160GQuark gtk_recent_manager_error_quark (void);
161
162
163GDK_AVAILABLE_IN_ALL
164GType gtk_recent_manager_get_type (void) G_GNUC_CONST;
165
166GDK_AVAILABLE_IN_ALL
167GtkRecentManager *gtk_recent_manager_new (void);
168GDK_AVAILABLE_IN_ALL
169GtkRecentManager *gtk_recent_manager_get_default (void);
170
171GDK_AVAILABLE_IN_ALL
172gboolean gtk_recent_manager_add_item (GtkRecentManager *manager,
173 const gchar *uri);
174GDK_AVAILABLE_IN_ALL
175gboolean gtk_recent_manager_add_full (GtkRecentManager *manager,
176 const gchar *uri,
177 const GtkRecentData *recent_data);
178GDK_AVAILABLE_IN_ALL
179gboolean gtk_recent_manager_remove_item (GtkRecentManager *manager,
180 const gchar *uri,
181 GError **error);
182GDK_AVAILABLE_IN_ALL
183GtkRecentInfo * gtk_recent_manager_lookup_item (GtkRecentManager *manager,
184 const gchar *uri,
185 GError **error);
186GDK_AVAILABLE_IN_ALL
187gboolean gtk_recent_manager_has_item (GtkRecentManager *manager,
188 const gchar *uri);
189GDK_AVAILABLE_IN_ALL
190gboolean gtk_recent_manager_move_item (GtkRecentManager *manager,
191 const gchar *uri,
192 const gchar *new_uri,
193 GError **error);
194GDK_AVAILABLE_IN_ALL
195GList * gtk_recent_manager_get_items (GtkRecentManager *manager);
196GDK_AVAILABLE_IN_ALL
197gint gtk_recent_manager_purge_items (GtkRecentManager *manager,
198 GError **error);
199
200
201GDK_AVAILABLE_IN_ALL
202GType gtk_recent_info_get_type (void) G_GNUC_CONST;
203
204GDK_AVAILABLE_IN_ALL
205GtkRecentInfo * gtk_recent_info_ref (GtkRecentInfo *info);
206GDK_AVAILABLE_IN_ALL
207void gtk_recent_info_unref (GtkRecentInfo *info);
208
209GDK_AVAILABLE_IN_ALL
210const gchar * gtk_recent_info_get_uri (GtkRecentInfo *info);
211GDK_AVAILABLE_IN_ALL
212const gchar * gtk_recent_info_get_display_name (GtkRecentInfo *info);
213GDK_AVAILABLE_IN_ALL
214const gchar * gtk_recent_info_get_description (GtkRecentInfo *info);
215GDK_AVAILABLE_IN_ALL
216const gchar * gtk_recent_info_get_mime_type (GtkRecentInfo *info);
217GDK_AVAILABLE_IN_ALL
218time_t gtk_recent_info_get_added (GtkRecentInfo *info);
219GDK_AVAILABLE_IN_ALL
220time_t gtk_recent_info_get_modified (GtkRecentInfo *info);
221GDK_AVAILABLE_IN_ALL
222time_t gtk_recent_info_get_visited (GtkRecentInfo *info);
223GDK_AVAILABLE_IN_ALL
224gboolean gtk_recent_info_get_private_hint (GtkRecentInfo *info);
225GDK_AVAILABLE_IN_ALL
226gboolean gtk_recent_info_get_application_info (GtkRecentInfo *info,
227 const gchar *app_name,
228 const gchar **app_exec,
229 guint *count,
230 time_t *time_);
231GDK_AVAILABLE_IN_ALL
232GAppInfo * gtk_recent_info_create_app_info (GtkRecentInfo *info,
233 const gchar *app_name,
234 GError **error);
235GDK_AVAILABLE_IN_ALL
236gchar ** gtk_recent_info_get_applications (GtkRecentInfo *info,
237 gsize *length) G_GNUC_MALLOC;
238GDK_AVAILABLE_IN_ALL
239gchar * gtk_recent_info_last_application (GtkRecentInfo *info) G_GNUC_MALLOC;
240GDK_AVAILABLE_IN_ALL
241gboolean gtk_recent_info_has_application (GtkRecentInfo *info,
242 const gchar *app_name);
243GDK_AVAILABLE_IN_ALL
244gchar ** gtk_recent_info_get_groups (GtkRecentInfo *info,
245 gsize *length) G_GNUC_MALLOC;
246GDK_AVAILABLE_IN_ALL
247gboolean gtk_recent_info_has_group (GtkRecentInfo *info,
248 const gchar *group_name);
249GDK_AVAILABLE_IN_ALL
250GdkPixbuf * gtk_recent_info_get_icon (GtkRecentInfo *info,
251 gint size);
252GDK_AVAILABLE_IN_ALL
253GIcon * gtk_recent_info_get_gicon (GtkRecentInfo *info);
254GDK_AVAILABLE_IN_ALL
255gchar * gtk_recent_info_get_short_name (GtkRecentInfo *info) G_GNUC_MALLOC;
256GDK_AVAILABLE_IN_ALL
257gchar * gtk_recent_info_get_uri_display (GtkRecentInfo *info) G_GNUC_MALLOC;
258GDK_AVAILABLE_IN_ALL
259gint gtk_recent_info_get_age (GtkRecentInfo *info);
260GDK_AVAILABLE_IN_ALL
261gboolean gtk_recent_info_is_local (GtkRecentInfo *info);
262GDK_AVAILABLE_IN_ALL
263gboolean gtk_recent_info_exists (GtkRecentInfo *info);
264GDK_AVAILABLE_IN_ALL
265gboolean gtk_recent_info_match (GtkRecentInfo *info_a,
266 GtkRecentInfo *info_b);
267
268/* private */
269void _gtk_recent_manager_sync (void);
270
271G_END_DECLS
272
273#endif /* __GTK_RECENT_MANAGER_H__ */
274