|  |  |  | GTK+ Reference Manual |  | 
|---|---|---|---|---|
| GtkRecentChooserGtkRecentChooser — Interface implemented by GtkRecentChooserWidget, GtkRecentChooserMenu and GtkRecentChooserDialog | 
#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);
GtkRecentChooser is implemented by GtkRecentChooserDialog, GtkRecentChooserWidget and GtkRecentChooserMenu.
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.
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;
#define GTK_RECENT_CHOOSER_ERROR (gtk_recent_chooser_error_quark ())
Used to get the GError quark for GtkRecentChooser errors.
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.
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: | TRUEto show private items,FALSEotherwise | 
Since 2.10
gboolean gtk_recent_chooser_get_show_private (GtkRecentChooser *chooser);
Returns whether chooser should display recently used resources
registered as private.
| chooser: | a GtkRecentChooser | 
| Returns : | TRUEif the recent chooser should show private items,FALSEotherwise. | 
Since 2.10
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
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 : | TRUEif the resources not found should be displayed, andFALSEotheriwse. | 
Since 2.10
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
gboolean gtk_recent_chooser_get_show_icons (GtkRecentChooser *chooser);
Retrieves whether chooser should show an icon near the resource.
| chooser: | a GtkRecentChooser | 
| Returns : | TRUEif the icons should be displayed,FALSEotherwise. | 
Since 2.10
void                gtk_recent_chooser_set_select_multiple
                                                        (GtkRecentChooser *chooser,
                                                         gboolean select_multiple);
Sets whether chooser can select multiple items.
| chooser: | a GtkRecentChooser | 
| select_multiple: | TRUEifchoosercan select more than one item | 
Since 2.10
gboolean            gtk_recent_chooser_get_select_multiple
                                                        (GtkRecentChooser *chooser);
Gets whether chooser can select multiple items.
| chooser: | a GtkRecentChooser | 
| Returns : | TRUEifchoosercan select more than one item. | 
Since 2.10
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: | TRUEif only local files can be shown | 
Since 2.10
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 : | TRUEif only local resources should be shown. | 
Since 2.10
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
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
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: | TRUEif tooltips should be shown | 
Since 2.10
gboolean gtk_recent_chooser_get_show_tips (GtkRecentChooser *chooser);
Gets whether chooser should display tooltips.
| chooser: | a GtkRecentChooser | 
| Returns : | TRUEif the recent chooser should show tooltips,FALSEotherwise. | 
Since 2.10
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: | TRUEto show numbers,FALSEotherwise | 
Since 2.10
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 : | TRUEif the recent chooser should show display numbers,FALSEotherwise. | 
Since 2.10
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.
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
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
gint (*GtkRecentSortFunc) (GtkRecentInfo *a, GtkRecentInfo *b, gpointer user_data);
| a: | |
| b: | |
| user_data: | |
| Returns : | 
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, orNULL | 
| data_destroy: | destroy notifier for sort_data, orNULL | 
Since 2.10
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 : | TRUEif the URI was found. | 
Since 2.10
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
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
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 : | TRUEifuriwas found. | 
Since 2.10
void gtk_recent_chooser_unselect_uri (GtkRecentChooser *chooser, const gchar *uri);
Unselects uri inside chooser.
| chooser: | a GtkRecentChooser | 
| uri: | a URI | 
Since 2.10
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
void gtk_recent_chooser_unselect_all (GtkRecentChooser *chooser);
Unselects all the items inside chooser.
| chooser: | a GtkRecentChooser | 
Since 2.10
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 usingg_list_free(). | 
Since 2.10
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, NULLterminated array of strings. Useg_strfreev()to free it. | 
Since 2.10
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
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
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
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
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
::item-activated signalvoid 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
::selection-changed signalvoid 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