Gtk.RecentManager¶

class — extends GObject.Object

Manages and looks 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.

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:

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 RecentManager.lookup_item:

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 RecentManager.get_items, which returns a list of RecentInfo.

Note that the maximum age of the recently used files list is controllable through the Settings.gtk-recent-files-max-age property.

Constructors¶

new¶

@classmethod
def new(cls) -> RecentManager

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 RecentManager.changed signal each time something inside the list changes.

GtkRecentManager objects are expensive: be sure to create them only when needed. You should use RecentManager.get_default instead.

Methods¶

add_full¶

def add_full(self, uri: str, recent_data: RecentData) -> bool

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.

Parameters:

uri — a valid URI
recent_data — metadata of the resource

add_item¶

def add_item(self, uri: str) -> bool

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 RecentManager.add_full.

See RecentManager.add_full if you want to explicitly define the metadata for the resource pointed by uri.

Parameters:

uri — a valid URI

get_items¶

def get_items(self) -> list[RecentInfo]

Gets the list of recently used resources.

has_item¶

def has_item(self, uri: str) -> bool

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

Parameters:

uri — a URI

lookup_item¶

def lookup_item(self, uri: str) -> RecentInfo | None

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.

Parameters:

uri — a URI

move_item¶

def move_item(self, uri: str, new_uri: str | None = ...) -> bool

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.

Parameters:

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

purge_items¶

def purge_items(self) -> int

Purges every item from the recently used resources list.

remove_item¶

def remove_item(self, uri: str) -> bool

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

Parameters:

uri — the URI of the item you wish to remove

Static functions¶

get_default¶

@staticmethod
def get_default() -> RecentManager

Gets a unique instance of GtkRecentManager that you can share in your application without caring about memory management.

Virtual methods¶

do_changed¶

def do_changed(self) -> None

Properties¶

filename¶

filename: str  # read/write

The full path to the file to be used to store and read the recently used resources list

size¶

size: int  # read-only

The size of the recently used resources list.

Signals¶

changed¶

def on_changed(self) -> None: ...

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

This can happen either by calling RecentManager.add_item or by another application.