Next: , Previous: GtkVRuler, Up: Top

147 GtkRecentManager

Managing Recently Used Files

147.1 Overview

<gtk-recent-manager> 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 <gtk-recent-manager> acts like a database of all the recently used files. You can create new <gtk-recent-manager> objects, but it is more efficient to use the standard recent manager for the <gdk-screen> 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);
     

     
     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.

147.2 Usage

— Class: <gtk-recent-manager>

Derives from <gobject>.

This class defines the following slots:

filename
The full path to the file to be used to store and read the list
limit
The maximum number of items to be returned by gtk_recent_manager_get_items()
size
The size of the recently used resources list
— Signal on <gtk-recent-manager>: changed

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

Since 2.10

— Class: <gtk-recent-info>

Derives from <gboxed>.

This class defines no direct slots.

— Function: gtk-recent-manager-new ⇒  (ret <gtk-recent-manager>)

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

<gtk-recent-manager> objects are expensive: be sure to create them only when needed. You should use the gtk-recent-manager-new-for-screen or the gtk-recent-manager-get-default functions instead.

ret
A newly created <gtk-recent-manager> object.

Since 2.10

— Function: gtk-recent-manager-get-default ⇒  (ret <gtk-recent-manager>)

Gets the recent manager for the default screen. See gtk-recent-manager-get-for-screen.

ret
A unique <gtk-recent-manager> associated with the default screen. This recent manager is associated with the screen and can be used as long as the screen is open. Do not ref or unref it.

Since 2.10

— Function: gtk-recent-manager-get-for-screen (screen <gdk-screen>) ⇒  (ret <gtk-recent-manager>)

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 <gdk-screen>
ret
A unique <gtk-recent-manager> 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

— Function: gtk-recent-manager-set-screen (self <gtk-recent-manager>) (screen <gdk-screen>)
— Method: set-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 <gtk-recent-manager>
screen
a <gdk-screen>

Since 2.10

— Function: gtk-recent-manager-add-item (self <gtk-recent-manager>) (uri mchars) ⇒  (ret bool)
— Method: add-item

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 <gtk-recent-manager>
uri
a valid URI
ret
‘#t’ if the new item was successfully added to the recently used resources list

Since 2.10

— Function: gtk-recent-manager-remove-item (self <gtk-recent-manager>) (uri mchars) ⇒  (ret bool)
— Method: remove-item

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

manager
a <gtk-recent-manager>
uri
the URI of the item you wish to remove
error
return location for a <g-error>, or ‘#f’
ret
‘#t’ if the item pointed by uri has been successfully removed by the recently used resources list, and ‘#f’ otherwise.

Since 2.10

— Function: gtk-recent-manager-lookup-item (self <gtk-recent-manager>) (uri mchars) ⇒  (ret <gtk-recent-info>)
— Method: lookup-item

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 <gtk-recent-manager>
uri
a URI
error
a return location for a <g-error>, or ‘#f’
ret
a <gtk-recent-info> structure containing information about the resource pointed by uri, or ‘#f’ if the URI was not registered in the recently used resources list. Free with gtk-recent-info-unref.

Since 2.10

— Function: gtk-recent-manager-has-item (self <gtk-recent-manager>) (uri mchars) ⇒  (ret bool)
— Method: has-item

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

manager
a <gtk-recent-manager>
uri
a URI
ret
‘#t’ if the resource was found, ‘#f’ otherwise.

Since 2.10

— Function: gtk-recent-manager-move-item (self <gtk-recent-manager>) (uri mchars) (new_uri mchars) ⇒  (ret bool)
— Method: move-item

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 <gtk-recent-manager>
uri
the URI of a recently used resource
new-uri
the new URI of the recently used resource, or ‘#f’ to remove the item pointed by uri in the list
error
a return location for a <g-error>, or ‘#f’
ret
‘#t’ on success.

Since 2.10

— Function: gtk-recent-manager-get-limit (self <gtk-recent-manager>) ⇒  (ret int)
— Method: get-limit

Gets the maximum number of items that the gtk-recent-manager-get-items function should return.

manager
a <gtk-recent-manager>
ret
the number of items to return, or -1 for every item.

Since 2.10

— Function: gtk-recent-manager-set-limit (self <gtk-recent-manager>) (limit int)
— Method: set-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 <gtk-recent-manager>
limit
the maximum number of items to return, or -1.

Since 2.10

— Function: gtk-recent-manager-get-items (self <gtk-recent-manager>) ⇒  (ret glist-of)
— Method: get-items

Gets the list of recently used resources.

manager
a <gtk-recent-manager>
ret
a list of newly allocated <gtk-recent-info> 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

— Function: gtk-recent-manager-purge-items (self <gtk-recent-manager>) ⇒  (ret int)
— Method: purge-items

Purges every item from the recently used resources list.

manager
a <gtk-recent-manager>
error
a return location for a <g-error>, or ‘#f’
ret
the number of items that have been removed from the recently used resources list.

Since 2.10

— Function: gtk-recent-info-get-uri (self <gtk-recent-info>) ⇒  (ret mchars)

Gets the URI of the resource.

info
a <gtk-recent-info>
ret
the URI of the resource. The returned string is owned by the recent manager, and should not be freed.

Since 2.10

— Function: gtk-recent-info-get-display-name (self <gtk-recent-info>) ⇒  (ret mchars)

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

info
a <gtk-recent-info>
ret
the display name of the resource. The returned string is owned by the recent manager, and should not be freed.

Since 2.10

— Function: gtk-recent-info-get-description (self <gtk-recent-info>) ⇒  (ret mchars)

Gets the (short) description of the resource.

info
a <gtk-recent-info>
ret
the description of the resource. The returned string is owned by the recent manager, and should not be freed.

Since 2.10

— Function: gtk-recent-info-get-mime-type (self <gtk-recent-info>) ⇒  (ret mchars)

Gets the MIME type of the resource.

info
a <gtk-recent-info>
ret
the MIME type of the resource. The returned string is owned by the recent manager, and should not be freed.

Since 2.10

— Function: gtk-recent-info-get-added (self <gtk-recent-info>) ⇒  (ret long)

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

info
a <gtk-recent-info>
ret
the number of seconds elapsed from system's Epoch when the resource was added to the list, or -1 on failure.

Since 2.10

— Function: gtk-recent-info-get-modified (self <gtk-recent-info>) ⇒  (ret long)

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

info
a <gtk-recent-info>
ret
the number of seconds elapsed from system's Epoch when the resource was last modified, or -1 on failure.

Since 2.10

— Function: gtk-recent-info-get-visited (self <gtk-recent-info>) ⇒  (ret long)

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

info
a <gtk-recent-info>
ret
the number of seconds elapsed from system's Epoch when the resource was last visited, or -1 on failure.

Since 2.10

— Function: gtk-recent-info-get-private-hint (self <gtk-recent-info>) ⇒  (ret bool)

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

info
a <gtk-recent-info>
ret
‘#t’ if the private flag was found, ‘#f’ otherwise.

Since 2.10

— Function: gtk-recent-info-last-application (self <gtk-recent-info>) ⇒  (ret mchars)

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

info
a <gtk-recent-info>
ret
an application name. Use g-free to free it.

Since 2.10

— Function: gtk-recent-info-has-group (self <gtk-recent-info>) (group_name mchars) ⇒  (ret bool)

Checks whether group-name appears inside the groups registered for the recently used item info.

info
a <gtk-recent-info>
group-name
name of a group
ret
‘#t’ if the group was found.

Since 2.10

— Function: gtk-recent-info-has-application (self <gtk-recent-info>) (app_name mchars) ⇒  (ret bool)

Checks whether an application registered this resource using app-name.

info
a <gtk-recent-info>
app-name
a string containing an application name
ret
‘#t’ if an application with name app-name was found, ‘#f’ otherwise.

Since 2.10

— Function: gtk-recent-info-get-icon (self <gtk-recent-info>) (size int) ⇒  (ret <gdk-pixbuf>)

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

info
a <gtk-recent-info>
size
the size of the icon in pixels
ret
a <gdk-pixbuf> containing the icon, or ‘#f’.

Since 2.10

— Function: gtk-recent-info-get-short-name (self <gtk-recent-info>) ⇒  (ret mchars)

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 <gtk-recent-info>
ret
A newly-allocated string in UTF-8 encoding; free it with g-free.

Since 2.10

— Function: gtk-recent-info-get-uri-display (self <gtk-recent-info>) ⇒  (ret mchars)

Gets a displayable version of the resource's URI.

info
a <gtk-recent-info>
ret
a UTF-8 string containing the resource's URI or ‘#f’

Since 2.10

— Function: gtk-recent-info-get-age (self <gtk-recent-info>) ⇒  (ret int)

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

info
a <gtk-recent-info>
ret
a positive integer containing the number of days elapsed since the time this resource was last modified.

Since 2.10

— Function: gtk-recent-info-is-local (self <gtk-recent-info>) ⇒  (ret bool)

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

info
a <gtk-recent-info>
ret
‘#t’ if the resource is local.

Since 2.10

— Function: gtk-recent-info-exists (self <gtk-recent-info>) ⇒  (ret bool)

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 <gtk-recent-info>
ret
‘#t’ if the resource exists

Since 2.10

— Function: gtk-recent-info-match (self <gtk-recent-info>) (info_b <gtk-recent-info>) ⇒  (ret bool)

Checks whether two <gtk-recent-info> structures point to the same resource.

info-a
a <gtk-recent-info>
info-b
a <gtk-recent-info>
ret
‘#t’ if both <gtk-recent-info> structures point to se same resource, ‘#f’ otherwise.

Since 2.10