La classe 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.
Il est possible de créer une nouvelle classe RecentManager, mais il est plus vraisemblable que vous souhaiterez vous servir de celle par défaut. Vous obtiendrez une référence sur cette dernière avec get_default().
XX.I.I. Ajout d'éléments à la liste des fichiers récents
Pour ajouter un nouveau fichier à la liste des documents récents, dans le cas le plus simple, vous n'avez besoin que de fournir l'URI. Par exemple :
auto recent_manager = Gtk::RecentManager::get_default(); recent_manager->add_item(uri);
Si vous voulez enregistrer un fichier avec ses métadonnées, passez un paramètre RecentManager::Data à la fonction membre add_item(). Les métadonnées pouvant être définies sur un élément fichier donné sont :
- app_exec : la ligne de commande à utiliser pour atteindre cette ressource. Cette chaîne peut comporter les caractères d'échappement « f » et « u » ; ils seront respectivement développés sous forme du chemin d'accès à la ressource et de l'URI.
- app_name : le nom de l'application qui a enregistré la ressource.
- description : une courte description de la ressource sous forme d'une chaîne UTF-8.
- display_name : le nom de la ressource à utiliser pour l'affichage sous forme d'une chaîne UTF-8.
- groups : une liste des groupes associés à cet élément. Les groupes sont essentiellement des dénominations arbitraires associées à des ressources particulières. Ils peuvent être pensés en termes de « catégories » (telles que « courriel », « graphiques ») ou de marqueurs pour la ressource.
- is_private : indique si la ressource ne doit être visible que des applications qui l'ont enregistrée ou non.
- mime_type : le type MIME de la ressource.
En plus de la possibilité d'intégrer des éléments dans la liste, vous pouvez aussi faire une recherche d'éléments déjà présents dans la liste, les modifier ou les enlever.
XX.I.II. Examen des éléments de la liste des fichiers récents
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:
auto 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.
XX.I.III. Modification de la liste des fichiers récents
Vous pouvez parfois avoir besoin de modifier la liste des fichiers récents. Par exemple, si un fichier est déplacé ou renommé, vous pouvez mettre à jour l'emplacement ou le nom du fichier dans la liste des fichiers récents pour éviter de pointer vers quelque chose d'incorrect. Vous pouvez mettre à jour l'emplacement d'un élément avec 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().
Les fonctions move_item(), remove_item() et purge_items() n'ont aucun effet concret sur les fichiers auxquels les URI se référent ; elles ne font que modifier la liste.