GtkRecentChooser

GtkRecentChooser — Interface implemented by widgets displaying recently used files

Properties

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

Object Hierarchy

    GInterface
    ╰── GtkRecentChooser

Prerequisites

GtkRecentChooser requires GObject.

Known Implementations

GtkRecentChooser is implemented by GtkRecentAction, GtkRecentChooserDialog, GtkRecentChooserMenu and GtkRecentChooserWidget.

Includes

#include <gtk/gtk.h>

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.

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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()

Parameters

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().

Parameters

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().

Parameters

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 containing the full path of each recently used resource in a GtkRecentChooser widget.

Parameters

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 containing the full path of a recently user resource.

Parameters

chooser

a GtkRecentChooser

 

Returns

TRUE if the recent chooser should show tooltips, FALSE otherwise.

Since: 2.10


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 .

Parameters

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().

Parameters

chooser

a GtkRecentChooser

 

Returns

the sorting order of the chooser .

Since: 2.10


GtkRecentSortFunc ()

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

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.

Parameters

chooser

a GtkRecentChooser

 

sort_func

the comparison function

 

sort_data

user data to pass to sort_func , or NULL.

[allow-none]

data_destroy

destroy notifier for sort_data , or NULL.

[allow-none]

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 .

Parameters

chooser

a GtkRecentChooser

 

uri

a URI

 

error

return location for a GError, or NULL.

[allow-none]

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 .

Parameters

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 .

Parameters

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 .

Parameters

chooser

a GtkRecentChooser

 

uri

a URI

 

error

return location for a GError, or NULL.

[allow-none]

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 .

Parameters

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.

Parameters

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 .

Parameters

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 .

Parameters

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().

[element-type GtkRecentInfo][transfer full]

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.

Parameters

chooser

a GtkRecentChooser

 

length

return location for a the length of the URI list, or NULL.

[out][allow-none]

Returns

A newly allocated, NULL-terminated array of strings. Use g_strfreev() to free it.

[array length=length zero-terminated=1][transfer full]

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().

Parameters

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 .

Parameters

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 .

Parameters

chooser

a GtkRecentChooser

 

Returns

A singly linked list of GtkRecentFilter objects. You should just free the returned list using g_slist_free().

[element-type GtkRecentFilter][transfer container]

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.

Parameters

chooser

a GtkRecentChooser

 

filter

a GtkRecentFilter.

[allow-none]

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.

Parameters

chooser

a GtkRecentChooser

 

Returns

a GtkRecentFilter object.

[transfer none]

Since: 2.10

Types and Values

GtkRecentChooser

typedef struct _GtkRecentChooser GtkRecentChooser;

struct GtkRecentChooserIface

struct GtkRecentChooserIface {
  /*
   * 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           sort_data,
  					    GDestroyNotify     data_destroy);

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

Members

set_current_uri ()

Sets uri as the current URI for chooser.

 

get_current_uri ()

Gets the URI currently selected by chooser.

 

select_uri ()

Selects uri inside chooser.

 

unselect_uri ()

Unselects uri inside chooser.

 

select_all ()

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

 

unselect_all ()

Unselects all the items inside chooser.

 

get_items ()

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

 

get_recent_manager ()

Gets the GtkRecentManager used by chooser.

 

add_filter ()

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

 

remove_filter ()

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

 

list_filters ()

Gets the GtkRecentFilter objects held by chooser.

 

set_sort_func ()

Sets the comparison function used when sorting to be sort_func.

 

item_activated ()

Signal emitted when the user “activates” a recent item in the recent chooser.

 

selection_changed ()

Signal emitted when there is a change in the set of selected recently used resources.

 

GTK_RECENT_CHOOSER_ERROR

#define GTK_RECENT_CHOOSER_ERROR (gtk_recent_chooser_error_quark ())

Used to get the GError quark for GtkRecentChooser errors.

Since: 2.10


enum GtkRecentChooserError

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

Members

GTK_RECENT_CHOOSER_ERROR_NOT_FOUND

Indicates that a file does not exist

 

GTK_RECENT_CHOOSER_ERROR_INVALID_URI

Indicates a malformed URI

 

Since: 2.10


enum GtkRecentSortType

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

Members

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_chooser_set_sort_func().

 

Since: 2.10

Property Details

The “filter” property

  “filter”                   GtkRecentFilter *

The GtkRecentFilter object to be used when displaying the recently used resources.

Flags: Read / Write

Since: 2.10


The “limit” property

  “limit”                    gint

The maximum number of recently used resources to be displayed, or -1 to display all items.

Flags: Read / Write

Allowed values: >= -1

Default value: 50

Since: 2.10


The “local-only” property

  “local-only”               gboolean

Whether this GtkRecentChooser should display only local (file:) resources.

Flags: Read / Write

Default value: TRUE

Since: 2.10


The “recent-manager” property

  “recent-manager”           GtkRecentManager *

The GtkRecentManager instance used by the GtkRecentChooser to display the list of recently used resources.

Flags: Write / Construct Only

Since: 2.10


The “select-multiple” property

  “select-multiple”          gboolean

Allow the user to select multiple resources.

Flags: Read / Write

Default value: FALSE

Since: 2.10


The “show-icons” property

  “show-icons”               gboolean

Whether this GtkRecentChooser should display an icon near the item.

Flags: Read / Write

Default value: TRUE

Since: 2.10


The “show-not-found” property

  “show-not-found”           gboolean

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).

Flags: Read / Write

Default value: TRUE

Since: 2.10


The “show-private” property

  “show-private”             gboolean

Whether the private items should be displayed.

Flags: Read / Write

Default value: FALSE


The “show-tips” property

  “show-tips”                gboolean

Whether this GtkRecentChooser should display a tooltip containing the full path of the recently used resources.

Flags: Read / Write

Default value: FALSE

Since: 2.10


The “sort-type” property

  “sort-type”                GtkRecentSortType

Sorting order to be used when displaying the recently used resources.

Flags: Read / Write

Default value: GTK_RECENT_SORT_NONE

Since: 2.10

Signal Details

The “item-activated” signal

void
user_function (GtkRecentChooser *chooser,
               gpointer          user_data)

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.

Parameters

chooser

the object which received the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 2.10


The “selection-changed” signal

void
user_function (GtkRecentChooser *chooser,
               gpointer          user_data)

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 explicitly calling functions to change the selection.

Parameters

chooser

the object which received the signal

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 2.10