![]() |
![]() |
![]() |
GTK+ Reference Manual | ![]() |
---|---|---|---|---|
#include <gtk/gtk.h> GtkRecentManager; GtkRecentInfo; GtkRecentData; #define GTK_RECENT_MANAGER_ERROR enum GtkRecentManagerError; GtkRecentManager* gtk_recent_manager_new (void); GtkRecentManager* gtk_recent_manager_get_default (void); GtkRecentManager* gtk_recent_manager_get_for_screen (GdkScreen *screen);void gtk_recent_manager_set_screen (GtkRecentManager *manager,GdkScreen *screen);gboolean gtk_recent_manager_add_item (GtkRecentManager *manager, constgchar *uri);gboolean gtk_recent_manager_add_full (GtkRecentManager *manager, constgchar *uri, const GtkRecentData *recent_data);gboolean gtk_recent_manager_remove_item (GtkRecentManager *manager, constgchar *uri,GError **error); GtkRecentInfo* gtk_recent_manager_lookup_item (GtkRecentManager *manager, constgchar *uri,GError **error);gboolean gtk_recent_manager_has_item (GtkRecentManager *manager, constgchar *uri);gboolean gtk_recent_manager_move_item (GtkRecentManager *manager, constgchar *uri, constgchar *new_uri,GError **error);gint gtk_recent_manager_get_limit (GtkRecentManager *manager);void gtk_recent_manager_set_limit (GtkRecentManager *manager,gint limit);GList * gtk_recent_manager_get_items (GtkRecentManager *manager);gint gtk_recent_manager_purge_items (GtkRecentManager *manager,GError **error); GtkRecentInfo* gtk_recent_info_ref (GtkRecentInfo *info);void gtk_recent_info_unref (GtkRecentInfo *info); constgchar * gtk_recent_info_get_uri (GtkRecentInfo *info); constgchar * gtk_recent_info_get_display_name (GtkRecentInfo *info); constgchar * gtk_recent_info_get_description (GtkRecentInfo *info); constgchar * gtk_recent_info_get_mime_type (GtkRecentInfo *info);time_t gtk_recent_info_get_added (GtkRecentInfo *info);time_t gtk_recent_info_get_modified (GtkRecentInfo *info);time_t gtk_recent_info_get_visited (GtkRecentInfo *info);gboolean gtk_recent_info_get_private_hint (GtkRecentInfo *info);gboolean gtk_recent_info_get_application_info (GtkRecentInfo *info, constgchar *app_name,gchar **app_exec,guint *count,time_t *time_);gchar ** gtk_recent_info_get_applications (GtkRecentInfo *info,gsize *length);gchar * gtk_recent_info_last_application (GtkRecentInfo *info);gchar ** gtk_recent_info_get_groups (GtkRecentInfo *info,gsize *length);gboolean gtk_recent_info_has_group (GtkRecentInfo *info, constgchar *group_name);gboolean gtk_recent_info_has_application (GtkRecentInfo *info, constgchar *app_name);GdkPixbuf * gtk_recent_info_get_icon (GtkRecentInfo *info,gint size);gchar * gtk_recent_info_get_short_name (GtkRecentInfo *info);gchar * gtk_recent_info_get_uri_display (GtkRecentInfo *info);gint gtk_recent_info_get_age (GtkRecentInfo *info);gboolean gtk_recent_info_is_local (GtkRecentInfo *info);gboolean gtk_recent_info_exists (GtkRecentInfo *info);gboolean gtk_recent_info_match (GtkRecentInfo *info_a, GtkRecentInfo *info_b);
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
GtkRecentManager *manager;
manager = gtk_recent_manager_get_default()
;
gtk_recent_manager_add_item (manager, file_uri);
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 */
g_object_unref (info);
}
Recently used files are supported since GTK+ 2.10.
typedef struct { } 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.
typedef struct _GtkRecentInfo GtkRecentInfo;
Contains informations found when looking up an entry of the recently used files list.
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.
Meta-data passed to gtk_recent_manager_add_full()
. You should
use GtkRecentData 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 ; |
a UTF-8 encoded string, containing the name of the recently
used resource to be displayed, or NULL |
description ; |
a UTF-8 encoded string, containing a short description of
the resource, or NULL |
mime_type ; |
the MIME type of the resource; |
app_name ; |
the name of the application that is registering this recently used resource; |
app_exec ; |
command line used to launch this resource; may contain the
"f u |
groups ; |
a vector of strings containing groups names; |
is_private ; |
whether this resource should be displayed only by the applications that have registered it or not. |
#define GTK_RECENT_MANAGER_ERROR (gtk_recent_manager_error_quark ())
The
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
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 expansive: be sure to create them only when
needed. You should use the gtk_recent_manager_new_for_screen()
gtk_recent_manager_get_default()
functions instead.
Returns : | A newly created GtkRecentManager object. |
Since 2.10
GtkRecentManager* gtk_recent_manager_get_default (void);
Gets the recent manager for the default screen. See
gtk_recent_manager_get_for_screen()
.
Returns : | A unique GtkRecentManager associated with the default screen. This recent manager is associated to the screen and can be used as long as the screen is open. Do no ref or unref it. |
Since 2.10
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.
screen : |
a |
Returns : | A unique GtkRecentManager 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. |
Since 2.10
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.
manager : |
a GtkRecentManager |
screen : |
a |
Since 2.10
gboolean gtk_recent_manager_add_item (GtkRecentManager *manager, constgchar *uri);
Adds a new resource, pointed by 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 gtk_recent_manager_add_full()
.
See gtk_recent_manager_add_full()
if you want to explicitely
define the metadata for the resource pointed by uri
.
manager : |
a GtkRecentManager |
uri : |
a valid URI |
Returns : | TRUE |
Since 2.10
gboolean gtk_recent_manager_add_full (GtkRecentManager *manager, constgchar *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.
manager : |
a GtkRecentManager |
uri : |
a valid URI |
recent_data : |
metadata of the resource |
Returns : | TRUE FALSE |
Since 2.10
gboolean gtk_recent_manager_remove_item (GtkRecentManager *manager, constgchar *uri,GError **error);
Removes a resource pointed by uri
from the recently used resources
list handled by a recent manager.
manager : |
a GtkRecentManager |
uri : |
the URI of the item you wish to remove |
error : |
return location for a NULL |
Returns : | TRUE uri has been successfully
removed by the recently used resources list, and FALSE |
Since 2.10
GtkRecentInfo* gtk_recent_manager_lookup_item (GtkRecentManager *manager, constgchar *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.
manager : |
a GtkRecentManager |
uri : |
a URI |
error : |
a return location for a NULL |
Returns : | a GtkRecentInfo structure containing information
about the resource pointed by uri , or NULL gtk_recent_info_unref() .
|
gboolean gtk_recent_manager_has_item (GtkRecentManager *manager, constgchar *uri);
Checks whether there is a recently used resource registered
with uri
inside the recent manager.
manager : |
a GtkRecentManager |
uri : |
a URI |
Returns : | TRUE FALSE |
Since 2.10
gboolean gtk_recent_manager_move_item (GtkRecentManager *manager, constgchar *uri, constgchar *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.
manager : |
a GtkRecentManager |
uri : |
the URI of a recently used resource |
new_uri : |
the new URI of the recently used resource, or NULL uri in the list
|
error : |
a return location for a NULL |
Returns : | TRUE |
Since 2.10
gint gtk_recent_manager_get_limit (GtkRecentManager *manager);
Gets the maximum number of items that the gtk_recent_manager_get_items()
function should return.
manager : |
a GtkRecentManager |
Returns : | the number of items to return, or -1 for every item. |
Since 2.10
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.
manager : |
a GtkRecentManager |
limit : |
the maximum number of items to return, or -1. |
Since 2.10
GList * gtk_recent_manager_get_items (GtkRecentManager *manager);
Gets the list of recently used resources.
manager : |
a GtkRecentManager |
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() |
Since 2.10
gint gtk_recent_manager_purge_items (GtkRecentManager *manager,GError **error);
Purges every item from the recently used resources list.
manager : |
a GtkRecentManager |
error : |
a return location for a NULL |
Returns : | the number of items that have been removed from the recently used resources list. |
Since 2.10
GtkRecentInfo* gtk_recent_info_ref (GtkRecentInfo *info);
Increases the reference count of recent_info
by one.
info : |
a GtkRecentInfo |
Returns : | the recent info object with its reference count increased by one. |
Since 2.10
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.
info : |
a GtkRecentInfo |
Since 2.10
constgchar * gtk_recent_info_get_uri (GtkRecentInfo *info);
Gets the URI of the resource.
info : |
a GtkRecentInfo |
Returns : | the URI of the resource. The returned string is owned by the recent manager, and should not be freed. |
Since 2.10
constgchar * 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.
info : |
a GtkRecentInfo |
Returns : | the display name of the resource. The returned string is owned by the recent manager, and should not be freed. |
Since 2.10
constgchar * gtk_recent_info_get_description (GtkRecentInfo *info);
Gets the (short) description of the resource.
info : |
a GtkRecentInfo |
Returns : | the description of the resource. The returned string is owned by the recent manager, and should not be freed. |
Since 2.10
constgchar * gtk_recent_info_get_mime_type (GtkRecentInfo *info);
Gets the MIME type of the resource.
info : |
a GtkRecentInfo |
Returns : | the MIME type of the resource. The returned string is owned by the recent manager, and should not be freed. |
Since 2.10
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.
info : |
a GtkRecentInfo |
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
time_t gtk_recent_info_get_modified (GtkRecentInfo *info);
Gets the timestamp (seconds from system's Epoch) when the resource was last modified.
info : |
a GtkRecentInfo |
Returns : | the number of seconds elapsed from system's Epoch when the resource was last modified, or -1 on failure. |
Since 2.10
time_t gtk_recent_info_get_visited (GtkRecentInfo *info);
Gets the timestamp (seconds from system's Epoch) when the resource was last visited.
info : |
a GtkRecentInfo |
Returns : | the number of seconds elapsed from system's Epoch when the resource was last visited, or -1 on failure. |
Since 2.10
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
info : |
a GtkRecentInfo |
Returns : | TRUE FALSE |
Since 2.10
gboolean gtk_recent_info_get_application_info (GtkRecentInfo *info, constgchar *app_name,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.
info : |
a GtkRecentInfo |
app_name : |
the name of the application that has registered this item |
app_exec : |
return location for the string containing the command line |
count : |
return location for the number of times this item was registered |
time_ : |
return location for the timestamp this item was last registered for this application |
Returns : | TRUE app_name has registered this
resource inside the recently used list, or FALSE g_free() |
Since 2.10
gchar ** gtk_recent_info_get_applications (GtkRecentInfo *info,gsize *length);
Retrieves the list of applications that have registered this resource.
info : |
a GtkRecentInfo |
length : |
return location for the length of the returned list, or NULL |
Returns : | a newly allocated NULL g_strfreev() |
Since 2.10
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
.
info : |
a GtkRecentInfo |
Returns : | an application name. Use g_free() |
Since 2.10
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
NULL
info : |
a GtkRecentInfo |
length : |
return location for the number of groups returned, or NULL |
Returns : | a newly allocated NULL g_strfreev() |
Since 2.10
gboolean gtk_recent_info_has_group (GtkRecentInfo *info, constgchar *group_name);
Checks whether group_name
appears inside the groups registered for the
recently used item info
.
info : |
a GtkRecentInfo |
group_name : |
name of a group |
Returns : | TRUE |
Since 2.10
gboolean gtk_recent_info_has_application (GtkRecentInfo *info, constgchar *app_name);
Checks whether an application registered this resource using app_name
.
info : |
a GtkRecentInfo |
app_name : |
a string containing an application name |
Returns : | TRUE app_name was found,
FALSE |
Since 2.10
GdkPixbuf * gtk_recent_info_get_icon (GtkRecentInfo *info,gint size);
Retrieves the icon of size size
associated to the resource MIME type.
info : |
a GtkRecentInfo |
size : |
the size of the icon in pixels |
Returns : | a NULL |
Since 2.10
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".
info : |
an GtkRecentInfo |
Returns : | A newly-allocated string in UTF-8 encoding; free it with
g_free() |
Since 2.10
gchar * gtk_recent_info_get_uri_display (GtkRecentInfo *info);
Gets a displayable version of the resource's URI.
info : |
a GtkRecentInfo |
Returns : | a UTF-8 string containing the resource's URI or NULL |
Since 2.10
gint gtk_recent_info_get_age (GtkRecentInfo *info);
Gets the number of days elapsed since the last update of the resource
pointed by info
.
info : |
a GtkRecentInfo |
Returns : | a positive integer containing the number of days elapsed since the time this resource was last modified. |
Since 2.10
gboolean gtk_recent_info_is_local (GtkRecentInfo *info);
Checks whether the resource is local or not by looking at the scheme of its URI.
info : |
a GtkRecentInfo |
Returns : | TRUE |
Since 2.10
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.
info : |
a GtkRecentInfo |
Returns : | TRUE |
Since 2.10
gboolean gtk_recent_info_match (GtkRecentInfo *info_a, GtkRecentInfo *info_b);
Checks whether two GtkRecentInfo structures point to the same resource.
info_a : |
a GtkRecentInfo |
info_b : |
a GtkRecentInfo |
Returns : | TRUE FALSE |
Since 2.10