libs/gtkmm2/gtk/gtkmm/recentmanager.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_RECENTMANAGER_H
   4 #define _GTKMM_RECENTMANAGER_H
   5
   6
   7 #include <glibmm.h>
   8
   9 /* Copyright (C) 2006 The gtkmm Development Team
  10  *
  11  * This library is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Library General Public
  13  * License as published by the Free Software Foundation; either
  14  * version 2 of the License, or (at your option) any later version.
  15  *
  16  * This library is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Library General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Library General Public
  22  * License along with this library; if not, write to the Free
  23  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  24  */
  25
  26 #include <gdkmm/screen.h>
  27 #include <gdkmm/pixbuf.h>
  28
  29 #include <gtkmm/recentinfo.h>
  30
  31 #include <glibmm/object.h>
  32 #include <glibmm/containers.h>
  33
  34
  35 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  36 typedef struct _GtkRecentManager GtkRecentManager;
  37 typedef struct _GtkRecentManagerClass GtkRecentManagerClass;
  38 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  39
  40
  41 namespace Gtk
  42 { class RecentManager_Class; } // namespace Gtk
  43 namespace Gtk
  44 {
  45
  46 /** Exception class for Gtk::RecentManager errors.
  47  */
  48 class RecentManagerError : public Glib::Error
  49 {
  50 public:
  51   enum Code
  52   {
  53     NOT_FOUND,
  54     INVALID_URI,
  55     INVALID_ENCODING,
  56     NOT_REGISTERED,
  57     READ,
  58     WRITE,
  59     UNKNOWN
  60   };
  61
  62   RecentManagerError(Code error_code, const Glib::ustring& error_message);
  63   explicit RecentManagerError(GError* gobject);
  64   Code code() const;
  65
  66 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  67 private:
  68
  69 #ifdef GLIBMM_EXCEPTIONS_ENABLED
  70   static void throw_func(GError* gobject);
  71 #else
  72   //When not using exceptions, we just pass the Exception object around without throwing it:
  73   static std::auto_ptr<Glib::Error> throw_func(GError* gobject);
  74 #endif //GLIBMM_EXCEPTIONS_ENABLED
  75
  76   friend void wrap_init(); // uses throw_func()
  77 #endif
  78 };
  79
  80 } // namespace Gtk
  81
  82 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  83 namespace Glib
  84 {
  85
  86 template <>
  87 class Value<Gtk::RecentManagerError::Code> : public Glib::Value_Enum<Gtk::RecentManagerError::Code>
  88 {
  89 public:
  90   static GType value_type() G_GNUC_CONST;
  91 };
  92
  93 } // namespace Glib
  94 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  95
  96
  97 namespace Gtk
  98 {
  99
 100
 101 /** @defgroup RecentFiles RecentFiles
 102  */
 103
 104 /** RecentManager provides a facility for adding, removing and
 105  * looking up recently used files.  Each recently used file is
 106  * identified by its URI, and has meta-data associated to it, like
 107  * the names and command lines of the applications that have
 108  * registered it, the number of time each application has registered
 109  * the same file, the mime type of the file and whether the file
 110  * should be displayed only by the applications that have
 111  * registered it.
 112  *
 113  * The RecentManager acts like a database of all the recently
 114  * used files.  You can create new RecentManager objects, but
 115  * it is more efficient to use the standard recent manager for
 116  * the Gdk::Screen so that informations about the recently used
 117  * files is shared with other people using them. Normally, you
 118  * retrieve the recent manager for a particular screen using
 119  * get_for_screen() and it will contain information about current
 120  * recent manager for that screen.
 121  *
 122  * @newin2p10
 123  *
 124  * @ingroup RecentFiles
 125  */
 126
 127 class RecentManager : public Glib::Object
 128 {
 129
 130 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 131
 132 public:
 133   typedef RecentManager CppObjectType;
 134   typedef RecentManager_Class CppClassType;
 135   typedef GtkRecentManager BaseObjectType;
 136   typedef GtkRecentManagerClass BaseClassType;
 137
 138 private:  friend class RecentManager_Class;
 139   static CppClassType recentmanager_class_;
 140
 141 private:
 142   // noncopyable
 143   RecentManager(const RecentManager&);
 144   RecentManager& operator=(const RecentManager&);
 145
 146 protected:
 147   explicit RecentManager(const Glib::ConstructParams& construct_params);
 148   explicit RecentManager(GtkRecentManager* castitem);
 149
 150 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 151
 152 public:
 153   virtual ~RecentManager();
 154
 155 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 156   static GType get_type()      G_GNUC_CONST;
 157   static GType get_base_type() G_GNUC_CONST;
 158 #endif
 159
 160   ///Provides access to the underlying C GObject.
 161   GtkRecentManager*       gobj()       { return reinterpret_cast<GtkRecentManager*>(gobject_); }
 162
 163   ///Provides access to the underlying C GObject.
 164   const GtkRecentManager* gobj() const { return reinterpret_cast<GtkRecentManager*>(gobject_); }
 165
 166   ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
 167   GtkRecentManager* gobj_copy();
 168
 169 private:
 170
 171
 172 protected:
 173   RecentManager();
 174
 175 public:
 176
 177   static Glib::RefPtr<RecentManager> create();
 178
 179
 180   static Glib::RefPtr<RecentManager> get_default();
 181
 182   static Glib::RefPtr<RecentManager> get_for_screen(const Glib::RefPtr<Gdk::Screen>& screen);
 183
 184   /** Meta-data passed to add_item().  You should
 185    * use RecentManager::Data if you want to control the meta-data associated
 186    * to an entry of the recently used files list when you are adding
 187    * a new file to it.
 188    *
 189    * - display_name: the string to be used when displaying the file inside a RecentChooser
 190    * - description: a user readable description of the file
 191    * - mime_type: the mime type of the file
 192    * - app_name: the name of the application that is registering the file
 193    * - app_exec: the command line that should be used when launching the file
 194    * - groups: the list of group names to which the file belongs to
 195    * - is_private: whether the file should be displayed only by the applications that have registered it
 196   */
 197   class Data
 198   {
 199   public:
 200     Glib::ustring display_name;
 201     Glib::ustring description;
 202
 203     Glib::ustring mime_type;
 204
 205     Glib::ustring app_name;
 206     Glib::ustring app_exec;
 207
 208     Glib::StringArrayHandle groups;
 209
 210     bool is_private;
 211   };
 212
 213
 214   void set_screen(const Glib::RefPtr<Gdk::Screen>& screen);
 215
 216 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 217   bool add_item(const Glib::ustring& uri);
 218 #else
 219   bool add_item(const Glib::ustring& uri, std::auto_ptr<Glib::Error>& error);
 220 #endif //GLIBMM_EXCEPTIONS_ENABLED
 221
 222
 223   bool add_item(const Glib::ustring& uri, const Data& recent_data);
 224
 225 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 226   bool remove_item(const Glib::ustring& uri);
 227 #else
 228   bool remove_item(const Glib::ustring& uri, std::auto_ptr<Glib::Error>& error);
 229 #endif //GLIBMM_EXCEPTIONS_ENABLED
 230
 231
 232 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 233   Glib::RefPtr<RecentInfo> lookup_item(const Glib::ustring& uri);
 234 #else
 235   Glib::RefPtr<RecentInfo> lookup_item(const Glib::ustring& uri, std::auto_ptr<Glib::Error>& error);
 236 #endif //GLIBMM_EXCEPTIONS_ENABLED
 237
 238
 239 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 240   Glib::RefPtr<const RecentInfo> lookup_item(const Glib::ustring& uri) const;
 241 #else
 242   Glib::RefPtr<const RecentInfo> lookup_item(const Glib::ustring& uri, std::auto_ptr<Glib::Error>& error) const;
 243 #endif //GLIBMM_EXCEPTIONS_ENABLED
 244
 245
 246   bool has_item(const Glib::ustring& uri) const;
 247
 248 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 249   bool move_item(const Glib::ustring& uri, const Glib::ustring& new_uri);
 250 #else
 251   bool move_item(const Glib::ustring& uri, const Glib::ustring& new_uri, std::auto_ptr<Glib::Error>& error);
 252 #endif //GLIBMM_EXCEPTIONS_ENABLED
 253
 254
 255   void set_limit(int limit);
 256
 257   int get_limit() const;
 258
 259   typedef Glib::ListHandle<RecentInfo, RecentInfoTraits> ListHandle_RecentInfos;
 260
 261
 262   ListHandle_RecentInfos get_items() const;
 263
 264
 265 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 266   int purge_items();
 267 #else
 268   int purge_items(std::auto_ptr<Glib::Error>& error);
 269 #endif //GLIBMM_EXCEPTIONS_ENABLED
 270
 271
 272   /// For instance, void on_changed();
 273   typedef sigc::slot<void> SlotChanged;
 274
 275   /** The "changed" signal is emitted when an item in the recently used resources list is changed.
 276   */
 277
 278 /**
 279    * @par Prototype:
 280    * <tt>void %changed()</tt>
 281    */
 282
 283   Glib::SignalProxy0< void > signal_changed();
 284
 285
 286   #ifdef GLIBMM_PROPERTIES_ENABLED
 287 /** The full path to the file to be used to store and read the list.
 288    *
 289    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 290    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 291    * the value of the property changes.
 292    */
 293   Glib::PropertyProxy_ReadOnly<Glib::ustring> property_filename() const;
 294 #endif //#GLIBMM_PROPERTIES_ENABLED
 295
 296
 297   #ifdef GLIBMM_PROPERTIES_ENABLED
 298 /** The maximum number of items to be returned by gtk_recent_manager_get_items.
 299    *
 300    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 301    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 302    * the value of the property changes.
 303    */
 304   Glib::PropertyProxy<int> property_limit() ;
 305 #endif //#GLIBMM_PROPERTIES_ENABLED
 306
 307 #ifdef GLIBMM_PROPERTIES_ENABLED
 308 /** The maximum number of items to be returned by gtk_recent_manager_get_items.
 309    *
 310    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 311    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 312    * the value of the property changes.
 313    */
 314   Glib::PropertyProxy_ReadOnly<int> property_limit() const;
 315 #endif //#GLIBMM_PROPERTIES_ENABLED
 316
 317   #ifdef GLIBMM_PROPERTIES_ENABLED
 318 /** The size of the recently used resources list.
 319    *
 320    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 321    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 322    * the value of the property changes.
 323    */
 324   Glib::PropertyProxy_ReadOnly<int> property_size() const;
 325 #endif //#GLIBMM_PROPERTIES_ENABLED
 326
 327
 328 public:
 329
 330 public:
 331   //C++ methods used to invoke GTK+ virtual functions:
 332 #ifdef GLIBMM_VFUNCS_ENABLED
 333 #endif //GLIBMM_VFUNCS_ENABLED
 334
 335 protected:
 336   //GTK+ Virtual Functions (override these to change behaviour):
 337 #ifdef GLIBMM_VFUNCS_ENABLED
 338 #endif //GLIBMM_VFUNCS_ENABLED
 339
 340   //Default Signal Handlers::
 341 #ifdef GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 342   virtual void on_changed();
 343 #endif //GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 344
 345
 346 };
 347
 348 } // namespace Gtk
 349
 350
 351 namespace Glib
 352 {
 353   /** @relates Gtk::RecentManager
 354    * @param object The C instance
 355    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 356    * @result A C++ instance that wraps this C instance.
 357    */
 358   Glib::RefPtr<Gtk::RecentManager> wrap(GtkRecentManager* object, bool take_copy = false);
 359 }
 360
 361
 362 #endif /* _GTKMM_RECENTMANAGER_H */
 363