Description
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:
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():
In order to retrieve the list of recently used files, you can use
gtk_recent_manager_get_items(), which returns a list of GtkRecentInfo-structs.
A GtkRecentManager is the model used to populate the contents of
one, or more GtkRecentChooser implementations.
Note that the maximum age of the recently used files list is
controllable through the “gtk-recent-files-max-age”
property.
Recently used files are supported since GTK+ 2.10.
Functions
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.
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
.
Returns
TRUE if the new item was successfully added
to the recently used resources list
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 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, 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 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.
Returns
TRUE if the new item was successfully added to the
recently used resources list, FALSE otherwise
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.
Returns
TRUE if the item pointed by uri
has been successfully
removed by the recently used resources list, and FALSE otherwise
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 GtkRecentInfo containing informations about the resource
like its MIME type, or its display name.
Returns
a GtkRecentInfo containing information
about the resource pointed by uri
, or NULL if the URI was
not registered in the recently used resources list. Free with
gtk_recent_info_unref().
[nullable]
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.
Returns
TRUE if the resource was found, FALSE otherwise
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_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.
Returns
the number of items that have been removed 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.
Returns
the recent info object with its reference count
increased 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.
Returns
the URI of the resource. The returned string is
owned by the recent manager, and should not be freed.
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.
Returns
the display name of the resource. The returned string
is owned by the recent manager, and should not be freed.
Since: 2.10
gtk_recent_info_get_description ()
const gchar *
gtk_recent_info_get_description (GtkRecentInfo *info);
Gets the (short) description of the resource.
Returns
the description of the resource. The returned string
is owned by the recent manager, and should not be freed.
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.
Returns
the MIME type of the resource. The returned string
is owned by the recent manager, and should not be freed.
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.
Returns
the number of seconds elapsed from system’s Epoch when
the resource was added to the list, or -1 on failure.
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 meta-data
for the resource was last modified.
Returns
the number of seconds elapsed from system’s Epoch when
the resource was last modified, or -1 on failure.
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 meta-data
for the resource was last visited.
Returns
the number of seconds elapsed from system’s Epoch when
the resource was last visited, or -1 on failure.
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.
Returns
TRUE if the private flag was found, FALSE otherwise
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.
Returns
TRUE if an application with app_name
has registered this
resource inside the recently used list, or FALSE otherwise. The
app_exec
string is owned by the GtkRecentInfo and should not be
modified or freed
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.
Returns
a newly allocated NULL-terminated array of strings.
Use g_strfreev() to free it.
[array length=length zero-terminated=1][transfer full]
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
.
Returns
an application name. Use g_free() to free it.
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
.
Returns
TRUE if an application with name app_name
was found,
FALSE otherwise
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.
Returns
a newly allocated NULL terminated array of strings.
Use g_strfreev() to free it.
[array length=length zero-terminated=1][transfer full]
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
.
Returns
TRUE if the group was found
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.
Returns
a GdkPixbuf containing the icon,
or NULL. Use g_object_unref() when finished using the icon.
[nullable][transfer full]
Since: 2.10
gtk_recent_info_get_gicon ()
GIcon *
gtk_recent_info_get_gicon (GtkRecentInfo *info);
Retrieves the icon associated to the resource MIME type.
Since: 2.22
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”.
Returns
A newly-allocated string in UTF-8 encoding
free it with g_free()
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().
Returns
a newly allocated UTF-8 string containing the
resource’s URI or NULL. Use g_free() when done using it.
[nullable]
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
.
Returns
a positive integer containing the number of days
elapsed since the time this resource was last modified
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.
Returns
TRUE if the resource is local
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.
Returns
TRUE if the resource exists
Since: 2.10
gtk_recent_info_match ()
gboolean
gtk_recent_info_match (GtkRecentInfo *info_a,
GtkRecentInfo *info_b);
Checks whether two GtkRecentInfo point to the same
resource.
Returns
TRUE if both GtkRecentInfo point to the same
resource, FALSE otherwise
Since: 2.10