Top |
Functions
Types and Values
struct | GtkRecentManager |
GtkRecentInfo | |
struct | GtkRecentData |
#define | GTK_RECENT_MANAGER_ERROR |
enum | GtkRecentManagerError |
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:
1 2 3 4 |
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()
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
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.
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.
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.
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.
gtk_recent_manager_add_item ()
gboolean gtk_recent_manager_add_item (GtkRecentManager *manager
,const char *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
.
gtk_recent_manager_add_full ()
gboolean gtk_recent_manager_add_full (GtkRecentManager *manager
,const char *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.
gtk_recent_manager_remove_item ()
gboolean gtk_recent_manager_remove_item (GtkRecentManager *manager
,const char *uri
,GError **error
);
Removes a resource pointed by uri
from the recently used resources
list handled by a recent manager.
gtk_recent_manager_lookup_item ()
GtkRecentInfo * gtk_recent_manager_lookup_item (GtkRecentManager *manager
,const char *uri
,GError **error
);
Searches for a URI inside the recently used resources list, and returns a GtkRecentInfo containing information 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]
gtk_recent_manager_has_item ()
gboolean gtk_recent_manager_has_item (GtkRecentManager *manager
,const char *uri
);
Checks whether there is a recently used resource registered
with uri
inside the recent manager.
gtk_recent_manager_move_item ()
gboolean gtk_recent_manager_move_item (GtkRecentManager *manager
,const char *uri
,const char *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.
gtk_recent_manager_get_items ()
GList *
gtk_recent_manager_get_items (GtkRecentManager *manager
);
Gets the list of recently used resources.
Returns
a list of
newly allocated GtkRecentInfo objects. Use
gtk_recent_info_unref()
on each item inside the list, and then
free the list itself using g_list_free()
.
[element-type GtkRecentInfo][transfer full]
gtk_recent_manager_purge_items ()
int gtk_recent_manager_purge_items (GtkRecentManager *manager
,GError **error
);
Purges every item from the recently used resources list.
gtk_recent_info_ref ()
GtkRecentInfo *
gtk_recent_info_ref (GtkRecentInfo *info
);
Increases the reference count of recent_info
by one.
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.
gtk_recent_info_get_uri ()
const char *
gtk_recent_info_get_uri (GtkRecentInfo *info
);
Gets the URI of the resource.
gtk_recent_info_get_display_name ()
const char *
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.
gtk_recent_info_get_description ()
const char *
gtk_recent_info_get_description (GtkRecentInfo *info
);
Gets the (short) description of the resource.
gtk_recent_info_get_mime_type ()
const char *
gtk_recent_info_get_mime_type (GtkRecentInfo *info
);
Gets the MIME type of the resource.
gtk_recent_info_get_added ()
GDateTime *
gtk_recent_info_get_added (GtkRecentInfo *info
);
Gets the the time when the resource was added to the recently used resources list.
gtk_recent_info_get_modified ()
GDateTime *
gtk_recent_info_get_modified (GtkRecentInfo *info
);
Gets the time when the meta-data for the resource was last modified.
gtk_recent_info_get_visited ()
GDateTime *
gtk_recent_info_get_visited (GtkRecentInfo *info
);
Gets the time when the meta-data for the resource was last visited.
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.
gtk_recent_info_get_application_info ()
gboolean gtk_recent_info_get_application_info (GtkRecentInfo *info
,const char *app_name
,const char **app_exec
,guint *count
,GDateTime **stamp
);
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.
Parameters
info |
||
app_name |
the name of the application that has registered this item |
|
app_exec |
return location for the string containing the command line. |
[transfer none][out] |
count |
return location for the number of times this item was registered. |
[out] |
stamp |
return location for the time this item was last registered for this application. |
[out][transfer none] |
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
gtk_recent_info_get_applications ()
char ** gtk_recent_info_get_applications (GtkRecentInfo *info
,gsize *length
);
Retrieves the list of applications that have registered this resource.
gtk_recent_info_last_application ()
char *
gtk_recent_info_last_application (GtkRecentInfo *info
);
Gets the name of the last application that have registered the
recently used resource represented by info
.
gtk_recent_info_has_application ()
gboolean gtk_recent_info_has_application (GtkRecentInfo *info
,const char *app_name
);
Checks whether an application registered this resource using app_name
.
gtk_recent_info_create_app_info ()
GAppInfo * gtk_recent_info_create_app_info (GtkRecentInfo *info
,const char *app_name
,GError **error
);
Creates a GAppInfo for the specified GtkRecentInfo
Parameters
info |
||
app_name |
the name of the application that should
be mapped to a GAppInfo; if |
[allow-none] |
error |
return location for a GError, or |
[allow-none] |
Returns
the newly created GAppInfo, or NULL
.
In case of error, error
will be set either with a
GTK_RECENT_MANAGER_ERROR
or a G_IO_ERROR
.
[nullable][transfer full]
gtk_recent_info_get_groups ()
char ** 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
.
gtk_recent_info_has_group ()
gboolean gtk_recent_info_has_group (GtkRecentInfo *info
,const char *group_name
);
Checks whether group_name
appears inside the groups
registered for the recently used item info
.
gtk_recent_info_get_gicon ()
GIcon *
gtk_recent_info_get_gicon (GtkRecentInfo *info
);
Retrieves the icon associated to the resource MIME type.
gtk_recent_info_get_short_name ()
char *
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”.
gtk_recent_info_get_uri_display ()
char *
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()
.
gtk_recent_info_get_age ()
int
gtk_recent_info_get_age (GtkRecentInfo *info
);
Gets the number of days elapsed since the last update
of the resource pointed by info
.
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.
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.
gtk_recent_info_match ()
gboolean gtk_recent_info_match (GtkRecentInfo *info_a
,GtkRecentInfo *info_b
);
Checks whether two GtkRecentInfo point to the same resource.
Types and Values
struct GtkRecentManager
struct GtkRecentManager;
GtkRecentManager contains only private data and should be accessed using the provided API.
GtkRecentInfo
typedef struct _GtkRecentInfo GtkRecentInfo;
GtkRecentInfo contains private data only, and should be accessed using the provided API.
GtkRecentInfo contains all the meta-data associated with an entry in the recently used files list.
struct GtkRecentData
struct GtkRecentData { char *display_name; char *description; char *mime_type; char *app_name; char *app_exec; char **groups; gboolean is_private; };
Meta-data to be passed to gtk_recent_manager_add_full()
when
registering a recently used resource.
Members
a UTF-8 encoded string, containing the name of the recently
used resource to be displayed, or |
||
a UTF-8 encoded string, containing a short description of
the resource, or |
||
the MIME type of the resource; |
||
the name of the application that is registering this recently used resource; |
||
command line used to launch this resource; may contain the “%f” and “%u” escape characters which will be expanded to the resource file path and URI respectively when the command line is retrieved; |
||
a vector of strings containing groups names;. |
[array zero-terminated=1] | |
whether this resource should be displayed only by the applications that have registered it or not. |
GTK_RECENT_MANAGER_ERROR
#define GTK_RECENT_MANAGER_ERROR (gtk_recent_manager_error_quark ())
The GError domain for GtkRecentManager errors.
enum GtkRecentManagerError
Error codes for GtkRecentManager operations
Members
the URI specified does not exists in the recently used resources list. |
||
the URI specified is not valid. |
||
the supplied string is not UTF-8 encoded. |
||
no application has registered the specified item. |
||
failure while reading the recently used resources file. |
||
failure while writing the recently used resources file. |
||
unspecified error. |
Property Details
The “filename”
property
“filename” char *
The full path to the file to be used to store and read the recently used resources list
Owner: GtkRecentManager
Flags: Read / Write / Construct Only
Default value: NULL
Signal Details
The “changed”
signal
void user_function (GtkRecentManager *recent_manager, gpointer user_data)
Emitted when the current recently used resources manager changes
its contents, either by calling gtk_recent_manager_add_item()
or
by another application.
Parameters
recent_manager |
the recent manager |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First