GtkRecentManager

typedef struct _GtkRecentManager GtkRecentManager;

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.

GtkRecentInfo

typedef struct _GtkRecentInfo GtkRecentInfo;

Contains informations found when looking up an entry of the recently used files list.

GtkRecentData

typedef struct {
  gchar *display_name;
  gchar *description;

  gchar *mime_type;

  gchar *app_name;
  gchar *app_exec;

  gchar **groups;

  gboolean is_private;
} GtkRecentData;

Meta-data to be passed to gtk_recent_manager_add_full() when registering a recently used resource.

GTK_RECENT_MANAGER_ERROR

#define GTK_RECENT_MANAGER_ERROR (gtk_recent_manager_error_quark ())

The GQuark used for GtkRecentManagerError errors.

enum GtkRecentManagerError

typedef enum
{
  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
} GtkRecentManagerError;

Error codes for GtkRecentManager operations

gtk_recent_manager_new ()

GtkRecentManager *  gtk_recent_manager_new              (void);

Creates a new recent manager object. Recent manager objects are used to handle the list of recently used resources. A GtkRecentManager object monitors the recently used resources list, and emits the "changed" signal each time something inside the list changes.

GtkRecentManager objects are expensive: be sure to create them only when needed. You should use gtk_recent_manager_get_default() instead.

Since 2.10

gtk_recent_manager_get_default ()

GtkRecentManager *  gtk_recent_manager_get_default      (void);

Gets a unique instance of GtkRecentManager, that you can share in your application without caring about memory management. The returned instance will be freed when you application terminates.

Since 2.10

gtk_recent_manager_get_for_screen ()

GtkRecentManager *  gtk_recent_manager_get_for_screen   (GdkScreen *screen);

Gets the recent manager object associated with 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 gtk_recent_manager_new() and setting the screen yourself; by using this function a single recent manager object will be shared between users.

Since 2.10

gtk_recent_manager_set_screen ()

void                gtk_recent_manager_set_screen       (GtkRecentManager *manager,
                                                         GdkScreen *screen);

Sets the screen for a recent manager; the screen is used to track the user's currently configured recently used documents storage.

Since 2.10

gtk_recent_manager_add_item ()

gboolean            gtk_recent_manager_add_item         (GtkRecentManager *manager,
                                                         const gchar *uri);

Adds a new resource, pointed by uri, into the recently used resources list.

This function automatically retrieves some of the needed metadata and setting other metadata to common default values; it then feeds the data to gtk_recent_manager_add_full().

See gtk_recent_manager_add_full() if you want to explicitly define the metadata for the resource pointed by uri.

Since 2.10

gtk_recent_manager_add_full ()

gboolean            gtk_recent_manager_add_full         (GtkRecentManager *manager,
                                                         const gchar *uri,
                                                         const GtkRecentData *recent_data);

Adds a new resource, pointed by uri, into the recently used resources list, using the metadata specified inside the GtkRecentData structure passed in recent_data.

The passed URI will be used to identify this resource inside the list.

In order to register the new recently used resource, metadata about the resource must be passed as well as the URI; the metadata is stored in a GtkRecentData structure, which must contain the MIME type of the resource pointed by the URI; the name of the application that is registering the item, and a command line to be used when launching the item.

Optionally, a GtkRecentData structure might contain a UTF-8 string to be used when viewing the item instead of the last component of the URI; a short description of the item; whether the item should be considered private - that is, should be displayed only by the applications that have registered it.

Since 2.10

gtk_recent_manager_remove_item ()

gboolean            gtk_recent_manager_remove_item      (GtkRecentManager *manager,
                                                         const gchar *uri,
                                                         GError **error);

Removes a resource pointed by uri from the recently used resources list handled by a recent manager.

Since 2.10

gtk_recent_manager_lookup_item ()

GtkRecentInfo *     gtk_recent_manager_lookup_item      (GtkRecentManager *manager,
                                                         const gchar *uri,
                                                         GError **error);

Searches for a URI inside the recently used resources list, and returns a structure containing informations about the resource like its MIME type, or its display name.

Since 2.10

gtk_recent_manager_has_item ()

gboolean            gtk_recent_manager_has_item         (GtkRecentManager *manager,
                                                         const gchar *uri);

Checks whether there is a recently used resource registered with uri inside the recent manager.

Since 2.10

gtk_recent_manager_move_item ()

gboolean            gtk_recent_manager_move_item        (GtkRecentManager *manager,
                                                         const gchar *uri,
                                                         const gchar *new_uri,
                                                         GError **error);

Changes the location of a recently used resource from uri to 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.

Since 2.10

gtk_recent_manager_get_limit ()

gint                gtk_recent_manager_get_limit        (GtkRecentManager *manager);

Gets the maximum number of items that the gtk_recent_manager_get_items() function should return.

Since 2.10

gtk_recent_manager_set_limit ()

void                gtk_recent_manager_set_limit        (GtkRecentManager *manager,
                                                         gint limit);

Sets the maximum number of item that the gtk_recent_manager_get_items() function should return. If limit is set to -1, then return all the items.

Since 2.10

gtk_recent_manager_get_items ()

GList *             gtk_recent_manager_get_items        (GtkRecentManager *manager);

Gets the list of recently used resources.

Since 2.10

gtk_recent_manager_purge_items ()

gint                gtk_recent_manager_purge_items      (GtkRecentManager *manager,
                                                         GError **error);

Purges every item from the recently used resources list.

Since 2.10

gtk_recent_info_ref ()

GtkRecentInfo *     gtk_recent_info_ref                 (GtkRecentInfo *info);

Increases the reference count of recent_info by one.

Since 2.10

gtk_recent_info_unref ()

void                gtk_recent_info_unref               (GtkRecentInfo *info);

Decreases the reference count of info by one. If the reference count reaches zero, info is deallocated, and the memory freed.

Since 2.10

gtk_recent_info_get_uri ()

const gchar *       gtk_recent_info_get_uri             (GtkRecentInfo *info);

Gets the URI of the resource.

Since 2.10

gtk_recent_info_get_display_name ()

const gchar *       gtk_recent_info_get_display_name    (GtkRecentInfo *info);

Gets the name of the resource. If none has been defined, the basename of the resource is obtained.

Since 2.10

gtk_recent_info_get_description ()

const gchar *       gtk_recent_info_get_description     (GtkRecentInfo *info);

Gets the (short) description of the resource.

Since 2.10

gtk_recent_info_get_mime_type ()

const gchar *       gtk_recent_info_get_mime_type       (GtkRecentInfo *info);

Gets the MIME type of the resource.

Since 2.10

gtk_recent_info_get_added ()

time_t              gtk_recent_info_get_added           (GtkRecentInfo *info);

Gets the timestamp (seconds from system's Epoch) when the resource was added to the recently used resources list.

Since 2.10

gtk_recent_info_get_modified ()

time_t              gtk_recent_info_get_modified        (GtkRecentInfo *info);

Gets the timestamp (seconds from system's Epoch) when the resource was last modified.

Since 2.10

gtk_recent_info_get_visited ()

time_t              gtk_recent_info_get_visited         (GtkRecentInfo *info);

Gets the timestamp (seconds from system's Epoch) when the resource was last visited.

Since 2.10

gtk_recent_info_get_private_hint ()

gboolean            gtk_recent_info_get_private_hint    (GtkRecentInfo *info);

Gets the value of the "private" flag. Resources in the recently used list that have this flag set to TRUE should only be displayed by the applications that have registered them.

Since 2.10

gtk_recent_info_get_application_info ()

gboolean            gtk_recent_info_get_application_info
                                                        (GtkRecentInfo *info,
                                                         const gchar *app_name,
                                                         const gchar **app_exec,
                                                         guint *count,
                                                         time_t *time_);

Gets the data regarding the application that has registered the resource pointed by info.

If the command line contains any escape characters defined inside the storage specification, they will be expanded.

Since 2.10

gtk_recent_info_get_applications ()

gchar **            gtk_recent_info_get_applications    (GtkRecentInfo *info,
                                                         gsize *length);

Retrieves the list of applications that have registered this resource.

Since 2.10

gtk_recent_info_last_application ()

gchar *             gtk_recent_info_last_application    (GtkRecentInfo *info);

Gets the name of the last application that have registered the recently used resource represented by info.

Since 2.10

gtk_recent_info_get_groups ()

gchar **            gtk_recent_info_get_groups          (GtkRecentInfo *info,
                                                         gsize *length);

Returns all groups registered for the recently used item info. The array of returned group names will be NULL terminated, so length might optionally be NULL.

Since 2.10

gtk_recent_info_has_group ()

gboolean            gtk_recent_info_has_group           (GtkRecentInfo *info,
                                                         const gchar *group_name);

Checks whether group_name appears inside the groups registered for the recently used item info.

Since 2.10

gtk_recent_info_has_application ()

gboolean            gtk_recent_info_has_application     (GtkRecentInfo *info,
                                                         const gchar *app_name);

Checks whether an application registered this resource using app_name.

Since 2.10

gtk_recent_info_get_icon ()

GdkPixbuf *         gtk_recent_info_get_icon            (GtkRecentInfo *info,
                                                         gint size);

Retrieves the icon of size size associated to the resource MIME type.

Since 2.10

gtk_recent_info_get_short_name ()

gchar *             gtk_recent_info_get_short_name      (GtkRecentInfo *info);

Computes a valid UTF-8 string that can be used as the name of the item in a menu or list. For example, calling this function on an item that refers to "file:///foo/bar.txt" will yield "bar.txt".

Since 2.10

gtk_recent_info_get_uri_display ()

gchar *             gtk_recent_info_get_uri_display     (GtkRecentInfo *info);

Gets a displayable version of the resource's URI. If the resource is local, it returns a local path; if the resource is not local, it returns the UTF-8 encoded content of gtk_recent_info_get_uri().

Since 2.10

gtk_recent_info_get_age ()

gint                gtk_recent_info_get_age             (GtkRecentInfo *info);

Gets the number of days elapsed since the last update of the resource pointed by info.

Since 2.10

gtk_recent_info_is_local ()

gboolean            gtk_recent_info_is_local            (GtkRecentInfo *info);

Checks whether the resource is local or not by looking at the scheme of its URI.

Since 2.10

gtk_recent_info_exists ()

gboolean            gtk_recent_info_exists              (GtkRecentInfo *info);

Checks whether the resource pointed by info still exists. At the moment this check is done only on resources pointing to local files.

Since 2.10

gtk_recent_info_match ()

gboolean            gtk_recent_info_match               (GtkRecentInfo *info_a,
                                                         GtkRecentInfo *info_b);

Checks whether two GtkRecentInfo structures point to the same resource.

Since 2.10

The "filename" property

  "filename"                 gchar*                : Read / Write / Construct Only

The full path to the file to be used to store and read the recently used resources list

Default value: NULL

Since 2.10

The "limit" property

  "limit"                    gint                  : Read / Write

The maximum number of items to be returned by the gtk_recent_manager_get_items() function.

Allowed values: >= G_MAXULONG

Default value: -1

Since 2.10

The "size" property

  "size"                     gint                  : Read

The size of the recently used resources list.

Allowed values: >= G_MAXULONG

Default value: 0

Since 2.10

The "changed" signal

void                user_function                      (GtkRecentManager *recent_manager,
                                                        gpointer          user_data)           : Run First

Emitted when the current recently used resources manager changes its contents.

Since 2.10