Gnome Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# gnome-history

## Name

gnome-history -- Keeping track of recently used documents.

## Synopsis

    #include <gnome.h>

    struct      GnomeHistoryEntry;
    void        gnome_history_recently_used     (char *filename,
                                                 char *filetype,
                                                 char *creator,
                                                 char *desc);
    GList*      gnome_history_get_recently_used (void);
    void        gnome_history_free_recently_used_list
                                                (GList *alist);

## Description

These functions provide ways to store and retrieve a list of recently used documents. Applications need to call the gnome_history_recently_used() routine with the proper arguments to register a file as having been recently used. The creator field should be an action in the format supported by the "open" MIME type action (for example "program `f`", or "program") to re-open the document.

In the following example, the file `sales.gnumeric` will be added to the history of visited documents, the MIME type of the file is "application/x-gnumeric" and the program that will open this file is "gnumeric". Finally, note that the descriptive information is surrounded by the _() macro to have this item translated to the user's language at runtime.

    gnome_history_recently_used ("sales.gnumeric",
                                 "application/x-gnumeric",
                                 "gnumeric",
                                 _("Load spreadsheet"));

The following example would keep track of recent talks with a user:

    void record_talk (char *user)
    {
        char *message = g_strdup_printf (_("Talk to s", user);

        gnome_history_recently_used (user, "x-protocol/x-talk",
                                     "gtalk", message);
        g_free (message);
    }

To retrieve items from the history, you use the gnome_history_get_recently_used() function which returns a GList that contains GnomeHistoryEntry structures. To release this list, call the gnome_history_free_recently_used_list().

## Details

### struct GnomeHistoryEntry

    struct GnomeHistoryEntry
    {
    	char *filename;		/* Name of the visited file. */
    	char *filetype;		/* MIME type of the visited file.  */
    	char *creator;		/* What program created the file.  */
    	char *desc;		/* Description of what choosing this
    				   item would do.  This is some
    				   explanatory text that might be
    				   presented to the user.  */
    };

### gnome_history_recently_used ()

    void        gnome_history_recently_used     (char *filename,
                                                 char *filetype,
                                                 char *creator,
                                                 char *desc);

This routine is used to keep track of recently used file within the GNOME desktop. `filename` is the file that was recently used or just created.

`filename` : | the file name that was recently used.
`filetype` : | the mime-type of the file used.
`creator` : | application that created this.
`desc` : | textual description of the application creator

### gnome_history_get_recently_used ()

    GList*      gnome_history_get_recently_used (void);

Returns : | a GList with GnomeHistoryEntry structures with all of the recently used documents.

### gnome_history_free_recently_used_list ()

    void        gnome_history_free_recently_used_list
                                                (GList *alist);

Releases the list of recently used documents

`alist` : | a list with the recently used documents

<<< Previous Page | Home | Up | Next Page >>>
gnome-help | gnome-i18n