## GtkRecentChooser

GtkRecentChooser — Interface implemented by GtkRecentChooserWidget, GtkRecentChooserMenu and GtkRecentChooserDialog

## Synopsis

    #include <gtk/gtk.h>

                GtkRecentChooser;
                GtkRecentChooserIface;
    #define     GTK_RECENT_CHOOSER_ERROR
    enum        GtkRecentChooserError;
    void        gtk_recent_chooser_set_show_private
                                                (GtkRecentChooser *chooser,
                                                 gboolean show_private);
    gboolean    gtk_recent_chooser_get_show_private
                                                (GtkRecentChooser *chooser);
    void        gtk_recent_chooser_set_show_not_found
                                                (GtkRecentChooser *chooser,
                                                 gboolean show_not_found);
    gboolean    gtk_recent_chooser_get_show_not_found
                                                (GtkRecentChooser *chooser);
    void        gtk_recent_chooser_set_show_icons
                                                (GtkRecentChooser *chooser,
                                                 gboolean show_icons);
    gboolean    gtk_recent_chooser_get_show_icons
                                                (GtkRecentChooser *chooser);
    void        gtk_recent_chooser_set_select_multiple
                                                (GtkRecentChooser *chooser,
                                                 gboolean select_multiple);
    gboolean    gtk_recent_chooser_get_select_multiple
                                                (GtkRecentChooser *chooser);
    void        gtk_recent_chooser_set_local_only
                                                (GtkRecentChooser *chooser,
                                                 gboolean local_only);
    gboolean    gtk_recent_chooser_get_local_only
                                                (GtkRecentChooser *chooser);
    void        gtk_recent_chooser_set_limit    (GtkRecentChooser *chooser,
                                                 gint limit);
    gint        gtk_recent_chooser_get_limit    (GtkRecentChooser *chooser);
    void        gtk_recent_chooser_set_show_tips
                                                (GtkRecentChooser *chooser,
                                                 gboolean show_tips);
    gboolean    gtk_recent_chooser_get_show_tips
                                                (GtkRecentChooser *chooser);
    void        gtk_recent_chooser_set_show_numbers
                                                (GtkRecentChooser *chooser,
                                                 gboolean show_numbers);
    gboolean    gtk_recent_chooser_get_show_numbers
                                                (GtkRecentChooser *chooser);
    enum        GtkRecentSortType;
    void        gtk_recent_chooser_set_sort_type
                                                (GtkRecentChooser *chooser,
                                                 GtkRecentSortType sort_type);
    GtkRecentSortType gtk_recent_chooser_get_sort_type
                                                (GtkRecentChooser *chooser);
    gint        (*GtkRecentSortFunc)            (GtkRecentInfo *a,
                                                 GtkRecentInfo *b,
                                                 gpointer user_data);
    void        gtk_recent_chooser_set_sort_func
                                                (GtkRecentChooser *chooser,
                                                 GtkRecentSortFunc sort_func,
                                                 gpointer sort_data,
                                                 GDestroyNotify data_destroy);
    gboolean    gtk_recent_chooser_set_current_uri
                                                (GtkRecentChooser *chooser,
                                                 const gchar *uri,
                                                 GError **error);
    gchar*      gtk_recent_chooser_get_current_uri
                                                (GtkRecentChooser *chooser);
    GtkRecentInfo* gtk_recent_chooser_get_current_item
                                                (GtkRecentChooser *chooser);
    gboolean    gtk_recent_chooser_select_uri   (GtkRecentChooser *chooser,
                                                 const gchar *uri,
                                                 GError **error);
    void        gtk_recent_chooser_unselect_uri (GtkRecentChooser *chooser,
                                                 const gchar *uri);
    void        gtk_recent_chooser_select_all   (GtkRecentChooser *chooser);
    void        gtk_recent_chooser_unselect_all (GtkRecentChooser *chooser);
    GList*      gtk_recent_chooser_get_items    (GtkRecentChooser *chooser);
    gchar**     gtk_recent_chooser_get_uris     (GtkRecentChooser *chooser,
                                                 gsize *length);
    void        gtk_recent_chooser_add_filter   (GtkRecentChooser *chooser,
                                                 GtkRecentFilter *filter);
    void        gtk_recent_chooser_remove_filter
                                                (GtkRecentChooser *chooser,
                                                 GtkRecentFilter *filter);
    GSList*     gtk_recent_chooser_list_filters (GtkRecentChooser *chooser);
    void        gtk_recent_chooser_set_filter   (GtkRecentChooser *chooser,
                                                 GtkRecentFilter *filter);
    GtkRecentFilter* gtk_recent_chooser_get_filter
                                                (GtkRecentChooser *chooser);

## Object Hierarchy

      GInterface
       +----GtkRecentChooser

## Prerequisites

GtkRecentChooser requires GtkObject.

## Known Implementations

GtkRecentChooser is implemented by GtkRecentChooserDialog, GtkRecentChooserWidget and GtkRecentChooserMenu.

## Properties

      "filter"               GtkRecentFilter       : Read / Write
      "limit"                gint                  : Read / Write
      "local-only"           gboolean              : Read / Write
      "recent-manager"       GtkRecentManager      : Write / Construct Only
      "select-multiple"      gboolean              : Read / Write
      "show-icons"           gboolean              : Read / Write
      "show-not-found"       gboolean              : Read / Write
      "show-private"         gboolean              : Read / Write
      "show-tips"            gboolean              : Read / Write
      "sort-type"            GtkRecentSortType     : Read / Write

## Signals

    "item-activated"
                void        user_function      (GtkRecentChooser *chooser,
                                                gpointer          user_data)      : Run last
    "selection-changed"
                void        user_function      (GtkRecentChooser *chooser,
                                                gpointer          user_data)      : Run last

## Description

GtkRecentChooser is an interface that can be implemented by widgets displaying the list of recently used files. In GTK+, the main objects that implement this interface are GtkRecentChooserWidget, GtkRecentChooserDialog and GtkRecentChooserMenu.

Recently used files are supported since GTK+ 2.10.

## Details

### GtkRecentChooser

    typedef struct _GtkRecentChooser GtkRecentChooser;

### GtkRecentChooserIface

    typedef struct {
      GTypeInterface base_iface;

      /*
       * Methods
       */
      gboolean          (* set_current_uri)    (GtkRecentChooser  *chooser,
      					    const gchar       *uri,
      					    GError           **error);
      gchar *           (* get_current_uri)    (GtkRecentChooser  *chooser);
      gboolean          (* select_uri)         (GtkRecentChooser  *chooser,
      					    const gchar       *uri,
      					    GError           **error);
      void              (* unselect_uri)       (GtkRecentChooser  *chooser,
                                                const gchar       *uri);
      void              (* select_all)         (GtkRecentChooser  *chooser);
      void              (* unselect_all)       (GtkRecentChooser  *chooser);
      GList *           (* get_items)          (GtkRecentChooser  *chooser);
      GtkRecentManager *(* get_recent_manager) (GtkRecentChooser  *chooser);
      void              (* add_filter)         (GtkRecentChooser  *chooser,
      					    GtkRecentFilter   *filter);
      void              (* remove_filter)      (GtkRecentChooser  *chooser,
      					    GtkRecentFilter   *filter);
      GSList *          (* list_filters)       (GtkRecentChooser  *chooser);
      void              (* set_sort_func)      (GtkRecentChooser  *chooser,
      					    GtkRecentSortFunc  sort_func,
      					    gpointer           data,
      					    GDestroyNotify     destroy);

      /*
       * Signals
       */
      void		    (* item_activated)     (GtkRecentChooser  *chooser);
      void		    (* selection_changed)  (GtkRecentChooser  *chooser);
    } GtkRecentChooserIface;

### GTK_RECENT_CHOOSER_ERROR

    #define GTK_RECENT_CHOOSER_ERROR	(gtk_recent_chooser_error_quark ())

Used to get the GError quark for GtkRecentChooser errors.

### enum GtkRecentChooserError

    typedef enum
    {
      GTK_RECENT_CHOOSER_ERROR_NOT_FOUND,
      GTK_RECENT_CHOOSER_ERROR_INVALID_URI
    } GtkRecentChooserError;

These identify the various errors that can occur while calling GtkRecentChooser functions.

`GTK_RECENT_CHOOSER_ERROR_NOT_FOUND` | Indicates that a file does not exist
`GTK_RECENT_CHOOSER_ERROR_INVALID_URI` | Indicates a malformed URI

### gtk_recent_chooser_set_show_private ()

    void        gtk_recent_chooser_set_show_private
                                                (GtkRecentChooser *chooser,
                                                 gboolean show_private);

Whether to show recently used resources marked registered as private.

`chooser` : | a GtkRecentChooser
`show_private` : | `TRUE` to show private items, `FALSE` otherwise

Since 2.10

### gtk_recent_chooser_get_show_private ()

    gboolean    gtk_recent_chooser_get_show_private
                                                (GtkRecentChooser *chooser);

Returns whether `chooser` should display recently used resources registered as private.

`chooser` : | a GtkRecentChooser
Returns : | `TRUE` if the recent chooser should show private items, `FALSE` otherwise.

Since 2.10

### gtk_recent_chooser_set_show_not_found ()

    void        gtk_recent_chooser_set_show_not_found
                                                (GtkRecentChooser *chooser,
                                                 gboolean show_not_found);

Sets whether `chooser` should display the recently used resources that it didn't find. This only applies to local resources.

`chooser` : | a GtkRecentChooser
`show_not_found` : | whether to show the local items we didn't find

Since 2.10

### gtk_recent_chooser_get_show_not_found ()

    gboolean    gtk_recent_chooser_get_show_not_found
                                                (GtkRecentChooser *chooser);

Retrieves whether `chooser` should show the recently used resources that were not found.

`chooser` : | a GtkRecentChooser
Returns : | `TRUE` if the resources not found should be displayed, and `FALSE` otheriwse.

Since 2.10

### gtk_recent_chooser_set_show_icons ()

    void        gtk_recent_chooser_set_show_icons
                                                (GtkRecentChooser *chooser,
                                                 gboolean show_icons);

Sets whether `chooser` should show an icon near the resource when displaying it.

`chooser` : | a GtkRecentChooser
`show_icons` : | whether to show an icon near the resource

Since 2.10

### gtk_recent_chooser_get_show_icons ()

    gboolean    gtk_recent_chooser_get_show_icons
                                                (GtkRecentChooser *chooser);

Retrieves whether `chooser` should show an icon near the resource.

`chooser` : | a GtkRecentChooser
Returns : | `TRUE` if the icons should be displayed, `FALSE` otherwise.

Since 2.10

### gtk_recent_chooser_set_select_multiple ()

    void        gtk_recent_chooser_set_select_multiple
                                                (GtkRecentChooser *chooser,
                                                 gboolean select_multiple);

Sets whether `chooser` can select multiple items.

`chooser` : | a GtkRecentChooser
`select_multiple` : | `TRUE` if `chooser` can select more than one item

Since 2.10

### gtk_recent_chooser_get_select_multiple ()

    gboolean    gtk_recent_chooser_get_select_multiple
                                                (GtkRecentChooser *chooser);

Gets whether `chooser` can select multiple items.

`chooser` : | a GtkRecentChooser
Returns : | `TRUE` if `chooser` can select more than one item.

Since 2.10

### gtk_recent_chooser_set_local_only ()

    void        gtk_recent_chooser_set_local_only
                                                (GtkRecentChooser *chooser,
                                                 gboolean local_only);

Sets whether only local resources, that is resources using the file:// URI scheme, should be shown in the recently used resources selector. If `local_only` is `TRUE` (the default) then the shown resources are guaranteed to be accessible through the operating system native file system.

`chooser` : | a GtkRecentChooser
`local_only` : | `TRUE` if only local files can be shown

Since 2.10

### gtk_recent_chooser_get_local_only ()

    gboolean    gtk_recent_chooser_get_local_only
                                                (GtkRecentChooser *chooser);

Gets whether only local resources should be shown in the recently used resources selector. See `gtk_recent_chooser_set_local_only()`

`chooser` : | a GtkRecentChooser
Returns : | `TRUE` if only local resources should be shown.

Since 2.10

### gtk_recent_chooser_set_limit ()

    void        gtk_recent_chooser_set_limit    (GtkRecentChooser *chooser,
                                                 gint limit);

Sets the number of items that should be returned by `gtk_recent_chooser_get_items()` and `gtk_recent_chooser_get_uris()`.

`chooser` : | a GtkRecentChooser
`limit` : | a positive integer, or -1 for all items

Since 2.10

### gtk_recent_chooser_get_limit ()

    gint        gtk_recent_chooser_get_limit    (GtkRecentChooser *chooser);

Gets the number of items returned by `gtk_recent_chooser_get_items()` and `gtk_recent_chooser_get_uris()`.

`chooser` : | a GtkRecentChooser
Returns : | A positive integer, or -1 meaning that all items are returned.

Since 2.10

### gtk_recent_chooser_set_show_tips ()

    void        gtk_recent_chooser_set_show_tips
                                                (GtkRecentChooser *chooser,
                                                 gboolean show_tips);

Sets whether to show a tooltips on the widget.

`chooser` : | a GtkRecentChooser
`show_tips` : | `TRUE` if tooltips should be shown

Since 2.10

### gtk_recent_chooser_get_show_tips ()

    gboolean    gtk_recent_chooser_get_show_tips
                                                (GtkRecentChooser *chooser);

Gets whether `chooser` should display tooltips.

`chooser` : | a GtkRecentChooser
Returns : | `TRUE` if the recent chooser should show tooltips, `FALSE` otherwise.

Since 2.10

### gtk_recent_chooser_set_show_numbers ()

    void        gtk_recent_chooser_set_show_numbers
                                                (GtkRecentChooser *chooser,
                                                 gboolean show_numbers);

Whether to show recently used resources prepended by a unique number.

Do not use this function: use `gtk_recent_chooser_menu_set_show_numbers()` instead.

`chooser` : | a GtkRecentChooser
`show_numbers` : | `TRUE` to show numbers, `FALSE` otherwise

Since 2.10

### gtk_recent_chooser_get_show_numbers ()

    gboolean    gtk_recent_chooser_get_show_numbers
                                                (GtkRecentChooser *chooser);

Returns whether `chooser` should display recently used resources prepended by a unique number.

Do not use this function: use `gtk_recent_chooser_menu_get_show_numbers()` instead.

`chooser` : | a GtkRecentChooser
Returns : | `TRUE` if the recent chooser should show display numbers, `FALSE` otherwise.

Since 2.10

### enum GtkRecentSortType

    typedef enum
    {
      GTK_RECENT_SORT_NONE = 0,
      GTK_RECENT_SORT_MRU,
      GTK_RECENT_SORT_LRU,
      GTK_RECENT_SORT_CUSTOM
    } GtkRecentSortType;

Used to specify the sorting method to be applyed to the recently used resource list.

`GTK_RECENT_SORT_NONE` | Do not sort the returned list of recently used resources.
`GTK_RECENT_SORT_MRU` | Sort the returned list with the most recently used items first.
`GTK_RECENT_SORT_LRU` | Sort the returned list with the least recently used items first.
`GTK_RECENT_SORT_CUSTOM` | Sort the returned list using a custom sorting function passed using `gtk_recent_manager_set_sort_func()`.

### gtk_recent_chooser_set_sort_type ()

    void        gtk_recent_chooser_set_sort_type
                                                (GtkRecentChooser *chooser,
                                                 GtkRecentSortType sort_type);

Changes the sorting order of the recently used resources list displayed by `chooser`.

`chooser` : | a GtkRecentChooser
`sort_type` : | sort order that the chooser should use

Since 2.10

### gtk_recent_chooser_get_sort_type ()

    GtkRecentSortType gtk_recent_chooser_get_sort_type
                                                (GtkRecentChooser *chooser);

Gets the value set by `gtk_recent_chooser_set_sort_type()`.

`chooser` : | a GtkRecentChooser
Returns : | the sorting order of the `chooser`.

Since 2.10

### GtkRecentSortFunc ()

    gint        (*GtkRecentSortFunc)            (GtkRecentInfo *a,
                                                 GtkRecentInfo *b,
                                                 gpointer user_data);

`a` : |
`b` : |
`user_data` : |
Returns : |

### gtk_recent_chooser_set_sort_func ()

    void        gtk_recent_chooser_set_sort_func
                                                (GtkRecentChooser *chooser,
                                                 GtkRecentSortFunc sort_func,
                                                 gpointer sort_data,
                                                 GDestroyNotify data_destroy);

Sets the comparison function used when sorting to be `sort_func`. If the `chooser` has the sort type set to GTK_RECENT_SORT_CUSTOM then the chooser will sort using this function.

To the comparison function will be passed two GtkRecentInfo structs and `sort_data`; `sort_func` should return a positive integer if the first item comes before the second, zero if the two items are equal and a negative integer if the first item comes after the second.

`chooser` : | a GtkRecentChooser
`sort_func` : | the comparison function
`sort_data` : | user data to pass to `sort_func`, or `NULL`
`data_destroy` : | destroy notifier for `sort_data`, or `NULL`

Since 2.10

### gtk_recent_chooser_set_current_uri ()

    gboolean    gtk_recent_chooser_set_current_uri
                                                (GtkRecentChooser *chooser,
                                                 const gchar *uri,
                                                 GError **error);

Sets `uri` as the current URI for `chooser`.

`chooser` : | a GtkRecentChooser
`uri` : | a URI
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if the URI was found.

Since 2.10

### gtk_recent_chooser_get_current_uri ()

    gchar*      gtk_recent_chooser_get_current_uri
                                                (GtkRecentChooser *chooser);

Gets the URI currently selected by `chooser`.

`chooser` : | a GtkRecentChooser
Returns : | a newly allocated string holding a URI.

Since 2.10

### gtk_recent_chooser_get_current_item ()

    GtkRecentInfo* gtk_recent_chooser_get_current_item
                                                (GtkRecentChooser *chooser);

Gets the GtkRecentInfo currently selected by `chooser`.

`chooser` : | a GtkRecentChooser
Returns : | a GtkRecentInfo. Use `gtk_recent_info_unref()` when when you have finished using it.

Since 2.10

### gtk_recent_chooser_select_uri ()

    gboolean    gtk_recent_chooser_select_uri   (GtkRecentChooser *chooser,
                                                 const gchar *uri,
                                                 GError **error);

Selects `uri` inside `chooser`.

`chooser` : | a GtkRecentChooser
`uri` : | a URI
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` if `uri` was found.

Since 2.10

### gtk_recent_chooser_unselect_uri ()

    void        gtk_recent_chooser_unselect_uri (GtkRecentChooser *chooser,
                                                 const gchar *uri);

Unselects `uri` inside `chooser`.

`chooser` : | a GtkRecentChooser
`uri` : | a URI

Since 2.10

### gtk_recent_chooser_select_all ()

    void        gtk_recent_chooser_select_all   (GtkRecentChooser *chooser);

Selects all the items inside `chooser`, if the `chooser` supports multiple selection.

`chooser` : | a GtkRecentChooser

Since 2.10

### gtk_recent_chooser_unselect_all ()

    void        gtk_recent_chooser_unselect_all (GtkRecentChooser *chooser);

Unselects all the items inside `chooser`.

`chooser` : | a GtkRecentChooser

Since 2.10

### gtk_recent_chooser_get_items ()

    GList*      gtk_recent_chooser_get_items    (GtkRecentChooser *chooser);

Gets the list of recently used resources in form of GtkRecentInfo objects.

The return value of this function is affected by the "sort-type" and "limit" properties of `chooser`.

`chooser` : | a GtkRecentChooser
Returns : | A newly allocated list of GtkRecentInfo objects. You should use `gtk_recent_info_unref()` on every item of the list, and then free the list itself using `g_list_free()`.

Since 2.10

### gtk_recent_chooser_get_uris ()

    gchar**     gtk_recent_chooser_get_uris     (GtkRecentChooser *chooser,
                                                 gsize *length);

Gets the URI of the recently used resources.

The return value of this function is affected by the "sort-type" and "limit" properties of `chooser`.

Since the returned array is `NULL` terminated, `length` may be `NULL`.

`chooser` : | a GtkRecentChooser
`length` : | return location for a the length of the URI list, or `NULL`
Returns : | A newly allocated, `NULL` terminated array of strings. Use `g_strfreev()` to free it.

Since 2.10

### gtk_recent_chooser_add_filter ()

    void        gtk_recent_chooser_add_filter   (GtkRecentChooser *chooser,
                                                 GtkRecentFilter *filter);

Adds `filter` to the list of GtkRecentFilter objects held by `chooser`.

If no previous filter objects were defined, this function will call `gtk_recent_chooser_set_filter()`.

`chooser` : | a GtkRecentChooser
`filter` : | a GtkRecentFilter

Since 2.10

### gtk_recent_chooser_remove_filter ()

    void        gtk_recent_chooser_remove_filter
                                                (GtkRecentChooser *chooser,
                                                 GtkRecentFilter *filter);

Removes `filter` from the list of GtkRecentFilter objects held by `chooser`.

`chooser` : | a GtkRecentChooser
`filter` : | a GtkRecentFilter

Since 2.10

### gtk_recent_chooser_list_filters ()

    GSList*     gtk_recent_chooser_list_filters (GtkRecentChooser *chooser);

Gets the GtkRecentFilter objects held by `chooser`.

`chooser` : | a GtkRecentChooser
Returns : | A singly linked list of GtkRecentFilter objects. You should just free the returned list using `g_slist_free()`.

Since 2.10

### gtk_recent_chooser_set_filter ()

    void        gtk_recent_chooser_set_filter   (GtkRecentChooser *chooser,
                                                 GtkRecentFilter *filter);

Sets `filter` as the current GtkRecentFilter object used by `chooser` to affect the displayed recently used resources.

`chooser` : | a GtkRecentChooser
`filter` : | a GtkRecentFilter

Since 2.10

### gtk_recent_chooser_get_filter ()

    GtkRecentFilter* gtk_recent_chooser_get_filter
                                                (GtkRecentChooser *chooser);

Gets the GtkRecentFilter object currently used by `chooser` to affect the display of the recently used resources.

`chooser` : | a GtkRecentChooser
Returns : | a GtkRecentFilter object.

Since 2.10

## Property Details

### The "`filter`" property

      "filter"               GtkRecentFilter       : Read / Write

The current filter for selecting which resources are displayed.

### The "`limit`" property

      "limit"                gint                  : Read / Write

The maximum number of items to be displayed.

Allowed values: >= -1

Default value: -1

### The "`local-only`" property

      "local-only"           gboolean              : Read / Write

Whether the selected resource(s) should be limited to local file: URIs.

Default value: TRUE

### The "`recent-manager`" property

      "recent-manager"       GtkRecentManager      : Write / Construct Only

The RecentManager object to use.

### The "`select-multiple`" property

      "select-multiple"      gboolean              : Read / Write

Whether to allow multiple items to be selected.

Default value: FALSE

### The "`show-icons`" property

      "show-icons"           gboolean              : Read / Write

Whether there should be an icon near the item.

Default value: TRUE

### The "`show-not-found`" property

      "show-not-found"       gboolean              : Read / Write

Whether the items pointing to unavailable resources should be displayed.

Default value: FALSE

### The "`show-private`" property

      "show-private"         gboolean              : Read / Write

Whether the private items should be displayed.

Default value: FALSE

### The "`show-tips`" property

      "show-tips"            gboolean              : Read / Write

Whether there should be a tooltip on the item.

Default value: FALSE

### The "`sort-type`" property

      "sort-type"            GtkRecentSortType     : Read / Write

The sorting order of the items displayed.

Default value: GTK_RECENT_SORT_NONE

## Signal Details

### The "item-activated" signal

    void        user_function                  (GtkRecentChooser *chooser,
                                                gpointer          user_data)      : Run last

This signal is emitted when the user "activates" a recent item in the recent chooser. This can happen by double-clicking on an item in the recently used resources list, or by pressing Enter.

`chooser` : | the object which received the signal
`user_data` : | user data set when the signal handler was connected.

Since 2.10

### The "selection-changed" signal

    void        user_function                  (GtkRecentChooser *chooser,
                                                gpointer          user_data)      : Run last

This signal is emitted when there is a change in the set of selected recently used resources. This can happen when a user modifies the selection with the mouse or the keyboard, or when explicitely calling functions to change the selection.

`chooser` : | the object which received the signal
`user_data` : | user data set when the signal handler was connected.

Since 2.10

## See Also

GtkRecentManager, GtkRecentChooserDialog, GtkRecentChooserWidget, GtkRecentChooserMenu