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   /** Gets a unique instance of Gtk::RecentManager, that you can share
 181    * in your application without caring about memory management. The
 182    * returned instance will be freed when you application terminates.
 183    * @return A unique Gtk::RecentManager. Do not ref or unref it.
 184    *
 185    * @newin2p10.
 186    */
 187   static Glib::RefPtr<RecentManager> get_default();
 188
 189   /** Gets the recent manager object associated with @a screen ; if this
 190    * function has not previously been called for the given screen,
 191    * a new recent manager object will be created and associated with
 192    * the screen. Recent manager objects are fairly expensive to create,
 193    * so using this function is usually a better choice than calling
 194    * new() and setting the screen yourself; by using
 195    * this function a single recent manager object will be shared between
 196    * users.
 197    * @param screen A Gdk::Screen.
 198    * @return A unique Gtk::RecentManager associated with the given
 199    * screen. This recent manager is associated to the with the screen
 200    * and can be used as long as the screen is open. Do not ref or
 201    * unref it.
 202    *
 203    * Deprecated: 2.12: This function has been deprecated and should
 204    * not be used in newly written code. Calling this function is
 205    * equivalent to calling get_default().
 206    *
 207    * @newin2p10.
 208    */
 209   static Glib::RefPtr<RecentManager> get_for_screen(const Glib::RefPtr<Gdk::Screen>& screen);
 210
 211   /** Meta-data passed to add_item().  You should
 212    * use RecentManager::Data if you want to control the meta-data associated
 213    * to an entry of the recently used files list when you are adding
 214    * a new file to it.
 215    *
 216    * - display_name: the string to be used when displaying the file inside a RecentChooser
 217    * - description: a user readable description of the file
 218    * - mime_type: the mime type of the file
 219    * - app_name: the name of the application that is registering the file
 220    * - app_exec: the command line that should be used when launching the file
 221    * - groups: the list of group names to which the file belongs to
 222    * - is_private: whether the file should be displayed only by the applications that have registered it
 223   */
 224   class Data
 225   {
 226   public:
 227     Glib::ustring display_name;
 228     Glib::ustring description;
 229
 230     Glib::ustring mime_type;
 231
 232     Glib::ustring app_name;
 233     Glib::ustring app_exec;
 234
 235     std::vector<Glib::ustring> groups;
 236
 237     bool is_private;
 238   };
 239
 240
 241   /** Sets the screen for a recent manager; the screen is used to
 242    * track the user's currently configured recently used documents
 243    * storage.
 244    *
 245    * @newin2p10
 246    *
 247    * Deprecated: 2.12: This function has been deprecated and should
 248    * not be used in newly written code. Calling this function has
 249    * no effect.
 250    * @param screen A Gdk::Screen.
 251    */
 252   void set_screen(const Glib::RefPtr<Gdk::Screen>& screen);
 253
 254   /** Adds a new resource into the recently used resources list. This function
 255    * will try and guess some of the meta-data associated to a URI. If you
 256    * know some of meta-data about the document yourself, set the desired
 257    * fields of a RecentManager::Data structure and pass it to add_item().
 258    */
 259
 260   /** Adds a new resource, pointed by @a uri , into the recently used
 261    * resources list.
 262    *
 263    * This function automatically retrieving some of the needed
 264    * metadata and setting other metadata to common default values; it
 265    * then feeds the data to add_full().
 266    *
 267    * See add_full() if you want to explicitely
 268    * define the metadata for the resource pointed by @a uri .
 269    * @param uri A valid URI.
 270    * @return <tt>true</tt> if the new item was successfully added
 271    * to the recently used resources list
 272    *
 273    * @newin2p10.
 274    */
 275 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 276   bool add_item(const Glib::ustring& uri);
 277 #else
 278   bool add_item(const Glib::ustring& uri, std::auto_ptr<Glib::Error>& error);
 279 #endif //GLIBMM_EXCEPTIONS_ENABLED
 280
 281
 282   /** Adds a new resource into the recently used resources list, taking
 283    * meta data from the given Data instead of guessing it from the URI.
 284    */
 285   bool add_item(const Glib::ustring& uri, const Data& recent_data);
 286
 287
 288   /** Removes a resource pointed by @a uri  from the recently used resources
 289    * list handled by a recent manager.
 290    * @param uri The URI of the item you wish to remove.
 291    * @param error Return location for a G::Error, or <tt>0</tt>.
 292    * @return <tt>true</tt> if the item pointed by @a uri  has been successfully
 293    * removed by the recently used resources list, and <tt>false</tt> otherwise.
 294    *
 295    * @newin2p10.
 296    */
 297 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 298   bool remove_item(const Glib::ustring& uri);
 299 #else
 300   bool remove_item(const Glib::ustring& uri, std::auto_ptr<Glib::Error>& error);
 301 #endif //GLIBMM_EXCEPTIONS_ENABLED
 302
 303
 304   /** Searches for a URI inside the recently used resources list, and
 305    * Return value: a Gtk::RecentInfo structure containing information
 306    * @param uri A URI.
 307    * @param error A return location for a G::Error, or <tt>0</tt>.
 308    * @return A Gtk::RecentInfo structure containing information
 309    * about the resource pointed by @a uri , or <tt>0</tt> if the URI was
 310    * not registered in the recently used resources list.  Free with
 311    * gtk_recent_info_unref().
 312    *
 313    * @newin2p10.
 314    */
 315 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 316   Glib::RefPtr<RecentInfo> lookup_item(const Glib::ustring& uri);
 317 #else
 318   Glib::RefPtr<RecentInfo> lookup_item(const Glib::ustring& uri, std::auto_ptr<Glib::Error>& error);
 319 #endif //GLIBMM_EXCEPTIONS_ENABLED
 320
 321
 322   /** Searches for a URI inside the recently used resources list, and
 323    * Return value: a Gtk::RecentInfo structure containing information
 324    * @param uri A URI.
 325    * @param error A return location for a G::Error, or <tt>0</tt>.
 326    * @return A Gtk::RecentInfo structure containing information
 327    * about the resource pointed by @a uri , or <tt>0</tt> if the URI was
 328    * not registered in the recently used resources list.  Free with
 329    * gtk_recent_info_unref().
 330    *
 331    * @newin2p10.
 332    */
 333 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 334   Glib::RefPtr<const RecentInfo> lookup_item(const Glib::ustring& uri) const;
 335 #else
 336   Glib::RefPtr<const RecentInfo> lookup_item(const Glib::ustring& uri, std::auto_ptr<Glib::Error>& error) const;
 337 #endif //GLIBMM_EXCEPTIONS_ENABLED
 338
 339
 340   /** Checks whether there is a recently used resource registered
 341    * with @a uri  inside the recent manager.
 342    * @param uri A URI.
 343    * @return <tt>true</tt> if the resource was found, <tt>false</tt> otherwise.
 344    *
 345    * @newin2p10.
 346    */
 347   bool has_item(const Glib::ustring& uri) const;
 348
 349   /** Changes the location of a recently used resource from @a uri  to @a new_uri .
 350    *
 351    * Please note that this function will not affect the resource pointed
 352    * by the URIs, but only the URI used in the recently used resources list.
 353    * @param uri The URI of a recently used resource.
 354    * @param new_uri The new URI of the recently used resource, or <tt>0</tt> to
 355    * remove the item pointed by @a uri  in the list.
 356    * @param error A return location for a G::Error, or <tt>0</tt>.
 357    * @return <tt>true</tt> on success.
 358    *
 359    * @newin2p10.
 360    */
 361 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 362   bool move_item(const Glib::ustring& uri, const Glib::ustring& new_uri);
 363 #else
 364   bool move_item(const Glib::ustring& uri, const Glib::ustring& new_uri, std::auto_ptr<Glib::Error>& error);
 365 #endif //GLIBMM_EXCEPTIONS_ENABLED
 366
 367
 368   /** Sets the maximum number of item that the get_items()
 369    * function should return.  If @a limit  is set to -1, then return all the
 370    * items.
 371    *
 372    * @newin2p10
 373    * @param limit The maximum number of items to return, or -1.
 374    */
 375   void set_limit(int limit);
 376
 377   /** Gets the maximum number of items that the get_items()
 378    * function should return.
 379    * @return The number of items to return, or -1 for every item.
 380    *
 381    * @newin2p10.
 382    */
 383   int get_limit() const;
 384
 385   typedef Glib::ListHandle<RecentInfo, RecentInfoTraits> ListHandle_RecentInfos;
 386
 387
 388   /** Gets the list of recently used resources.
 389    * @return A list of newly allocated Gtk::RecentInfo objects. Use
 390    * gtk_recent_info_unref() on each item inside the list, and then
 391    * free the list itself using Glib::list_free().
 392    *
 393    * @newin2p10.
 394    */
 395   ListHandle_RecentInfos get_items() const;
 396
 397
 398   /** Purges every item from the recently used resources list.
 399    * @param error A return location for a G::Error, or <tt>0</tt>.
 400    * @return The number of items that have been removed from the
 401    * recently used resources list.
 402    *
 403    * @newin2p10.
 404    */
 405 #ifdef GLIBMM_EXCEPTIONS_ENABLED
 406   int purge_items();
 407 #else
 408   int purge_items(std::auto_ptr<Glib::Error>& error);
 409 #endif //GLIBMM_EXCEPTIONS_ENABLED
 410
 411
 412   /// For instance, void on_changed();
 413   typedef sigc::slot<void> SlotChanged;
 414
 415   /** The "changed" signal is emitted when an item in the recently used resources list is changed.
 416   *
 417    * @par Prototype:
 418    * <tt>void on_my_%changed()</tt>
 419    */
 420
 421   Glib::SignalProxy0< void > signal_changed();
 422
 423
 424   #ifdef GLIBMM_PROPERTIES_ENABLED
 425 /** The full path to the file to be used to store and read the list.
 426    *
 427    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 428    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 429    * the value of the property changes.
 430    */
 431   Glib::PropertyProxy_ReadOnly<Glib::ustring> property_filename() const;
 432 #endif //#GLIBMM_PROPERTIES_ENABLED
 433
 434
 435   #ifdef GLIBMM_PROPERTIES_ENABLED
 436 /** The maximum number of items to be returned by gtk_recent_manager_get_items().
 437    *
 438    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 439    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 440    * the value of the property changes.
 441    */
 442   Glib::PropertyProxy<int> property_limit() ;
 443 #endif //#GLIBMM_PROPERTIES_ENABLED
 444
 445 #ifdef GLIBMM_PROPERTIES_ENABLED
 446 /** The maximum number of items to be returned by gtk_recent_manager_get_items().
 447    *
 448    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 449    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 450    * the value of the property changes.
 451    */
 452   Glib::PropertyProxy_ReadOnly<int> property_limit() const;
 453 #endif //#GLIBMM_PROPERTIES_ENABLED
 454
 455   #ifdef GLIBMM_PROPERTIES_ENABLED
 456 /** The size of the recently used resources list.
 457    *
 458    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 459    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 460    * the value of the property changes.
 461    */
 462   Glib::PropertyProxy_ReadOnly<int> property_size() const;
 463 #endif //#GLIBMM_PROPERTIES_ENABLED
 464
 465
 466 public:
 467
 468 public:
 469   //C++ methods used to invoke GTK+ virtual functions:
 470 #ifdef GLIBMM_VFUNCS_ENABLED
 471 #endif //GLIBMM_VFUNCS_ENABLED
 472
 473 protected:
 474   //GTK+ Virtual Functions (override these to change behaviour):
 475 #ifdef GLIBMM_VFUNCS_ENABLED
 476 #endif //GLIBMM_VFUNCS_ENABLED
 477
 478   //Default Signal Handlers::
 479 #ifdef GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 480   virtual void on_changed();
 481 #endif //GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 482
 483
 484 };
 485
 486 } // namespace Gtk
 487
 488
 489 namespace Glib
 490 {
 491   /** A Glib::wrap() method for this object.
 492    *
 493    * @param object The C instance.
 494    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 495    * @result A C++ instance that wraps this C instance.
 496    *
 497    * @relates Gtk::RecentManager
 498    */
 499   Glib::RefPtr<Gtk::RecentManager> wrap(GtkRecentManager* object, bool take_copy = false);
 500 }
 501
 502
 503 #endif /* _GTKMM_RECENTMANAGER_H */
 504