La classe RecentManager
La classe RecentManager joue le rôle de base de donnée centrale des fichiers récemment utilisés. Vous utilisez cette classe pour enregistrer de nouveaux fichiers, enlever des fichiers de la liste ou rechercher les fichiers récemment utilisés.
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().
XXI.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 :
Glib::RefPtr<Gtk::RecentManager> 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.
XXI.I.II. Examen des éléments de la liste des fichiers récents
Pour chercher les fichiers récemment utilisés, RecentManager dispose de plusieurs fonctions. Pour chercher un élément donné par son URI, utilisez la fonction lookup_item() qui renvoie un objet de la classe RecentInfo. Si l'URI indiqué n'existe pas dans la liste des fichiers récents, l'objet RecentInfo sera non valide. RecentInfo implémente operator bool() que vous pouvez utiliser pour tester la validité. Par exemple :
Gtk::RecentInfo info = recent_manager->lookup_item(uri);
if (info)
{
// l'élément a été trouvé
}Un objet RecentInfo est essentiellement un objet contenant toutes les métadonnées à propos d'un seul fichier récemment utilisé. Vous pouvez utiliser cet objet pour chercher l'une quelconque des propriétés listées ci-dessus. FIXME — ajouter les références croisées.
Si vous ne voulez pas rechercher un URI donné, mais au lieu de cela, voulez obtenir la liste de tous les éléments récemment utilisés, RecentManager dispose de la fonction get_items(). La valeur renvoyée peut être assignée à n'importe quel conteneur standard C++ (par exemple, std::vector, std::list, etc) ; elle contient la liste de tous les fichiers récemment utilisés jusqu'à la limite indiquée par l'utilisateur [FIXME : quelle est la limite par défaut ?]. Le code ci-après montre comment obtenir une liste des fichiers récemment utilisés :
std::vector<Gtk::RecentInfo> info_list = recent_manager->get_items();
La fonction membre set_limit() fixe le nombre limite d'éléments renvoyés ; get_limit() permet d'en prendre connaissance.
XXI.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().
En plus de modifier l'URI d'un fichier, vous pouvez enlever des éléments de la liste, soit un à un, soit tous à la fois. La première opération s'effectue avec remove_item(), la dernière avec 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.