1/* GTK - The GIMP Toolkit
2 * gtkrecentchooser.h - Abstract interface for recent file selectors GUIs
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 Lesser 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 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20#ifndef __GTK_RECENT_CHOOSER_H__
21#define __GTK_RECENT_CHOOSER_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 <gtk/gtkwidget.h>
28#include <gtk/gtkrecentmanager.h>
29#include <gtk/gtkrecentfilter.h>
30
31G_BEGIN_DECLS
32
33#define GTK_TYPE_RECENT_CHOOSER (gtk_recent_chooser_get_type ())
34#define GTK_RECENT_CHOOSER(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_RECENT_CHOOSER, GtkRecentChooser))
35#define GTK_IS_RECENT_CHOOSER(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_RECENT_CHOOSER))
36#define GTK_RECENT_CHOOSER_GET_IFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), GTK_TYPE_RECENT_CHOOSER, GtkRecentChooserIface))
37
38/**
39 * GtkRecentSortType:
40 * @GTK_RECENT_SORT_NONE: Do not sort the returned list of recently used
41 * resources.
42 * @GTK_RECENT_SORT_MRU: Sort the returned list with the most recently used
43 * items first.
44 * @GTK_RECENT_SORT_LRU: Sort the returned list with the least recently used
45 * items first.
46 * @GTK_RECENT_SORT_CUSTOM: Sort the returned list using a custom sorting
47 * function passed using gtk_recent_chooser_set_sort_func().
48 *
49 * Used to specify the sorting method to be applyed to the recently
50 * used resource list.
51 *
52 * Since: 2.10
53 */
54typedef enum
55{
56 GTK_RECENT_SORT_NONE = 0,
57 GTK_RECENT_SORT_MRU,
58 GTK_RECENT_SORT_LRU,
59 GTK_RECENT_SORT_CUSTOM
60} GtkRecentSortType;
61
62typedef gint (*GtkRecentSortFunc) (GtkRecentInfo *a,
63 GtkRecentInfo *b,
64 gpointer user_data);
65
66
67typedef struct _GtkRecentChooser GtkRecentChooser; /* dummy */
68typedef struct _GtkRecentChooserIface GtkRecentChooserIface;
69
70/**
71 * GTK_RECENT_CHOOSER_ERROR:
72 *
73 * Used to get the #GError quark for #GtkRecentChooser errors.
74 *
75 * Since: 2.10
76 */
77#define GTK_RECENT_CHOOSER_ERROR (gtk_recent_chooser_error_quark ())
78
79/**
80 * GtkRecentChooserError:
81 * @GTK_RECENT_CHOOSER_ERROR_NOT_FOUND: Indicates that a file does not exist
82 * @GTK_RECENT_CHOOSER_ERROR_INVALID_URI: Indicates a malformed URI
83 *
84 * These identify the various errors that can occur while calling
85 * #GtkRecentChooser functions.
86 *
87 * Since: 2.10
88 */
89typedef enum
90{
91 GTK_RECENT_CHOOSER_ERROR_NOT_FOUND,
92 GTK_RECENT_CHOOSER_ERROR_INVALID_URI
93} GtkRecentChooserError;
94
95GDK_AVAILABLE_IN_ALL
96GQuark gtk_recent_chooser_error_quark (void);
97
98
99/**
100 * GtkRecentChooserIface:
101 * @set_current_uri: Sets uri as the current URI for chooser.
102 * @get_current_uri: Gets the URI currently selected by chooser.
103 * @select_uri: Selects uri inside chooser.
104 * @unselect_uri: Unselects uri inside chooser.
105 * @select_all: Selects all the items inside chooser, if the chooser
106 * supports multiple selection.
107 * @unselect_all: Unselects all the items inside chooser.
108 * @get_items: Gets the list of recently used resources in form of
109 * #GtkRecentInfo objects.
110 * @get_recent_manager: Gets the #GtkRecentManager used by chooser.
111 * @add_filter: Adds filter to the list of #GtkRecentFilter objects
112 * held by chooser.
113 * @remove_filter: Removes filter from the list of #GtkRecentFilter
114 * objects held by chooser.
115 * @list_filters: Gets the #GtkRecentFilter objects held by chooser.
116 * @set_sort_func: Sets the comparison function used when sorting to
117 * be sort_func.
118 * @item_activated: Signal emitted when the user “activates” a recent
119 * item in the recent chooser.
120 * @selection_changed: Signal emitted when there is a change in the
121 * set of selected recently used resources.
122 */
123struct _GtkRecentChooserIface
124{
125 /*< private >*/
126 GTypeInterface base_iface;
127
128 /*< public >*/
129
130 /*
131 * Methods
132 */
133 gboolean (* set_current_uri) (GtkRecentChooser *chooser,
134 const gchar *uri,
135 GError **error);
136 gchar * (* get_current_uri) (GtkRecentChooser *chooser);
137 gboolean (* select_uri) (GtkRecentChooser *chooser,
138 const gchar *uri,
139 GError **error);
140 void (* unselect_uri) (GtkRecentChooser *chooser,
141 const gchar *uri);
142 void (* select_all) (GtkRecentChooser *chooser);
143 void (* unselect_all) (GtkRecentChooser *chooser);
144 GList * (* get_items) (GtkRecentChooser *chooser);
145 GtkRecentManager *(* get_recent_manager) (GtkRecentChooser *chooser);
146 void (* add_filter) (GtkRecentChooser *chooser,
147 GtkRecentFilter *filter);
148 void (* remove_filter) (GtkRecentChooser *chooser,
149 GtkRecentFilter *filter);
150 GSList * (* list_filters) (GtkRecentChooser *chooser);
151 void (* set_sort_func) (GtkRecentChooser *chooser,
152 GtkRecentSortFunc sort_func,
153 gpointer sort_data,
154 GDestroyNotify data_destroy);
155
156 /*
157 * Signals
158 */
159 void (* item_activated) (GtkRecentChooser *chooser);
160 void (* selection_changed) (GtkRecentChooser *chooser);
161};
162
163GDK_AVAILABLE_IN_ALL
164GType gtk_recent_chooser_get_type (void) G_GNUC_CONST;
165
166/*
167 * Configuration
168 */
169GDK_AVAILABLE_IN_ALL
170void gtk_recent_chooser_set_show_private (GtkRecentChooser *chooser,
171 gboolean show_private);
172GDK_AVAILABLE_IN_ALL
173gboolean gtk_recent_chooser_get_show_private (GtkRecentChooser *chooser);
174GDK_AVAILABLE_IN_ALL
175void gtk_recent_chooser_set_show_not_found (GtkRecentChooser *chooser,
176 gboolean show_not_found);
177GDK_AVAILABLE_IN_ALL
178gboolean gtk_recent_chooser_get_show_not_found (GtkRecentChooser *chooser);
179GDK_AVAILABLE_IN_ALL
180void gtk_recent_chooser_set_select_multiple (GtkRecentChooser *chooser,
181 gboolean select_multiple);
182GDK_AVAILABLE_IN_ALL
183gboolean gtk_recent_chooser_get_select_multiple (GtkRecentChooser *chooser);
184GDK_AVAILABLE_IN_ALL
185void gtk_recent_chooser_set_limit (GtkRecentChooser *chooser,
186 gint limit);
187GDK_AVAILABLE_IN_ALL
188gint gtk_recent_chooser_get_limit (GtkRecentChooser *chooser);
189GDK_AVAILABLE_IN_ALL
190void gtk_recent_chooser_set_local_only (GtkRecentChooser *chooser,
191 gboolean local_only);
192GDK_AVAILABLE_IN_ALL
193gboolean gtk_recent_chooser_get_local_only (GtkRecentChooser *chooser);
194GDK_AVAILABLE_IN_ALL
195void gtk_recent_chooser_set_show_tips (GtkRecentChooser *chooser,
196 gboolean show_tips);
197GDK_AVAILABLE_IN_ALL
198gboolean gtk_recent_chooser_get_show_tips (GtkRecentChooser *chooser);
199GDK_AVAILABLE_IN_ALL
200void gtk_recent_chooser_set_show_icons (GtkRecentChooser *chooser,
201 gboolean show_icons);
202GDK_AVAILABLE_IN_ALL
203gboolean gtk_recent_chooser_get_show_icons (GtkRecentChooser *chooser);
204GDK_AVAILABLE_IN_ALL
205void gtk_recent_chooser_set_sort_type (GtkRecentChooser *chooser,
206 GtkRecentSortType sort_type);
207GDK_AVAILABLE_IN_ALL
208GtkRecentSortType gtk_recent_chooser_get_sort_type (GtkRecentChooser *chooser);
209GDK_AVAILABLE_IN_ALL
210void gtk_recent_chooser_set_sort_func (GtkRecentChooser *chooser,
211 GtkRecentSortFunc sort_func,
212 gpointer sort_data,
213 GDestroyNotify data_destroy);
214
215/*
216 * Items handling
217 */
218GDK_AVAILABLE_IN_ALL
219gboolean gtk_recent_chooser_set_current_uri (GtkRecentChooser *chooser,
220 const gchar *uri,
221 GError **error);
222GDK_AVAILABLE_IN_ALL
223gchar * gtk_recent_chooser_get_current_uri (GtkRecentChooser *chooser);
224GDK_AVAILABLE_IN_ALL
225GtkRecentInfo *gtk_recent_chooser_get_current_item (GtkRecentChooser *chooser);
226GDK_AVAILABLE_IN_ALL
227gboolean gtk_recent_chooser_select_uri (GtkRecentChooser *chooser,
228 const gchar *uri,
229 GError **error);
230GDK_AVAILABLE_IN_ALL
231void gtk_recent_chooser_unselect_uri (GtkRecentChooser *chooser,
232 const gchar *uri);
233GDK_AVAILABLE_IN_ALL
234void gtk_recent_chooser_select_all (GtkRecentChooser *chooser);
235GDK_AVAILABLE_IN_ALL
236void gtk_recent_chooser_unselect_all (GtkRecentChooser *chooser);
237GDK_AVAILABLE_IN_ALL
238GList * gtk_recent_chooser_get_items (GtkRecentChooser *chooser);
239GDK_AVAILABLE_IN_ALL
240gchar ** gtk_recent_chooser_get_uris (GtkRecentChooser *chooser,
241 gsize *length);
242
243/*
244 * Filters
245 */
246GDK_AVAILABLE_IN_ALL
247void gtk_recent_chooser_add_filter (GtkRecentChooser *chooser,
248 GtkRecentFilter *filter);
249GDK_AVAILABLE_IN_ALL
250void gtk_recent_chooser_remove_filter (GtkRecentChooser *chooser,
251 GtkRecentFilter *filter);
252GDK_AVAILABLE_IN_ALL
253GSList * gtk_recent_chooser_list_filters (GtkRecentChooser *chooser);
254GDK_AVAILABLE_IN_ALL
255void gtk_recent_chooser_set_filter (GtkRecentChooser *chooser,
256 GtkRecentFilter *filter);
257GDK_AVAILABLE_IN_ALL
258GtkRecentFilter *gtk_recent_chooser_get_filter (GtkRecentChooser *chooser);
259
260
261G_END_DECLS
262
263#endif /* __GTK_RECENT_CHOOSER_H__ */
264