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 char *display_name;
72 char *description;
73
74 char *mime_type;
75
76 char *app_name;
77 char *app_exec;
78
79 char **groups;
80
81 gboolean is_private;
82};
83
84struct _GtkRecentManager
85{
86 /*< private >*/
87 GObject parent_instance;
88
89 GtkRecentManagerPrivate *priv;
90};
91
92/**
93 * GtkRecentManagerClass:
94 *
95 * `GtkRecentManagerClass` contains only private data.
96 */
97struct _GtkRecentManagerClass
98{
99 /*< private >*/
100 GObjectClass parent_class;
101
102 void (*changed) (GtkRecentManager *manager);
103
104 /* padding for future expansion */
105 void (*_gtk_recent1) (void);
106 void (*_gtk_recent2) (void);
107 void (*_gtk_recent3) (void);
108 void (*_gtk_recent4) (void);
109};
110
111/**
112 * GtkRecentManagerError:
113 * @GTK_RECENT_MANAGER_ERROR_NOT_FOUND: the URI specified does not exists in
114 * the recently used resources list.
115 * @GTK_RECENT_MANAGER_ERROR_INVALID_URI: the URI specified is not valid.
116 * @GTK_RECENT_MANAGER_ERROR_INVALID_ENCODING: the supplied string is not
117 * UTF-8 encoded.
118 * @GTK_RECENT_MANAGER_ERROR_NOT_REGISTERED: no application has registered
119 * the specified item.
120 * @GTK_RECENT_MANAGER_ERROR_READ: failure while reading the recently used
121 * resources file.
122 * @GTK_RECENT_MANAGER_ERROR_WRITE: failure while writing the recently used
123 * resources file.
124 * @GTK_RECENT_MANAGER_ERROR_UNKNOWN: unspecified error.
125 *
126 * Error codes for `GtkRecentManager` operations
127 */
128typedef enum
129{
130 GTK_RECENT_MANAGER_ERROR_NOT_FOUND,
131 GTK_RECENT_MANAGER_ERROR_INVALID_URI,
132 GTK_RECENT_MANAGER_ERROR_INVALID_ENCODING,
133 GTK_RECENT_MANAGER_ERROR_NOT_REGISTERED,
134 GTK_RECENT_MANAGER_ERROR_READ,
135 GTK_RECENT_MANAGER_ERROR_WRITE,
136 GTK_RECENT_MANAGER_ERROR_UNKNOWN
137} GtkRecentManagerError;
138
139/**
140 * GTK_RECENT_MANAGER_ERROR:
141 *
142 * The `GError` domain for `GtkRecentManager` errors.
143 */
144#define GTK_RECENT_MANAGER_ERROR (gtk_recent_manager_error_quark ())
145GDK_AVAILABLE_IN_ALL
146GQuark gtk_recent_manager_error_quark (void);
147
148
149GDK_AVAILABLE_IN_ALL
150GType gtk_recent_manager_get_type (void) G_GNUC_CONST;
151
152GDK_AVAILABLE_IN_ALL
153GtkRecentManager *gtk_recent_manager_new (void);
154GDK_AVAILABLE_IN_ALL
155GtkRecentManager *gtk_recent_manager_get_default (void);
156
157GDK_AVAILABLE_IN_ALL
158gboolean gtk_recent_manager_add_item (GtkRecentManager *manager,
159 const char *uri);
160GDK_AVAILABLE_IN_ALL
161gboolean gtk_recent_manager_add_full (GtkRecentManager *manager,
162 const char *uri,
163 const GtkRecentData *recent_data);
164GDK_AVAILABLE_IN_ALL
165gboolean gtk_recent_manager_remove_item (GtkRecentManager *manager,
166 const char *uri,
167 GError **error);
168GDK_AVAILABLE_IN_ALL
169GtkRecentInfo * gtk_recent_manager_lookup_item (GtkRecentManager *manager,
170 const char *uri,
171 GError **error);
172GDK_AVAILABLE_IN_ALL
173gboolean gtk_recent_manager_has_item (GtkRecentManager *manager,
174 const char *uri);
175GDK_AVAILABLE_IN_ALL
176gboolean gtk_recent_manager_move_item (GtkRecentManager *manager,
177 const char *uri,
178 const char *new_uri,
179 GError **error);
180GDK_AVAILABLE_IN_ALL
181GList * gtk_recent_manager_get_items (GtkRecentManager *manager);
182GDK_AVAILABLE_IN_ALL
183int gtk_recent_manager_purge_items (GtkRecentManager *manager,
184 GError **error);
185
186
187GDK_AVAILABLE_IN_ALL
188GType gtk_recent_info_get_type (void) G_GNUC_CONST;
189
190GDK_AVAILABLE_IN_ALL
191GtkRecentInfo * gtk_recent_info_ref (GtkRecentInfo *info);
192GDK_AVAILABLE_IN_ALL
193void gtk_recent_info_unref (GtkRecentInfo *info);
194
195GDK_AVAILABLE_IN_ALL
196const char * gtk_recent_info_get_uri (GtkRecentInfo *info);
197GDK_AVAILABLE_IN_ALL
198const char * gtk_recent_info_get_display_name (GtkRecentInfo *info);
199GDK_AVAILABLE_IN_ALL
200const char * gtk_recent_info_get_description (GtkRecentInfo *info);
201GDK_AVAILABLE_IN_ALL
202const char * gtk_recent_info_get_mime_type (GtkRecentInfo *info);
203GDK_AVAILABLE_IN_ALL
204GDateTime * gtk_recent_info_get_added (GtkRecentInfo *info);
205GDK_AVAILABLE_IN_ALL
206GDateTime * gtk_recent_info_get_modified (GtkRecentInfo *info);
207GDK_AVAILABLE_IN_ALL
208GDateTime * gtk_recent_info_get_visited (GtkRecentInfo *info);
209GDK_AVAILABLE_IN_ALL
210gboolean gtk_recent_info_get_private_hint (GtkRecentInfo *info);
211GDK_AVAILABLE_IN_ALL
212gboolean gtk_recent_info_get_application_info (GtkRecentInfo *info,
213 const char *app_name,
214 const char **app_exec,
215 guint *count,
216 GDateTime **stamp);
217GDK_AVAILABLE_IN_ALL
218GAppInfo * gtk_recent_info_create_app_info (GtkRecentInfo *info,
219 const char *app_name,
220 GError **error);
221GDK_AVAILABLE_IN_ALL
222char ** gtk_recent_info_get_applications (GtkRecentInfo *info,
223 gsize *length) G_GNUC_MALLOC;
224GDK_AVAILABLE_IN_ALL
225char * gtk_recent_info_last_application (GtkRecentInfo *info) G_GNUC_MALLOC;
226GDK_AVAILABLE_IN_ALL
227gboolean gtk_recent_info_has_application (GtkRecentInfo *info,
228 const char *app_name);
229GDK_AVAILABLE_IN_ALL
230char ** gtk_recent_info_get_groups (GtkRecentInfo *info,
231 gsize *length) G_GNUC_MALLOC;
232GDK_AVAILABLE_IN_ALL
233gboolean gtk_recent_info_has_group (GtkRecentInfo *info,
234 const char *group_name);
235GDK_AVAILABLE_IN_ALL
236GIcon * gtk_recent_info_get_gicon (GtkRecentInfo *info);
237GDK_AVAILABLE_IN_ALL
238char * gtk_recent_info_get_short_name (GtkRecentInfo *info) G_GNUC_MALLOC;
239GDK_AVAILABLE_IN_ALL
240char * gtk_recent_info_get_uri_display (GtkRecentInfo *info) G_GNUC_MALLOC;
241GDK_AVAILABLE_IN_ALL
242int gtk_recent_info_get_age (GtkRecentInfo *info);
243GDK_AVAILABLE_IN_ALL
244gboolean gtk_recent_info_is_local (GtkRecentInfo *info);
245GDK_AVAILABLE_IN_ALL
246gboolean gtk_recent_info_exists (GtkRecentInfo *info);
247GDK_AVAILABLE_IN_ALL
248gboolean gtk_recent_info_match (GtkRecentInfo *info_a,
249 GtkRecentInfo *info_b);
250
251/* private */
252void _gtk_recent_manager_sync (void);
253
254G_END_DECLS
255
256#endif /* __GTK_RECENT_MANAGER_H__ */
257

source code of gtk/gtk/gtkrecentmanager.h