gtk.RecentManager
Prev | The gtk Class Reference | Next

## gtk.RecentManager

gtk.RecentManager — manages recently used files (new in PyGTK 2.10)

## Synopsis

    class gtk.RecentManager(gobject.GObject):
        gtk.RecentManager()
        def set_screen(screen)
        def add_item(uri)
        def add_full(uri, recent_data)
        def remove_item(uri)
        def lookup_item(uri)
        def has_item(uri)
        def move_item(uri, new_uri)
        def set_limit(limit)
        def get_limit()
        def get_items()
        def purge_items()

    Functions

        def gtk.recent_manager_get_default()
        def gtk.recent_manager_get_for_screen(screen)

## Ancestry

    +-- gobject.GObject
      +-- gtk.RecentManager

## gtk.RecentManager Properties

"filename" | Read-Write-Construct Only | The full path to the file to be used to store and read the recently used resources list This property is available in GTK+ 2.10 and above.
"limit" | Read-Write | The maximum number of items to be returned by the `gtk.RecentManager.get_items()` function. This property is available in GTK+ 2.10 and above.
"size" | Read | The size of the recently used resources list. This property is available in GTK+ 2.10 and above.

## gtk.RecentManager Signal Prototypes

gobject.GObject Signal Prototypes

"changed | `def callback(`recent_manager`, `user_param1`, `...`)`

## Description

`gtk.RecentManager` 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.RecentManager` acts like a database of all the recently used files. You can create new `gtk.RecentManager` objects, but it is more efficient to use the standard recent manager for the `gtk.gdk.Screen` so that information 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:

      manager = gtk.recent_manager_get_default()
      manager.add_item(file_uri)

While looking up a recently used file is as simple as:

      manager = gtk.recent_manager_get_default()
      try:
        info = manager.lookup_item(file_uri)
      except gobject.GError:
        print "Could not find the file: ", file_uri

Recently used files are supported since GTK+ 2.10.

## Constructor

### gtk.RecentManager

        gtk.RecentManager()

Returns : | A newly created `gtk.RecentManager` object.

### Note

This constructor is available in PyGTK 2.10 and above.

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

`gtk.RecentManager` objects are expansive: be sure to create them only when needed. You should use the `gtk.recent_manager_get_for_screen`() or the `gtk.recent_manager_get_default`() functions instead.

## Methods

### gtk.RecentManager.set_screen

        def set_screen(screen)

`screen` : | a `gtk.gdk.Screen`

### Note

This method is available in PyGTK 2.10 and above.

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

### gtk.RecentManager.add_item

        def add_item(uri)

`uri` : | a valid URI
Returns : | `TRUE` if the new item was successfully added to the recently used resources list

### Note

This method is available in PyGTK 2.10 and above.

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

This method automatically retrieves some of the needed metadata and sets other metadata to common default values.

See the `gtk.RecentManager.add_full()` method if you want to explicitly define the metadata for the resource pointed by `uri`.

### gtk.RecentManager.add_full

        def add_full(uri, recent_data)

`uri` : | a valid URI
`recent_data` : | a dict containing metadata of the resource
Returns : | `TRUE` if the new item was successfully added to the recently used resources list.

### Note

This method is available in PyGTK 2.10 and above.

Adds a new resource, pointed by `uri`, into the recently used resources list, using the metadata specified inside the dict 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 dict, which must contain the MIME type of the resource pointed by the URI ("mime_type"), the name of the application that is registering the item ("app_name"), and a command line to be used when launching the item ("app_exec").

Optionally, the `recent_data` dict might contain a UTF-8 string to be used when viewing the item instead of the last component of the URI ("display_name"), a short description of the item ("description"), whether the item should be considered private - that is, should be displayed only by the applications that have registered it("is_private") or a list of the groups that the item belongs to ("groups").

### gtk.RecentManager.remove_item

        def remove_item(uri)

`uri` : | the URI of the item you wish to remove
Returns : | `TRUE` if the item pointed by `uri` has been successfully removed by the recently used resources list.

### Note

This method is available in PyGTK 2.10 and above.

Removes a resource pointed by `uri` from the recently used resources list handled by a recent manager. Raises the gobject.GError when an error occurs.

### gtk.RecentManager.lookup_item

        def lookup_item(uri)

`uri` : | a URI
Returns : | a `gtk.RecentInfo` object containing information about the resource pointed by `uri`, or `None` if the URI was not registered in the recently used resources list.

Searches for a URI inside the recently used resources list, and returns a `gtk.RecentInfo` object containing information about the resource like its MIME type, or its display name. Raises the gobject.GError when an error occurs.

### gtk.RecentManager.has_item

        def has_item(uri)

`uri` : | a URI
Returns : | `TRUE` if the resource was found.

### Note

This method is available in PyGTK 2.10 and above.

Checks whether there is a recently used resource registered with `uri`.

### gtk.RecentManager.move_item

        def move_item(uri, new_uri)

`uri` : | the URI of a recently used resource
`new_uri` : | the new URI of the recently used resource, or `None` to remove the item pointed by `uri` in the list
Returns : | `TRUE` on success.

### Note

This method is available in PyGTK 2.10 and above.

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. Raises the gobject.GError when an error occurs.

### gtk.RecentManager.set_limit

        def set_limit(limit)

`limit` : | the maximum number of items to return, or -1.

### Note

This method is available in PyGTK 2.10 and above.

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

### gtk.RecentManager.get_limit

        def get_limit()

Returns : | the number of items to return, or -1 for every item.

### Note

This method is available in PyGTK 2.10 and above.

Returns the maximum number of items that the `gtk.RecentManager.get_items()` method should return.

### gtk.RecentManager.get_items

        def get_items()

Returns : | a list of `gtk.RecentInfo` objects.

### Note

This method is available in PyGTK 2.10 and above.

Returns the list of recently used resources as `gtk.RecentInfo` objects.

### gtk.RecentManager.purge_items

        def purge_items()

Returns : | the number of items that have been removed from the recently used resources list.

### Note

This method is available in PyGTK 2.10 and above.

Purges every item from the recently used resources list. Raises the gobject.GError when an error occurs.

## Functions

### gtk.recent_manager_get_default

        def gtk.recent_manager_get_default()

Returns : | A unique `gtk.RecentManager` associated with the default screen. This recent manager is associated to the screen and can be used as long as the screen is open.

### Note

This function is available in PyGTK 2.10 and above.

Gets the recent manager for the default screen. See the `gtk.recent_manager_get_for_screen`() function.

### gtk.recent_manager_get_for_screen

        def gtk.recent_manager_get_for_screen(screen)

`screen` : | a `gtk.gdk.Screen`
Returns : | A unique `gtk.RecentManager` 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.

### Note

This function is available in PyGTK 2.10 and above.

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

## Signals

### The "changed" gtk.RecentManager Signal

        def callback(recent_manager, user_param1, ...)

`recent_manager` : | the recent manager
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.10 and above.

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

Prev | Up | Next
gtk.RecentInfo | Home | gtk.Requisition