How does one add an item to GTK's “recently us

I'm trying to add to the "recently used" files list from Python 3 on Ubuntu.

I am able to successfully read the recently used file list like this:

from gi.repository import Gtk
recent_mgr = Gtk.RecentManager.get_default()
for item in recent_mgr.get_items():
    print(item.get_uri())

This prints out the same list of files I see when I look at "Recent" in Nautilus, or look at the "Recently Used" place in the file dialog of apps like GIMP.

However, when I tried adding an item like this (where /home/laurence/foo/bar.txt is an existing text file)...

recent_mgr.add_item('file:///home/laurence/foo/bar.txt')

...the file does not show up in the Recent section of Nautilus or in file dialogs. It doesn't even show up in the results returned by get_items().

How can I add a file to GTK's recently used file list from Python?

A Gtk.RecentManager needs to emit the changed signal for the update to be written in a private attribute of the C++ class. To use a RecentManager object in an application, you need to start the event loop by calling Gtk.main:

from gi.repository import Gtk

recent_mgr = Gtk.RecentManager.get_default()
uri = r'file:/path/to/my/file'
recent_mgr.add_item(uri)
Gtk.main()

If you don't call Gtk.main(), the changed signal is not emitted and nothing happens.

To answer @andlabs query, the reason why RecentManager.add_item returns a boolean is because the g_file_query_info_async function is called. The callback function gtk_recent_manager_add_item_query_info then gathers the mimetype, application name and command into a GtkRecentData struct and finally calls gtk_recent_manager_add_full. The source is here.

If anything goes wrong, it is well after add_item has finished, so the method just returns True if the object it is called from is a RecentManager and if the uri is not NULL; and False otherwise.

The documentation is inaccurate in saying:

Returns TRUE if the new item was successfully added to the recently used resources list

as returning TRUE only means that an asynchronous function was called to deal with the addition of a new item.

As suggested by Laurence Gonsalves, the following runs pseudo-synchronously:

from gi.repository import Gtk, GObject

recent_mgr = Gtk.RecentManager.get_default()
uri = r'file:/path/to/my/file'
recent_mgr.add_item(uri)
GObject.idle_add(Gtk.main_quit)
Gtk.main()