diff --git a/docs/reference/gtk/tmpl/gtkrecentmanager.sgml b/docs/reference/gtk/tmpl/gtkrecentmanager.sgml deleted file mode 100644 index 0f5ab0add5..0000000000 --- a/docs/reference/gtk/tmpl/gtkrecentmanager.sgml +++ /dev/null @@ -1,464 +0,0 @@ - -GtkRecentManager - - -Managing Recently Used Files - - - -#GtkRecentManager 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 #GtkRecentManager acts like a database of all the recently -used files. You can create new #GtkRecentManager objects, but -it is more efficient to use the standard recent manager for -the #GdkScreen so that informations about the recently used -files is shared with other people using them. In case the -default screen is being used, adding a new recently used -file is as simple as: - - - - -GtkRecentManager *manager; - -manager = gtk_recent_manager_get_default (); -gtk_recent_manager_add_item (manager, file_uri); - - - -While looking up a recently used file is as simple as: - - - -GtkRecentManager *manager; -GtkRecentInfo *info; -GError *error = NULL; - -manager = gtk_recent_manager_get_default (); -info = gtk_recent_manager_lookup_item (manager, file_uri, &error); -if (error) - { - g_warning ("Could not find the file: %s", error->message); - g_error_free (error); - } -else - { - /* Use the info object */ - gtk_recent_info_unref (info); - } - - - - -Recently used files are supported since GTK+ 2.10. - - - - - - - - - - - - - - - -Acts as a database of information about the list of recently -used files. Normally, you retrieve the recent manager for a -particular screen using gtk_recent_manager_get_for_screen() -and it will contain information about current recent manager -for that screen. - - - - - - - -@recentmanager: the object which received the signal. - - - - - - - - - - - - - - - - - - -Contains informations found when looking up an entry of the -recently used files list. - - - - - - - - -@display_name: -@description: -@mime_type: -@app_name: -@app_exec: -@groups: -@is_private: - - - -The #GQuark used for #GtkRecentManagerError errors. - - - - - - - - - -@GTK_RECENT_MANAGER_ERROR_NOT_FOUND: -@GTK_RECENT_MANAGER_ERROR_INVALID_URI: -@GTK_RECENT_MANAGER_ERROR_INVALID_ENCODING: -@GTK_RECENT_MANAGER_ERROR_NOT_REGISTERED: -@GTK_RECENT_MANAGER_ERROR_READ: -@GTK_RECENT_MANAGER_ERROR_WRITE: -@GTK_RECENT_MANAGER_ERROR_UNKNOWN: - - - - - - -@void: -@Returns: - - - - - - - -@void: -@Returns: - - - - - - - -@manager: -@uri: -@Returns: - - - - - - - -@manager: -@uri: -@recent_data: -@Returns: - - - - - - - -@manager: -@uri: -@error: -@Returns: - - - - - - - -@manager: -@uri: -@error: -@Returns: - - - - - - - -@manager: -@uri: -@Returns: - - - - - - - -@manager: -@uri: -@new_uri: -@error: -@Returns: - - - - - - - -@manager: -@Returns: - - - - - - - -@manager: -@error: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: - - - - - - - -@info: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: -@app_name: -@app_exec: -@count: -@time_: -@Returns: - - - - - - - -@info: -@length: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: -@length: -@Returns: - - - - - - - -@info: -@group_name: -@Returns: - - - - - - - -@info: -@app_name: -@Returns: - - - - - - - -@info: -@size: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info: -@Returns: - - - - - - - -@info_a: -@info_b: -@Returns: - - diff --git a/gtk/gtkrecentmanager.c b/gtk/gtkrecentmanager.c index 58b41dca79..4226de2997 100644 --- a/gtk/gtkrecentmanager.c +++ b/gtk/gtkrecentmanager.c @@ -18,6 +18,75 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, */ +/** + * SECTION:gtkrecentmanager + * @Title: GtkRecentManager + * @short_description: Managing recently used files + * @See_Also: #GBookmarkFile, #GtkSettings, #GtkRecentChooser + * + * #GtkRecentManager 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 recently used files list is per user. + * + * The #GtkRecentManager acts like a database of all the recently + * used files. You can create new #GtkRecentManager objects, but + * it is more efficient to use the default manager created by GTK+. + * + * Adding a new recently used file is as simple as: + * + * |[ + * GtkRecentManager *manager; + * + * manager = gtk_recent_manager_get_default (); + * gtk_recent_manager_add_item (manager, file_uri); + * ]| + * + * The #GtkRecentManager will try to gather all the needed information + * from the file itself through GIO. + * + * Looking up the meta-data associated with a recently used file + * given its URI requires calling gtk_recent_manager_lookup_item(): + * + * |[ + * GtkRecentManager *manager; + * GtkRecentInfo *info; + * GError *error = NULL; + * + * manager = gtk_recent_manager_get_default (); + * info = gtk_recent_manager_lookup_item (manager, file_uri, &error); + * if (error) + * { + * g_warning ("Could not find the file: %s", error->message); + * g_error_free (error); + * } + * else + * { + * /* Use the info object */ + * gtk_recent_info_unref (info); + * } + * ]| + * + * In order to retrieve the list of recently used files, you can use + * gtk_recent_manager_get_items(), which returns a list of #GtkRecentInfo + * structures. + * + * A #GtkRecentManager is the model used to populate the contents of + * one, or more #GtkRecentChooser implementations. + * + * The maximum age of the recently used files list is + * controllable through the #GtkSettings:gtk-recent-files-max-age + * property. + * + * Recently used files are supported since GTK+ 2.10. + */ + #include "config.h" #include @@ -59,6 +128,17 @@ typedef struct time_t stamp; } RecentAppInfo; +/** + * GtkRecentInfo: + * + * GtkRecentInfo is an opaque data structure + * whose members can only be accessed using the provided API. + * + * GtkRecentInfo constains all the meta-data + * associated with an entry in the recently used files list. + * + * Since: 2.10 + */ struct _GtkRecentInfo { gchar *uri; @@ -84,7 +164,6 @@ struct _GtkRecentInfo gint ref_count; }; - struct _GtkRecentManagerPrivate { gchar *filename; @@ -235,7 +314,8 @@ gtk_recent_manager_class_init (GtkRecentManagerClass *klass) * @recent_manager: the recent manager * * Emitted when the current recently used resources manager changes its - * contents. + * contents, either by calling gtk_recent_manager_add_item() or by another + * application. * * Since: 2.10 */ diff --git a/gtk/gtkrecentmanager.h b/gtk/gtkrecentmanager.h index 105d0e2fe7..f23b61e364 100644 --- a/gtk/gtkrecentmanager.h +++ b/gtk/gtkrecentmanager.h @@ -81,14 +81,29 @@ struct _GtkRecentData gboolean is_private; }; +/** + * GtkRecentManager: + * + * GtkRecentManager contains only private data + * and should be accessed using the provided API. + * + * Since: 2.10 + */ struct _GtkRecentManager { + /* */ GObject parent_instance; - /* */ GtkRecentManagerPrivate *priv; }; +/** + * GtkRecentManagerClass: + * + * GtkRecentManagerClass contains only private data. + * + * Since: 2.10 + */ struct _GtkRecentManagerClass { /*< private >*/ @@ -118,8 +133,10 @@ struct _GtkRecentManagerClass * resources file. * @GTK_RECENT_MANAGER_ERROR_UNKNOWN: unspecified error. * - * Error codes for GtkRecentManager operations - **/ + * Error codes for #GtkRecentManager operations + * + * Since: 2.10 + */ typedef enum { GTK_RECENT_MANAGER_ERROR_NOT_FOUND, @@ -131,6 +148,13 @@ typedef enum GTK_RECENT_MANAGER_ERROR_UNKNOWN } GtkRecentManagerError; +/** + * GTK_RECENT_MANAGER_ERROR: + * + * The #GError domain for #GtkRecentManager errors. + * + * Since: 2.10 + */ #define GTK_RECENT_MANAGER_ERROR (gtk_recent_manager_error_quark ()) GQuark gtk_recent_manager_error_quark (void);