gtkrecentchooser.h 9.82 KB
Newer Older
Cody Russell's avatar
Cody Russell committed
1
/* GTK - The GIMP Toolkit
2 3 4
 * gtkrecentchooser.h - Abstract interface for recent file selectors GUIs
 *
 * Copyright (C) 2006, Emmanuele Bassi
5
 *
6 7 8 9 10 11 12 13 14 15 16
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
Javier Jardón's avatar
Javier Jardón committed
17
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
18 19
 */

20 21 22
#ifndef __GTK_RECENT_CHOOSER_H__
#define __GTK_RECENT_CHOOSER_H__

23
#if !defined (__GTK_H_INSIDE__) && !defined (GTK_COMPILATION)
24 25 26
#error "Only <gtk/gtk.h> can be included directly."
#endif

27
#include <gtk/gtkwidget.h>
28 29
#include <gtk/gtkrecentmanager.h>
#include <gtk/gtkrecentfilter.h>
30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46

G_BEGIN_DECLS

#define GTK_TYPE_RECENT_CHOOSER			(gtk_recent_chooser_get_type ())
#define GTK_RECENT_CHOOSER(obj)			(G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_RECENT_CHOOSER, GtkRecentChooser))
#define GTK_IS_RECENT_CHOOSER(obj)		(G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_RECENT_CHOOSER))
#define GTK_RECENT_CHOOSER_GET_IFACE(inst)	(G_TYPE_INSTANCE_GET_INTERFACE ((inst), GTK_TYPE_RECENT_CHOOSER, GtkRecentChooserIface))

/**
 * GtkRecentSortType:
 * @GTK_RECENT_SORT_NONE: Do not sort the returned list of recently used
 *   resources.
 * @GTK_RECENT_SORT_MRU: Sort the returned list with the most recently used
 *   items first.
 * @GTK_RECENT_SORT_LRU: Sort the returned list with the least recently used
 *   items first.
 * @GTK_RECENT_SORT_CUSTOM: Sort the returned list using a custom sorting
47
 *   function passed using gtk_recent_chooser_set_sort_func().
48 49 50
 *
 * Used to specify the sorting method to be applyed to the recently
 * used resource list.
51 52 53
 *
 * Since: 2.10
 */
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69
typedef enum
{
  GTK_RECENT_SORT_NONE = 0,
  GTK_RECENT_SORT_MRU,
  GTK_RECENT_SORT_LRU,
  GTK_RECENT_SORT_CUSTOM
} GtkRecentSortType;

typedef gint (*GtkRecentSortFunc) (GtkRecentInfo *a,
				   GtkRecentInfo *b,
				   gpointer       user_data);


typedef struct _GtkRecentChooser      GtkRecentChooser; /* dummy */
typedef struct _GtkRecentChooserIface GtkRecentChooserIface;

70 71 72 73 74 75 76
/**
 * GTK_RECENT_CHOOSER_ERROR:
 *
 * Used to get the #GError quark for #GtkRecentChooser errors.
 *
 * Since: 2.10
 */
77 78
#define GTK_RECENT_CHOOSER_ERROR	(gtk_recent_chooser_error_quark ())

79 80 81 82 83 84 85 86 87 88
/**
 * GtkRecentChooserError:
 * @GTK_RECENT_CHOOSER_ERROR_NOT_FOUND: Indicates that a file does not exist
 * @GTK_RECENT_CHOOSER_ERROR_INVALID_URI: Indicates a malformed URI
 *
 * These identify the various errors that can occur while calling
 * #GtkRecentChooser functions.
 *
 * Since: 2.10
 */
89 90 91 92 93 94
typedef enum
{
  GTK_RECENT_CHOOSER_ERROR_NOT_FOUND,
  GTK_RECENT_CHOOSER_ERROR_INVALID_URI
} GtkRecentChooserError;

95
GDK_AVAILABLE_IN_ALL
96 97 98
GQuark  gtk_recent_chooser_error_quark (void);


99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
/**
 * GtkRecentChooserIface:
 * @set_current_uri: Sets uri as the current URI for chooser.
 * @get_current_uri: Gets the URI currently selected by chooser.
 * @select_uri: Selects uri inside chooser.
 * @unselect_uri: Unselects uri inside chooser.
 * @select_all: Selects all the items inside chooser, if the chooser
 *    supports multiple selection.
 * @unselect_all: Unselects all the items inside chooser.
 * @get_items: Gets the list of recently used resources in form of
 *    #GtkRecentInfo objects.
 * @get_recent_manager: Gets the #GtkRecentManager used by chooser.
 * @add_filter: Adds filter to the list of #GtkRecentFilter objects
 *    held by chooser.
 * @remove_filter: Removes filter from the list of #GtkRecentFilter
 *    objects held by chooser.
 * @list_filters: Gets the #GtkRecentFilter objects held by chooser.
 * @set_sort_func: Sets the comparison function used when sorting to
 *    be sort_func.
118
 * @item_activated: Signal emitted when the user “activates” a recent
119 120 121 122
 *    item in the recent chooser.
 * @selection_changed: Signal emitted when there is a change in the
 *    set of selected recently used resources.
 */
123 124
struct _GtkRecentChooserIface
{
125
  /*< private >*/
126
  GTypeInterface base_iface;
127

128 129
  /*< public >*/

130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152
  /*
   * Methods
   */
  gboolean          (* set_current_uri)    (GtkRecentChooser  *chooser,
  					    const gchar       *uri,
  					    GError           **error);
  gchar *           (* get_current_uri)    (GtkRecentChooser  *chooser);
  gboolean          (* select_uri)         (GtkRecentChooser  *chooser,
  					    const gchar       *uri,
  					    GError           **error);
  void              (* unselect_uri)       (GtkRecentChooser  *chooser,
                                            const gchar       *uri);
  void              (* select_all)         (GtkRecentChooser  *chooser);
  void              (* unselect_all)       (GtkRecentChooser  *chooser);
  GList *           (* get_items)          (GtkRecentChooser  *chooser);
  GtkRecentManager *(* get_recent_manager) (GtkRecentChooser  *chooser);
  void              (* add_filter)         (GtkRecentChooser  *chooser,
  					    GtkRecentFilter   *filter);
  void              (* remove_filter)      (GtkRecentChooser  *chooser,
  					    GtkRecentFilter   *filter);
  GSList *          (* list_filters)       (GtkRecentChooser  *chooser);
  void              (* set_sort_func)      (GtkRecentChooser  *chooser,
  					    GtkRecentSortFunc  sort_func,
153 154
  					    gpointer           sort_data,
  					    GDestroyNotify     data_destroy);
155

156 157 158 159 160 161 162
  /*
   * Signals
   */
  void		    (* item_activated)     (GtkRecentChooser  *chooser);
  void		    (* selection_changed)  (GtkRecentChooser  *chooser);
};

163
GDK_AVAILABLE_IN_ALL
164 165 166 167 168
GType   gtk_recent_chooser_get_type    (void) G_GNUC_CONST;

/*
 * Configuration
 */
169
GDK_AVAILABLE_IN_ALL
170 171
void              gtk_recent_chooser_set_show_private    (GtkRecentChooser  *chooser,
							  gboolean           show_private);
172
GDK_AVAILABLE_IN_ALL
173
gboolean          gtk_recent_chooser_get_show_private    (GtkRecentChooser  *chooser);
174
GDK_AVAILABLE_IN_ALL
175 176
void              gtk_recent_chooser_set_show_not_found  (GtkRecentChooser  *chooser,
							  gboolean           show_not_found);
177
GDK_AVAILABLE_IN_ALL
178
gboolean          gtk_recent_chooser_get_show_not_found  (GtkRecentChooser  *chooser);
179
GDK_AVAILABLE_IN_ALL
180 181
void              gtk_recent_chooser_set_select_multiple (GtkRecentChooser  *chooser,
							  gboolean           select_multiple);
182
GDK_AVAILABLE_IN_ALL
183
gboolean          gtk_recent_chooser_get_select_multiple (GtkRecentChooser  *chooser);
184
GDK_AVAILABLE_IN_ALL
185 186
void              gtk_recent_chooser_set_limit           (GtkRecentChooser  *chooser,
							  gint               limit);
187
GDK_AVAILABLE_IN_ALL
188
gint              gtk_recent_chooser_get_limit           (GtkRecentChooser  *chooser);
189
GDK_AVAILABLE_IN_ALL
190 191
void              gtk_recent_chooser_set_local_only      (GtkRecentChooser  *chooser,
							  gboolean           local_only);
192
GDK_AVAILABLE_IN_ALL
193
gboolean          gtk_recent_chooser_get_local_only      (GtkRecentChooser  *chooser);
194
GDK_AVAILABLE_IN_ALL
195 196
void              gtk_recent_chooser_set_show_tips       (GtkRecentChooser  *chooser,
							  gboolean           show_tips);
197
GDK_AVAILABLE_IN_ALL
198
gboolean          gtk_recent_chooser_get_show_tips       (GtkRecentChooser  *chooser);
199
GDK_AVAILABLE_IN_ALL
200 201
void              gtk_recent_chooser_set_show_icons      (GtkRecentChooser  *chooser,
							  gboolean           show_icons);
202
GDK_AVAILABLE_IN_ALL
203
gboolean          gtk_recent_chooser_get_show_icons      (GtkRecentChooser  *chooser);
204
GDK_AVAILABLE_IN_ALL
205 206
void              gtk_recent_chooser_set_sort_type       (GtkRecentChooser  *chooser,
							  GtkRecentSortType  sort_type);
207
GDK_AVAILABLE_IN_ALL
208
GtkRecentSortType gtk_recent_chooser_get_sort_type       (GtkRecentChooser  *chooser);
209
GDK_AVAILABLE_IN_ALL
210 211 212 213 214 215 216 217
void              gtk_recent_chooser_set_sort_func       (GtkRecentChooser  *chooser,
							  GtkRecentSortFunc  sort_func,
							  gpointer           sort_data,
							  GDestroyNotify     data_destroy);

/*
 * Items handling
 */
218
GDK_AVAILABLE_IN_ALL
219 220 221
gboolean       gtk_recent_chooser_set_current_uri  (GtkRecentChooser  *chooser,
						    const gchar       *uri,
						    GError           **error);
222
GDK_AVAILABLE_IN_ALL
223
gchar *        gtk_recent_chooser_get_current_uri  (GtkRecentChooser  *chooser);
224
GDK_AVAILABLE_IN_ALL
225
GtkRecentInfo *gtk_recent_chooser_get_current_item (GtkRecentChooser  *chooser);
226
GDK_AVAILABLE_IN_ALL
227 228 229
gboolean       gtk_recent_chooser_select_uri       (GtkRecentChooser  *chooser,
						    const gchar       *uri,
						    GError           **error);
230
GDK_AVAILABLE_IN_ALL
231 232
void           gtk_recent_chooser_unselect_uri     (GtkRecentChooser  *chooser,
					            const gchar       *uri);
233
GDK_AVAILABLE_IN_ALL
234
void           gtk_recent_chooser_select_all       (GtkRecentChooser  *chooser);
235
GDK_AVAILABLE_IN_ALL
236
void           gtk_recent_chooser_unselect_all     (GtkRecentChooser  *chooser);
237
GDK_AVAILABLE_IN_ALL
238
GList *        gtk_recent_chooser_get_items        (GtkRecentChooser  *chooser);
239
GDK_AVAILABLE_IN_ALL
240 241 242 243 244 245
gchar **       gtk_recent_chooser_get_uris         (GtkRecentChooser  *chooser,
						    gsize             *length);

/*
 * Filters
 */
246
GDK_AVAILABLE_IN_ALL
247 248
void 		 gtk_recent_chooser_add_filter    (GtkRecentChooser *chooser,
			 			   GtkRecentFilter  *filter);
249
GDK_AVAILABLE_IN_ALL
250 251
void 		 gtk_recent_chooser_remove_filter (GtkRecentChooser *chooser,
						   GtkRecentFilter  *filter);
252
GDK_AVAILABLE_IN_ALL
253
GSList * 	 gtk_recent_chooser_list_filters  (GtkRecentChooser *chooser);
254
GDK_AVAILABLE_IN_ALL
255 256
void 		 gtk_recent_chooser_set_filter    (GtkRecentChooser *chooser,
						   GtkRecentFilter  *filter);
257
GDK_AVAILABLE_IN_ALL
258 259 260 261 262 263
GtkRecentFilter *gtk_recent_chooser_get_filter    (GtkRecentChooser *chooser);


G_END_DECLS

#endif /* __GTK_RECENT_CHOOSER_H__ */