migrating from eggrecent to gtkrecentchooser

emmanuele

<ebassigmail.com>

managing the recently used documents
displaying the recently used documents
advanced usage

since version 2.10, gtk+ provides a way of handling the recently used documents. it is similar to the code that has lived inside the libegg library and has been incorporated by many applications. the gtk+ version aims to completely replace that code, and offers many distinctive features that improve the registration and visualization of the recently used documents, such as:

better performances while reading and writing the list of recently used files
more meta-data available for each recent document, like the applications that have registered a document inside the list, the last time and the number of times the same application did register a document inside the list, an optional user readable name and description of the document
improved the ability to sort and filter the documents, also using custom sorting and filtering functions
new widgets for displaying the list, and better integration with current gtkfilechooser and gtkuimanager widgets

managing the recently used documents

gtkrecentmanager is used to manage the recently used documents. to create a new gtkrecentmanager, you simply call gtk_recent_manager_new(). like the eggrecentmodel inside eggrecent, the gtkrecentmanager loads the list of the recent documents and notifies you of changes inside the list.

usually, instead of creating a new gtkrecentmanager each time you need it, you'll want to use the gtk_recent_manager_get_default() function.

to add a document to the list, you can use gtk_recent_manager_add_item(), like:

        gtkrecentmanager *manager;

	manager = gtk_recent_manager_new ();

	if (!gtk_recent_manager_add_item (manager, document_uri))
	  {
	    /* warn about the error */
	  }
	
	g_object_unref (manager);

the gtk_recent_manager_add_item() function will try and guess some of the meta-data associated to a uri. if you know some of meta-data about the document yourself, set the desired fields of a gtkrecentdata structure and pass it to the gtk_recent_manager_add_full() function instead:

        gtkrecentmanager *manager;
        gtkrecentdata *recent_data;

	manager = gtk_recent_manager_new ();
	
	recent_data = g_new0 (gtkrecentdata, 1);
	/* the user visible name of the document (maybe its title); should
	 * be preferred when displaying the item into the list
	 */
        recent_data->display_name = document_name;
	
	/* the mime type is mandatory */
	recent_data->mime_type = document_mime_type;

	/* the name of the application that is registering the document
	 * (also mandatory); usually, the same name you used with
	 * the g_set_application_name () function.
	 */
	recent_data-&app_name = app_name;

	/* the command to open a file; the u string will be automagically
	 * expanded to the document's uri when getting the application's
	 * command line from the gtkrecentinfo object with
	 * gtk_recent_info_get_application_info ()
	 */
	recent_data-&app_exec = g_strjoin (" ", g_get_prgname (), "--open-file", "u", null);

	if (!gtk_recent_manager_add_full (manager, document_uri, recent_data))
	  {
	    /* warn about the error */
	  }

	g_free (recent_data->app_exec);
	g_free (recent_data);
	g_object_unref (manager);

getting the list of items is also similar to eggrecentmodel; the gtkrecentinfo data is allocated at look up time in order not to waste memory keeping it around, so you must remember to free the data inside the list and then the list itself when you are done using it:

        gtkrecentmanager *manager;
        glist *recent_items, *l;

	manager = gtk_recent_manager_get_default();

	recent_items = gtk_recent_manager_get_items (manager);
	for (l = recent_items; l != null; l = l->next)
	  {
	    gtkrecentinfo *recent_info = l->data;

	    do_something_with_the_item (recent_info);
	  }
	
	/* free everything and the list */
	g_list_foreach (recent_items, (gfunc) gtk_recent_info_unref, null);
	g_list_free (recent_items);

you can also look up a single item:

        gtkrecentinfo *recent_info;
	gerror *error = null;

	recent_info = gtk_recent_manager_lookup_item (manager, document_uri, &error);
	if (error)
	  {
	    display_error (error);

	    g_error_free (error);
	  }
	else
	  {
	    do_something_with_the_item (recent_info);

	    gtk_recent_info_unref (recent_info);
	  }

the gtkrecentinfo is a reference counted boxed type, and it holds all the meta-data of a recently used document, like its display name, its description, the list of each application that has registered the document or the list of groups to which the document belong.