![]() |
![]() |
![]() |
GTK+ Reference Manual | ![]() |
---|---|---|---|---|
#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 GtkRecentChooserMenu, GtkRecentChooserDialog, GtkRecentChooserWidget and GtkRecentAction.
"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
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 : | TRUE to show private items, FALSE otherwise |
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 : | TRUE if the recent chooser should show private items, FALSE otherwise. |
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 : | TRUE if the resources not found should be displayed, and FALSE otheriwse. |
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 : | TRUE if the icons should be displayed, FALSE otherwise. |
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 : | TRUE if chooser can 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 : | TRUE if chooser can 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 : | TRUE if 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 : | TRUE if 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 containing the full path of each recently used resource in a GtkRecentChooser widget.
chooser : | a GtkRecentChooser |
show_tips : | TRUE if tooltips should be shown |
Since 2.10
gboolean gtk_recent_chooser_get_show_tips (GtkRecentChooser *chooser);
Gets whether chooser should display tooltips containing the full path of a recently user resource.
chooser : | a GtkRecentChooser |
Returns : | TRUE if the recent chooser should show tooltips, FALSE otherwise. |
Since 2.10
void gtk_recent_chooser_set_show_numbers (GtkRecentChooser *chooser, gboolean show_numbers);
gtk_recent_chooser_set_show_numbers has been deprecated since version 2.12 and should not be used in newly-written code. Use gtk_recent_chooser_menu_set_show_numbers() instead.
Whether to show recently used resources prepended by a unique number.
chooser : | a GtkRecentChooser |
show_numbers : | TRUE to show numbers, FALSE otherwise |
Since 2.10
gboolean gtk_recent_chooser_get_show_numbers (GtkRecentChooser *chooser);
gtk_recent_chooser_get_show_numbers has been deprecated since version 2.12 and should not be used in newly-written code. use gtk_recent_chooser_menu_get_show_numbers() instead.
Returns whether chooser should display recently used resources prepended by a unique number.
chooser : | a GtkRecentChooser |
Returns : | TRUE if the recent chooser should show display numbers, FALSE otherwise. |
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, or NULL |
data_destroy : | destroy notifier for sort_data, or NULL |
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 : | TRUE if 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 : | TRUE if uri was 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 using g_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, NULL terminated array of strings. Use g_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
"filter" GtkRecentFilter : Read / Write
The GtkRecentFilter object to be used when displaying the recently used resources.
Since 2.10
"limit" gint : Read / Write
The maximum number of recently used resources to be displayed, or -1 to display all items. By default, the GtkSetting:gtk-recent-files-limit setting is respected: you can override that limit on a particular instance of GtkRecentChooser by setting this property.
Allowed values: >= G_MAXULONG
Default value: -1
Since 2.10
"local-only" gboolean : Read / Write
Whether this GtkRecentChooser should display only local (file:) resources.
Default value: TRUE
Since 2.10
"recent-manager" GtkRecentManager : Write / Construct Only
The GtkRecentManager instance used by the GtkRecentChooser to display the list of recently used resources.
Since 2.10
"select-multiple" gboolean : Read / Write
Allow the user to select multiple resources.
Default value: FALSE
Since 2.10
"show-icons" gboolean : Read / Write
Whether this GtkRecentChooser should display an icon near the item.
Default value: TRUE
Since 2.10
"show-not-found" gboolean : Read / Write
Whether this GtkRecentChooser should display the recently used resources even if not present anymore. Setting this to FALSE will perform a potentially expensive check on every local resource (every remote resource will always be displayed).
Default value: TRUE
Since 2.10
"show-private" gboolean : Read / Write
Whether the private items should be displayed.
Default value: FALSE
"show-tips" gboolean : Read / Write
Whether this GtkRecentChooser should display a tooltip containing the full path of the recently used resources.
Default value: FALSE
Since 2.10
"sort-type" GtkRecentSortType : Read / Write
Sorting order to be used when displaying the recently used resources.
Default value: GTK_RECENT_SORT_NONE
Since 2.10
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
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