// -*- c++ -*- // Generated by gtkmmproc -- DO NOT MODIFY! #ifndef _GTKMM_RECENTMANAGER_H #define _GTKMM_RECENTMANAGER_H #include /* Copyright (C) 2006 The gtkmm Development Team * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Library 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 * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public * License along with this library; if not, write to the Free * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. */ #include #include #include #include #include #ifndef DOXYGEN_SHOULD_SKIP_THIS typedef struct _GtkRecentManager GtkRecentManager; typedef struct _GtkRecentManagerClass GtkRecentManagerClass; #endif /* DOXYGEN_SHOULD_SKIP_THIS */ namespace Gtk { class RecentManager_Class; } // namespace Gtk namespace Gtk { /** Exception class for Gtk::RecentManager errors. */ class RecentManagerError : public Glib::Error { public: enum Code { NOT_FOUND, INVALID_URI, INVALID_ENCODING, NOT_REGISTERED, READ, WRITE, UNKNOWN }; RecentManagerError(Code error_code, const Glib::ustring& error_message); explicit RecentManagerError(GError* gobject); Code code() const; #ifndef DOXYGEN_SHOULD_SKIP_THIS private: #ifdef GLIBMM_EXCEPTIONS_ENABLED static void throw_func(GError* gobject); #else //When not using exceptions, we just pass the Exception object around without throwing it: static std::auto_ptr throw_func(GError* gobject); #endif //GLIBMM_EXCEPTIONS_ENABLED friend void wrap_init(); // uses throw_func() #endif }; } // namespace Gtk #ifndef DOXYGEN_SHOULD_SKIP_THIS namespace Glib { template <> class Value : public Glib::Value_Enum { public: static GType value_type() G_GNUC_CONST; }; } // namespace Glib #endif /* DOXYGEN_SHOULD_SKIP_THIS */ namespace Gtk { /** @defgroup RecentFiles RecentFiles */ /** RecentManager provides a facility for adding, removing and * looking up recently used files. Each recently used file is * identified by its URI, and has meta-data associated to it, like * the names and command lines of the applications that have * registered it, the number of time each application has registered * the same file, the mime type of the file and whether the file * should be displayed only by the applications that have * registered it. * * The RecentManager acts like a database of all the recently * used files. You can create new RecentManager objects, but * it is more efficient to use the standard recent manager for * the Gdk::Screen so that informations about the recently used * files is shared with other people using them. Normally, you * retrieve the recent manager for a particular screen using * get_for_screen() and it will contain information about current * recent manager for that screen. * * @newin2p10 * * @ingroup RecentFiles */ class RecentManager : public Glib::Object { #ifndef DOXYGEN_SHOULD_SKIP_THIS public: typedef RecentManager CppObjectType; typedef RecentManager_Class CppClassType; typedef GtkRecentManager BaseObjectType; typedef GtkRecentManagerClass BaseClassType; private: friend class RecentManager_Class; static CppClassType recentmanager_class_; private: // noncopyable RecentManager(const RecentManager&); RecentManager& operator=(const RecentManager&); protected: explicit RecentManager(const Glib::ConstructParams& construct_params); explicit RecentManager(GtkRecentManager* castitem); #endif /* DOXYGEN_SHOULD_SKIP_THIS */ public: virtual ~RecentManager(); #ifndef DOXYGEN_SHOULD_SKIP_THIS static GType get_type() G_GNUC_CONST; static GType get_base_type() G_GNUC_CONST; #endif ///Provides access to the underlying C GObject. GtkRecentManager* gobj() { return reinterpret_cast(gobject_); } ///Provides access to the underlying C GObject. const GtkRecentManager* gobj() const { return reinterpret_cast(gobject_); } ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. GtkRecentManager* gobj_copy(); private: protected: RecentManager(); public: static Glib::RefPtr create(); /** Gets a unique instance of Gtk::RecentManager, that you can share * in your application without caring about memory management. The * returned instance will be freed when you application terminates. * @return A unique Gtk::RecentManager. Do not ref or unref it. * * @newin2p10. */ static Glib::RefPtr get_default(); /** Gets the recent manager object associated with @a screen ; if this * function has not previously been called for the given screen, * a new recent manager object will be created and associated with * the screen. Recent manager objects are fairly expensive to create, * so using this function is usually a better choice than calling * new() and setting the screen yourself; by using * this function a single recent manager object will be shared between * users. * @param screen A Gdk::Screen. * @return A unique Gtk::RecentManager associated with the given * screen. This recent manager is associated to the with the screen * and can be used as long as the screen is open. Do not ref or * unref it. * * Deprecated: 2.12: This function has been deprecated and should * not be used in newly written code. Calling this function is * equivalent to calling get_default(). * * @newin2p10. */ static Glib::RefPtr get_for_screen(const Glib::RefPtr& screen); /** Meta-data passed to add_item(). You should * use RecentManager::Data if you want to control the meta-data associated * to an entry of the recently used files list when you are adding * a new file to it. * * - display_name: the string to be used when displaying the file inside a RecentChooser * - description: a user readable description of the file * - mime_type: the mime type of the file * - app_name: the name of the application that is registering the file * - app_exec: the command line that should be used when launching the file * - groups: the list of group names to which the file belongs to * - is_private: whether the file should be displayed only by the applications that have registered it */ class Data { public: Glib::ustring display_name; Glib::ustring description; Glib::ustring mime_type; Glib::ustring app_name; Glib::ustring app_exec; std::vector groups; bool is_private; }; /** Sets the screen for a recent manager; the screen is used to * track the user's currently configured recently used documents * storage. * * @newin2p10 * * Deprecated: 2.12: This function has been deprecated and should * not be used in newly written code. Calling this function has * no effect. * @param screen A Gdk::Screen. */ void set_screen(const Glib::RefPtr& screen); /** Adds a new resource into the recently used resources list. This function * will try and guess some of the meta-data associated to a URI. If you * know some of meta-data about the document yourself, set the desired * fields of a RecentManager::Data structure and pass it to add_item(). */ /** Adds a new resource, pointed by @a uri , into the recently used * resources list. * * This function automatically retrieving some of the needed * metadata and setting other metadata to common default values; it * then feeds the data to add_full(). * * See add_full() if you want to explicitely * define the metadata for the resource pointed by @a uri . * @param uri A valid URI. * @return true if the new item was successfully added * to the recently used resources list * * @newin2p10. */ #ifdef GLIBMM_EXCEPTIONS_ENABLED bool add_item(const Glib::ustring& uri); #else bool add_item(const Glib::ustring& uri, std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED /** Adds a new resource into the recently used resources list, taking * meta data from the given Data instead of guessing it from the URI. */ bool add_item(const Glib::ustring& uri, const Data& recent_data); /** Removes a resource pointed by @a uri from the recently used resources * list handled by a recent manager. * @param uri The URI of the item you wish to remove. * @param error Return location for a G::Error, or 0. * @return true if the item pointed by @a uri has been successfully * removed by the recently used resources list, and false otherwise. * * @newin2p10. */ #ifdef GLIBMM_EXCEPTIONS_ENABLED bool remove_item(const Glib::ustring& uri); #else bool remove_item(const Glib::ustring& uri, std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED /** Searches for a URI inside the recently used resources list, and * Return value: a Gtk::RecentInfo structure containing information * @param uri A URI. * @param error A return location for a G::Error, or 0. * @return A Gtk::RecentInfo structure containing information * about the resource pointed by @a uri , or 0 if the URI was * not registered in the recently used resources list. Free with * gtk_recent_info_unref(). * * @newin2p10. */ #ifdef GLIBMM_EXCEPTIONS_ENABLED Glib::RefPtr lookup_item(const Glib::ustring& uri); #else Glib::RefPtr lookup_item(const Glib::ustring& uri, std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED /** Searches for a URI inside the recently used resources list, and * Return value: a Gtk::RecentInfo structure containing information * @param uri A URI. * @param error A return location for a G::Error, or 0. * @return A Gtk::RecentInfo structure containing information * about the resource pointed by @a uri , or 0 if the URI was * not registered in the recently used resources list. Free with * gtk_recent_info_unref(). * * @newin2p10. */ #ifdef GLIBMM_EXCEPTIONS_ENABLED Glib::RefPtr lookup_item(const Glib::ustring& uri) const; #else Glib::RefPtr lookup_item(const Glib::ustring& uri, std::auto_ptr& error) const; #endif //GLIBMM_EXCEPTIONS_ENABLED /** Checks whether there is a recently used resource registered * with @a uri inside the recent manager. * @param uri A URI. * @return true if the resource was found, false otherwise. * * @newin2p10. */ bool has_item(const Glib::ustring& uri) const; /** Changes the location of a recently used resource from @a uri to @a new_uri . * * Please note that this function will not affect the resource pointed * by the URIs, but only the URI used in the recently used resources list. * @param uri The URI of a recently used resource. * @param new_uri The new URI of the recently used resource, or 0 to * remove the item pointed by @a uri in the list. * @param error A return location for a G::Error, or 0. * @return true on success. * * @newin2p10. */ #ifdef GLIBMM_EXCEPTIONS_ENABLED bool move_item(const Glib::ustring& uri, const Glib::ustring& new_uri); #else bool move_item(const Glib::ustring& uri, const Glib::ustring& new_uri, std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED /** Sets the maximum number of item that the get_items() * function should return. If @a limit is set to -1, then return all the * items. * * @newin2p10 * @param limit The maximum number of items to return, or -1. */ void set_limit(int limit); /** Gets the maximum number of items that the get_items() * function should return. * @return The number of items to return, or -1 for every item. * * @newin2p10. */ int get_limit() const; typedef Glib::ListHandle ListHandle_RecentInfos; /** Gets the list of recently used resources. * @return A list of newly allocated Gtk::RecentInfo objects. Use * gtk_recent_info_unref() on each item inside the list, and then * free the list itself using Glib::list_free(). * * @newin2p10. */ ListHandle_RecentInfos get_items() const; /** Purges every item from the recently used resources list. * @param error A return location for a G::Error, or 0. * @return The number of items that have been removed from the * recently used resources list. * * @newin2p10. */ #ifdef GLIBMM_EXCEPTIONS_ENABLED int purge_items(); #else int purge_items(std::auto_ptr& error); #endif //GLIBMM_EXCEPTIONS_ENABLED /// For instance, void on_changed(); typedef sigc::slot SlotChanged; /** The "changed" signal is emitted when an item in the recently used resources list is changed. * * @par Prototype: * void on_my_%changed() */ Glib::SignalProxy0< void > signal_changed(); #ifdef GLIBMM_PROPERTIES_ENABLED /** The full path to the file to be used to store and read the list. * * You rarely need to use properties because there are get_ and set_ methods for almost all of them. * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when * the value of the property changes. */ Glib::PropertyProxy_ReadOnly property_filename() const; #endif //#GLIBMM_PROPERTIES_ENABLED #ifdef GLIBMM_PROPERTIES_ENABLED /** The maximum number of items to be returned by gtk_recent_manager_get_items(). * * You rarely need to use properties because there are get_ and set_ methods for almost all of them. * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when * the value of the property changes. */ Glib::PropertyProxy property_limit() ; #endif //#GLIBMM_PROPERTIES_ENABLED #ifdef GLIBMM_PROPERTIES_ENABLED /** The maximum number of items to be returned by gtk_recent_manager_get_items(). * * You rarely need to use properties because there are get_ and set_ methods for almost all of them. * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when * the value of the property changes. */ Glib::PropertyProxy_ReadOnly property_limit() const; #endif //#GLIBMM_PROPERTIES_ENABLED #ifdef GLIBMM_PROPERTIES_ENABLED /** The size of the recently used resources list. * * You rarely need to use properties because there are get_ and set_ methods for almost all of them. * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when * the value of the property changes. */ Glib::PropertyProxy_ReadOnly property_size() const; #endif //#GLIBMM_PROPERTIES_ENABLED public: public: //C++ methods used to invoke GTK+ virtual functions: #ifdef GLIBMM_VFUNCS_ENABLED #endif //GLIBMM_VFUNCS_ENABLED protected: //GTK+ Virtual Functions (override these to change behaviour): #ifdef GLIBMM_VFUNCS_ENABLED #endif //GLIBMM_VFUNCS_ENABLED //Default Signal Handlers:: #ifdef GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED virtual void on_changed(); #endif //GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED }; } // namespace Gtk namespace Glib { /** A Glib::wrap() method for this object. * * @param object The C instance. * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref. * @result A C++ instance that wraps this C instance. * * @relates Gtk::RecentManager */ Glib::RefPtr wrap(GtkRecentManager* object, bool take_copy = false); } #endif /* _GTKMM_RECENTMANAGER_H */