:right-sidebar: True RecentManager =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: RecentManager(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` ``GtkRecentManager`` 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: .. code-block:: :dedent: 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 :obj:`~gi.repository.Gtk.RecentManager.lookup_item`: .. code-block:: :dedent: 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 :obj:`~gi.repository.Gtk.RecentManager.get_items`, which returns a list of :obj:`~gi.repository.Gtk.RecentInfo`. Note that the maximum age of the recently used files list is controllable through the :obj:`~gi.repository.Gtk.Settings.props.gtk_recent_files_max_age` property. Constructors ------------ .. rst-class:: interim-class .. class:: RecentManager :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.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 :obj:`~gi.repository.Gtk.RecentManager.signals.changed` signal each time something inside the list changes. ``GtkRecentManager`` objects are expensive: be sure to create them only when needed. You should use :obj:`~gi.repository.Gtk.RecentManager.get_default` instead. Methods ------- .. rst-class:: interim-class .. class:: RecentManager :no-index: .. method:: add_full(uri: str, recent_data: ~gi.repository.Gtk.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. :param uri: a valid URI :param recent_data: metadata of the resource .. method:: add_item(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 :obj:`~gi.repository.Gtk.RecentManager.add_full`. See :obj:`~gi.repository.Gtk.RecentManager.add_full` if you want to explicitly define the metadata for the resource pointed by ``uri``. :param uri: a valid URI .. method:: get_default() -> ~gi.repository.Gtk.RecentManager Gets a unique instance of ``GtkRecentManager`` that you can share in your application without caring about memory management. .. method:: get_items() -> list[~gi.repository.Gtk.RecentInfo] Gets the list of recently used resources. .. method:: has_item(uri: str) -> bool Checks whether there is a recently used resource registered with ``uri`` inside the recent manager. :param uri: a URI .. method:: lookup_item(uri: str) -> ~gi.repository.Gtk.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. :param uri: a URI .. method:: move_item(uri: str, new_uri: str | None = 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. :param uri: the URI of a recently used resource :param new_uri: the new URI of the recently used resource, or :const:`None` to remove the item pointed by ``uri`` in the list .. method:: purge_items() -> int Purges every item from the recently used resources list. .. method:: remove_item(uri: str) -> bool Removes a resource pointed by ``uri`` from the recently used resources list handled by a recent manager. :param uri: the URI of the item you wish to remove Properties ---------- .. rst-class:: interim-class .. class:: RecentManager :no-index: .. attribute:: props.filename :type: str The full path to the file to be used to store and read the recently used resources list .. attribute:: props.size :type: int The size of the recently used resources list. Signals ------- .. rst-class:: interim-class .. class:: RecentManager.signals :no-index: .. method:: changed() -> None Emitted when the current recently used resources manager changes its contents. This can happen either by calling :obj:`~gi.repository.Gtk.RecentManager.add_item` or by another application. Virtual Methods --------------- .. rst-class:: interim-class .. class:: RecentManager :no-index: .. method:: do_changed() -> None Fields ------ .. rst-class:: interim-class .. class:: RecentManager :no-index: .. attribute:: parent_instance .. attribute:: priv