Chapter 21. Recently Used Documents

# Chapter 21. Recently Used Documents

gtkmm provides an easy way to manage recently used documents. The classes involved in implementing this functionality are `RecentManager`, `RecentChooserDialog`, `RecentChooserMenu`, `RecentChooserWidget`, and `RecentFilter`.

Each item in the list of recently used files is identified by its URI, and can have associated metadata. The metadata can be used to specify how the file should be displayed, a description of the file, its mime type, which application registered it, whether it's private to the registering application, and several other things.

## RecentManager

`RecentManager` acts as a database of recently used files. You use this class to register new files, remove files from the list, or look up recently used files. There is one list of recently used files per user.

You can create a new `RecentManager`, but you'll most likely just want to use the default one. You can get a reference to the default `RecentManager` with `get_default()`.

`RecentManager` is the model of a model-view pattern, where the view is a class that implements the `RecentChooser` interface.

### Adding Items to the List of Recent Files

To add a new file to the list of recent documents, in the simplest case, you only need to provide the URI. For example:

    Glib::RefPtr<Gtk::RecentManager> recent_manager = Gtk::RecentManager::get_default();
    recent_manager->add_item(uri);

If you want to register a file with metadata, you can pass a `RecentManager::Data` parameter to `add_item()`. The metadata that can be set on a particular file item is as follows:

- `app_exec`: The command line to be used to launch this resource. This string may contain the "f" and "u" escape characters which will be expanded to the resource file path and URI respectively

- `app_name`: The name of the application that registered the resource

- `description`: A short description of the resource as a UTF-8 encoded string

- `display_name`: The name of the resource to be used for display as a UTF-8 encoded string

- `groups`: A list of groups associated with this item. Groups are essentially arbitrary strings associated with a particular resource. They can be thought of as 'categories' (such as "email", "graphics", etc) or tags for the resource.

- `is_private`: Whether this resource should be visible only to applications that have registered it or not

- `mime_type`: The MIME type of the resource

In addition to adding items to the list, you can also look up items from the list and modify or remove items.

### Looking up Items in the List of Recent Files

To look up recently used files, `RecentManager` provides several functions. To look up a specific item by its URI, you can use the `lookup_item()` function, which will return a `RecentInfo` class. If the specified URI did not exist in the list of recent files, `lookup_item()` throws a `RecentManagerError` exception. For example:

    Glib::RefPtr<Gtk::RecentInfo> info;
    try
    {
      info = recent_manager->lookup_item(uri);
    }
    catch(const Gtk::RecentManagerError& ex)
    {
      std::cerr << "RecentManagerError: " << ex.what() << std::endl;
    }
    if (info)
    {
      // item was found
    }

A `RecentInfo` object is essentially an object containing all of the metadata about a single recently-used file. You can use this object to look up any of the properties listed above.

If you don't want to look for a specific URI, but instead want to get a list of all recently used items, `RecentManager` provides the `get_items()` function. The return value of this function is a `std::vector` of all recently used files. The following code demonstrates how you might get a list of recently used files:

    std::vector< Glib::RefPtr<Gtk::RecentInfo> > info_list = recent_manager->get_items();

The maximum age of items in the recently used files list can be set with `Gtk::Settings::property_gtk_recent_files_max_age()`. Default value: 30 days.

### Modifying the List of Recent Files

There may be times when you need to modify the list of recent files. For instance, if a file is moved or renamed, you may need to update the file's location in the recent files list so that it doesn't point to an incorrect location. You can update an item's location by using `move_item()`.

In addition to changing a file's URI, you can also remove items from the list, either one at a time or by clearing them all at once. The former is accomplished with `remove_item()`, the latter with `purge_items()`.

| Note
The functions `move_item()`, `remove_item()` and `purge_items()` have no effect on the actual files that are referred to by the URIs, they only modify the list of recent files.

Example |  | RecentChooser