Pileus Git - ~andy/gtk/blob - gtk/gtkrecentmanager.h

   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
  31 G_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
  42 typedef struct _GtkRecentInfo           GtkRecentInfo;
  43 typedef struct _GtkRecentData           GtkRecentData;
  44 typedef struct _GtkRecentManager        GtkRecentManager;
  45 typedef struct _GtkRecentManagerClass   GtkRecentManagerClass;
  46 typedef 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  *   "&percnt;f" and "&percnt;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: a vector of strings containing groups names;
  62  * @is_private: whether this resource should be displayed only by the
  63  *   applications that have registered it or not.
  64  *
  65  * Meta-data to be passed to gtk_recent_manager_add_full() when
  66  * registering a recently used resource.
  67  **/
  68 struct _GtkRecentData
  69 {
  70   gchar *display_name;
  71   gchar *description;
  72
  73   gchar *mime_type;
  74
  75   gchar *app_name;
  76   gchar *app_exec;
  77
  78   gchar **groups;
  79
  80   gboolean is_private;
  81 };
  82
  83 /**
  84  * GtkRecentManager:
  85  *
  86  * #GtkRecentManager contains only private data
  87  * and should be accessed using the provided API.
  88  *
  89  * Since: 2.10
  90  */
  91 struct _GtkRecentManager
  92 {
  93   /*< private >*/
  94   GObject parent_instance;
  95
  96   GtkRecentManagerPrivate *priv;
  97 };
  98
  99 /**
 100  * GtkRecentManagerClass:
 101  *
 102  * #GtkRecentManagerClass contains only private data.
 103  *
 104  * Since: 2.10
 105  */
 106 struct _GtkRecentManagerClass
 107 {
 108   /*< private >*/
 109   GObjectClass parent_class;
 110
 111   void (*changed) (GtkRecentManager *manager);
 112
 113   /* padding for future expansion */
 114   void (*_gtk_recent1) (void);
 115   void (*_gtk_recent2) (void);
 116   void (*_gtk_recent3) (void);
 117   void (*_gtk_recent4) (void);
 118 };
 119
 120 /**
 121  * GtkRecentManagerError:
 122  * @GTK_RECENT_MANAGER_ERROR_NOT_FOUND: the URI specified does not exists in
 123  *   the recently used resources list.
 124  * @GTK_RECENT_MANAGER_ERROR_INVALID_URI: the URI specified is not valid.
 125  * @GTK_RECENT_MANAGER_ERROR_INVALID_ENCODING: the supplied string is not
 126  *   UTF-8 encoded.
 127  * @GTK_RECENT_MANAGER_ERROR_NOT_REGISTERED: no application has registered
 128  *   the specified item.
 129  * @GTK_RECENT_MANAGER_ERROR_READ: failure while reading the recently used
 130  *   resources file.
 131  * @GTK_RECENT_MANAGER_ERROR_WRITE: failure while writing the recently used
 132  *   resources file.
 133  * @GTK_RECENT_MANAGER_ERROR_UNKNOWN: unspecified error.
 134  *
 135  * Error codes for #GtkRecentManager operations
 136  *
 137  * Since: 2.10
 138  */
 139 typedef enum
 140 {
 141   GTK_RECENT_MANAGER_ERROR_NOT_FOUND,
 142   GTK_RECENT_MANAGER_ERROR_INVALID_URI,
 143   GTK_RECENT_MANAGER_ERROR_INVALID_ENCODING,
 144   GTK_RECENT_MANAGER_ERROR_NOT_REGISTERED,
 145   GTK_RECENT_MANAGER_ERROR_READ,
 146   GTK_RECENT_MANAGER_ERROR_WRITE,
 147   GTK_RECENT_MANAGER_ERROR_UNKNOWN
 148 } GtkRecentManagerError;
 149
 150 /**
 151  * GTK_RECENT_MANAGER_ERROR:
 152  *
 153  * The #GError domain for #GtkRecentManager errors.
 154  *
 155  * Since: 2.10
 156  */
 157 #define GTK_RECENT_MANAGER_ERROR        (gtk_recent_manager_error_quark ())
 158 GQuark  gtk_recent_manager_error_quark (void);
 159
 160
 161 GType             gtk_recent_manager_get_type       (void) G_GNUC_CONST;
 162
 163 GtkRecentManager *gtk_recent_manager_new            (void);
 164 GtkRecentManager *gtk_recent_manager_get_default    (void);
 165
 166 gboolean          gtk_recent_manager_add_item       (GtkRecentManager     *manager,
 167                                                      const gchar          *uri);
 168 gboolean          gtk_recent_manager_add_full       (GtkRecentManager     *manager,
 169                                                      const gchar          *uri,
 170                                                      const GtkRecentData  *recent_data);
 171 gboolean          gtk_recent_manager_remove_item    (GtkRecentManager     *manager,
 172                                                      const gchar          *uri,
 173                                                      GError              **error);
 174 GtkRecentInfo *   gtk_recent_manager_lookup_item    (GtkRecentManager     *manager,
 175                                                      const gchar          *uri,
 176                                                      GError              **error);
 177 gboolean          gtk_recent_manager_has_item       (GtkRecentManager     *manager,
 178                                                      const gchar          *uri);
 179 gboolean          gtk_recent_manager_move_item      (GtkRecentManager     *manager,
 180                                                      const gchar          *uri,
 181                                                      const gchar          *new_uri,
 182                                                      GError              **error);
 183 GList *           gtk_recent_manager_get_items      (GtkRecentManager     *manager);
 184 gint              gtk_recent_manager_purge_items    (GtkRecentManager     *manager,
 185                                                      GError              **error);
 186
 187
 188 GType                 gtk_recent_info_get_type             (void) G_GNUC_CONST;
 189
 190 GtkRecentInfo *       gtk_recent_info_ref                  (GtkRecentInfo  *info);
 191 void                  gtk_recent_info_unref                (GtkRecentInfo  *info);
 192
 193 const gchar *         gtk_recent_info_get_uri              (GtkRecentInfo  *info);
 194 const gchar *         gtk_recent_info_get_display_name     (GtkRecentInfo  *info);
 195 const gchar *         gtk_recent_info_get_description      (GtkRecentInfo  *info);
 196 const gchar *         gtk_recent_info_get_mime_type        (GtkRecentInfo  *info);
 197 time_t                gtk_recent_info_get_added            (GtkRecentInfo  *info);
 198 time_t                gtk_recent_info_get_modified         (GtkRecentInfo  *info);
 199 time_t                gtk_recent_info_get_visited          (GtkRecentInfo  *info);
 200 gboolean              gtk_recent_info_get_private_hint     (GtkRecentInfo  *info);
 201 gboolean              gtk_recent_info_get_application_info (GtkRecentInfo  *info,
 202                                                             const gchar    *app_name,
 203                                                             const gchar   **app_exec,
 204                                                             guint          *count,
 205                                                             time_t         *time_);
 206 GAppInfo *            gtk_recent_info_create_app_info      (GtkRecentInfo  *info,
 207                                                             const gchar    *app_name,
 208                                                             GError        **error);
 209 gchar **              gtk_recent_info_get_applications     (GtkRecentInfo  *info,
 210                                                             gsize          *length) G_GNUC_MALLOC;
 211 gchar *               gtk_recent_info_last_application     (GtkRecentInfo  *info) G_GNUC_MALLOC;
 212 gboolean              gtk_recent_info_has_application      (GtkRecentInfo  *info,
 213                                                             const gchar    *app_name);
 214 gchar **              gtk_recent_info_get_groups           (GtkRecentInfo  *info,
 215                                                             gsize          *length) G_GNUC_MALLOC;
 216 gboolean              gtk_recent_info_has_group            (GtkRecentInfo  *info,
 217                                                             const gchar    *group_name);
 218 GdkPixbuf *           gtk_recent_info_get_icon             (GtkRecentInfo  *info,
 219                                                             gint            size);
 220 GIcon *               gtk_recent_info_get_gicon            (GtkRecentInfo  *info);
 221 gchar *               gtk_recent_info_get_short_name       (GtkRecentInfo  *info) G_GNUC_MALLOC;
 222 gchar *               gtk_recent_info_get_uri_display      (GtkRecentInfo  *info) G_GNUC_MALLOC;
 223 gint                  gtk_recent_info_get_age              (GtkRecentInfo  *info);
 224 gboolean              gtk_recent_info_is_local             (GtkRecentInfo  *info);
 225 gboolean              gtk_recent_info_exists               (GtkRecentInfo  *info);
 226 gboolean              gtk_recent_info_match                (GtkRecentInfo  *info_a,
 227                                                             GtkRecentInfo  *info_b);
 228
 229 /* private */
 230 void _gtk_recent_manager_sync (void);
 231
 232 G_END_DECLS
 233
 234 #endif /* __GTK_RECENT_MANAGER_H__ */