Gtk.RecentChooser¶

Implementations:
	`Gtk.RecentAction`, `Gtk.RecentChooserDialog`, `Gtk.RecentChooserMenu`, `Gtk.RecentChooserWidget`

Methods¶

	`add_filter` (filter)
	`get_current_item` ()
	`get_current_uri` ()
	`get_filter` ()
	`get_items` ()
	`get_limit` ()
	`get_local_only` ()
	`get_select_multiple` ()
	`get_show_icons` ()
	`get_show_not_found` ()
	`get_show_private` ()
	`get_show_tips` ()
	`get_sort_type` ()
	`get_uris` ()
	`list_filters` ()
	`remove_filter` (filter)
	`select_all` ()
	`select_uri` (uri)
	`set_current_uri` (uri)
	`set_filter` (filter)
	`set_limit` (limit)
	`set_local_only` (local_only)
	`set_select_multiple` (select_multiple)
	`set_show_icons` (show_icons)
	`set_show_not_found` (show_not_found)
	`set_show_private` (show_private)
	`set_show_tips` (show_tips)
	`set_sort_func` (sort_func, *sort_data)
	`set_sort_type` (sort_type)
	`unselect_all` ()
	`unselect_uri` (uri)

Virtual Methods¶

	`do_add_filter` (filter)
	`do_get_current_uri` ()
	`do_get_items` ()
	`do_item_activated` ()
	`do_list_filters` ()
	`do_remove_filter` (filter)
	`do_select_all` ()
	`do_select_uri` (uri)
	`do_selection_changed` ()
	`do_set_current_uri` (uri)
	`do_set_sort_func` (sort_func, sort_data)
	`do_unselect_all` ()
	`do_unselect_uri` (uri)

Properties¶

Name	Type	Flags	Short Description
`filter`	`Gtk.RecentFilter`	r/w	The current filter for selecting which resources are displayed
`limit`	`int`	r/w/en	The maximum number of items to be displayed
`local-only`	`bool`	r/w/en	Whether the selected resource(s) should be limited to local file: URIs
`recent-manager`	`Gtk.RecentManager`	w/co	The RecentManager object to use
`select-multiple`	`bool`	r/w/en	Whether to allow multiple items to be selected
`show-icons`	`bool`	r/w/en	Whether there should be an icon near the item
`show-not-found`	`bool`	r/w/en	Whether the items pointing to unavailable resources should be displayed
`show-private`	`bool`	r/w/en	Whether the private items should be displayed
`show-tips`	`bool`	r/w/en	Whether there should be a tooltip on the item
`sort-type`	`Gtk.RecentSortType`	r/w/en	The sorting order of the items displayed

Signals¶

Name	Short Description
`item-activated`	This signal is emitted when the user “activates” a recent item in the recent chooser.
`selection-changed`	This signal is emitted when there is a change in the set of selected recently used resources.

Fields¶

None

Class Details¶

class Gtk.RecentChooser¶

Bases:	`GObject.GInterface`
Structure:	`Gtk.RecentChooserIface`

Gtk.RecentChooser 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 Gtk.RecentChooserWidget, Gtk.RecentChooserDialog and Gtk.RecentChooserMenu.

Recently used files are supported since GTK+ 2.10.

add_filter(filter)[source]¶

Parameters:	filter (`Gtk.RecentFilter`) – a `Gtk.RecentFilter`

Adds filter to the list of Gtk.RecentFilter objects held by self.

If no previous filter objects were defined, this function will call Gtk.RecentChooser.set_filter().

New in version 2.10.

get_current_item()[source]¶

Returns:	a `Gtk.RecentInfo`. Use `Gtk.RecentInfo.unref`() when when you have finished using it.
Return type:	`Gtk.RecentInfo`

Gets the Gtk.RecentInfo currently selected by self.

New in version 2.10.

get_current_uri()[source]¶

Returns:	a newly allocated string holding a URI.
Return type:	`str`

Gets the URI currently selected by self.

New in version 2.10.

get_filter()[source]¶

Returns:	a `Gtk.RecentFilter` object.
Return type:	`Gtk.RecentFilter`

Gets the Gtk.RecentFilter object currently used by self to affect the display of the recently used resources.

New in version 2.10.

get_items()[source]¶

Returns:	A newly allocated list of `Gtk.RecentInfo` objects. You should use `Gtk.RecentInfo.unref`() on every item of the list, and then free the list itself using g_list_free().
Return type:	[`Gtk.RecentInfo`]

Gets the list of recently used resources in form of Gtk.RecentInfo objects.

The return value of this function is affected by the “sort-type” and “limit” properties of self.

New in version 2.10.

get_limit()[source]¶

Returns:	A positive integer, or -1 meaning that all items are returned.
Return type:	`int`

Gets the number of items returned by Gtk.RecentChooser.get_items() and Gtk.RecentChooser.get_uris().

New in version 2.10.

get_local_only()[source]¶

Returns:	`True` if only local resources should be shown.
Return type:	`bool`

Gets whether only local resources should be shown in the recently used resources selector. See Gtk.RecentChooser.set_local_only()

New in version 2.10.

get_select_multiple()[source]¶

Returns:	`True` if self can select more than one item.
Return type:	`bool`

Gets whether self can select multiple items.

New in version 2.10.

get_show_icons()[source]¶

Returns:	`True` if the icons should be displayed, `False` otherwise.
Return type:	`bool`

Retrieves whether self should show an icon near the resource.

New in version 2.10.

get_show_not_found()[source]¶

Returns:	`True` if the resources not found should be displayed, and `False` otheriwse.
Return type:	`bool`

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

New in version 2.10.

get_show_private()[source]¶

Returns:	`True` if the recent chooser should show private items, `False` otherwise.
Return type:	`bool`

Returns whether self should display recently used resources registered as private.

New in version 2.10.

get_show_tips()[source]¶

Returns:	`True` if the recent chooser should show tooltips, `False` otherwise.
Return type:	`bool`

Gets whether self should display tooltips containing the full path of a recently user resource.

New in version 2.10.

get_sort_type()[source]¶

Returns:	the sorting order of the self.
Return type:	`Gtk.RecentSortType`

Gets the value set by Gtk.RecentChooser.set_sort_type().

New in version 2.10.

get_uris()[source]¶

Returns:	A newly allocated, `None`-terminated array of strings. Use `GLib.strfreev`() to free it.
Return type:	[`str`]

Gets the URI of the recently used resources.

The return value of this function is affected by the “sort-type” and “limit” properties of self.

Since the returned array is None terminated, length may be None.

New in version 2.10.

list_filters()[source]¶

Returns:	A singly linked list of `Gtk.RecentFilter` objects. You should just free the returned list using g_slist_free().
Return type:	[`Gtk.RecentFilter`]

Gets the Gtk.RecentFilter objects held by self.

New in version 2.10.

remove_filter(filter)[source]¶

Parameters:	filter (`Gtk.RecentFilter`) – a `Gtk.RecentFilter`

Removes filter from the list of Gtk.RecentFilter objects held by self.

New in version 2.10.

select_all()[source]¶: Selects all the items inside self, if the self supports multiple selection.

New in version 2.10.

select_uri(uri)[source]¶

Parameters:	uri (`str`) – a URI
Raises:	`GLib.Error`
Returns:	`True` if uri was found.
Return type:	`bool`

Selects uri inside self.

New in version 2.10.

set_current_uri(uri)[source]¶

Parameters:	uri (`str`) – a URI
Raises:	`GLib.Error`
Returns:	`True` if the URI was found.
Return type:	`bool`

Sets uri as the current URI for self.

New in version 2.10.

set_filter(filter)[source]¶

Parameters:	filter (`Gtk.RecentFilter` or `None`) – a `Gtk.RecentFilter`

Sets filter as the current Gtk.RecentFilter object used by self to affect the displayed recently used resources.

New in version 2.10.

set_limit(limit)[source]¶

Parameters:	limit (`int`) – a positive integer, or -1 for all items

Sets the number of items that should be returned by Gtk.RecentChooser.get_items() and Gtk.RecentChooser.get_uris().

New in version 2.10.

set_local_only(local_only)[source]¶

Parameters:	local_only (`bool`) – `True` if only local files can be shown

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.

New in version 2.10.

set_select_multiple(select_multiple)[source]¶

Parameters:	select_multiple (`bool`) – `True` if self can select more than one item

Sets whether self can select multiple items.

New in version 2.10.

set_show_icons(show_icons)[source]¶

Parameters:	show_icons (`bool`) – whether to show an icon near the resource

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

New in version 2.10.

set_show_not_found(show_not_found)[source]¶

Parameters:	show_not_found (`bool`) – whether to show the local items we didn’t find

Sets whether self should display the recently used resources that it didn’t find. This only applies to local resources.

New in version 2.10.

set_show_private(show_private)[source]¶

Parameters:	show_private (`bool`) – `True` to show private items, `False` otherwise

Whether to show recently used resources marked registered as private.

New in version 2.10.

set_show_tips(show_tips)[source]¶

Parameters:	show_tips (`bool`) – `True` if tooltips should be shown

Sets whether to show a tooltips containing the full path of each recently used resource in a Gtk.RecentChooser widget.

New in version 2.10.

set_sort_func(sort_func, *sort_data)[source]¶

Parameters:	sort_func (`Gtk.RecentSortFunc`) – the comparison function sort_data (`object` or `None`) – user data to pass to sort_func, or `None`

Sets the comparison function used when sorting to be sort_func. If the self has the sort type set to Gtk.RecentSortType.CUSTOM then the chooser will sort using this function.

To the comparison function will be passed two Gtk.RecentInfo 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.

New in version 2.10.

set_sort_type(sort_type)[source]¶

Parameters:	sort_type (`Gtk.RecentSortType`) – sort order that the chooser should use

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

New in version 2.10.

unselect_all()[source]¶: Unselects all the items inside self.

New in version 2.10.

unselect_uri(uri)[source]¶

Parameters:	uri (`str`) – a URI

Unselects uri inside self.

New in version 2.10.

do_add_filter(filter) virtual¶

Parameters:	filter (`Gtk.RecentFilter`) – a `Gtk.RecentFilter`

Adds filter to the list of Gtk.RecentFilter objects held by chooser.

If no previous filter objects were defined, this function will call Gtk.RecentChooser.set_filter().

New in version 2.10.

do_get_current_uri() virtual¶

Returns:	a newly allocated string holding a URI.
Return type:	`str`

Gets the URI currently selected by chooser.

New in version 2.10.

do_get_items() virtual¶

Returns:	A newly allocated list of `Gtk.RecentInfo` objects. You should use `Gtk.RecentInfo.unref`() on every item of the list, and then free the list itself using g_list_free().
Return type:	[`Gtk.RecentInfo`]

Gets the list of recently used resources in form of Gtk.RecentInfo objects.

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

New in version 2.10.

do_item_activated() virtual¶

do_list_filters() virtual¶

Returns:	A singly linked list of `Gtk.RecentFilter` objects. You should just free the returned list using g_slist_free().
Return type:	[`Gtk.RecentFilter`]

Gets the Gtk.RecentFilter objects held by chooser.

New in version 2.10.

do_remove_filter(filter) virtual¶

Parameters:	filter (`Gtk.RecentFilter`) – a `Gtk.RecentFilter`

Removes filter from the list of Gtk.RecentFilter objects held by chooser.

New in version 2.10.

do_select_all() virtual¶: Selects all the items inside chooser, if the chooser supports multiple selection.

New in version 2.10.

do_select_uri(uri) virtual¶

Parameters:	uri (`str`) – a URI
Returns:	`True` if uri was found.
Return type:	`bool`

Selects uri inside chooser.

New in version 2.10.

do_selection_changed() virtual¶

do_set_current_uri(uri) virtual¶

Parameters:	uri (`str`) – a URI
Returns:	`True` if the URI was found.
Return type:	`bool`

Sets uri as the current URI for chooser.

New in version 2.10.

do_set_sort_func(sort_func, sort_data) virtual¶

Parameters:	sort_func (`Gtk.RecentSortFunc`) – the comparison function sort_data (`object` or `None`) – user data to pass to sort_func, or `None`

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

To the comparison function will be passed two Gtk.RecentInfo 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.

New in version 2.10.

do_unselect_all() virtual¶: Unselects all the items inside chooser.

New in version 2.10.

do_unselect_uri(uri) virtual¶

Parameters:	uri (`str`) – a URI

Unselects uri inside chooser.

New in version 2.10.

Signal Details¶

Gtk.RecentChooser.signals.item_activated(recent_chooser)¶

Signal Name:	`item-activated`
Flags:	`RUN_LAST`
Parameters:	recent_chooser (`Gtk.RecentChooser`) – The object which received the signal

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.

New in version 2.10.

Gtk.RecentChooser.signals.selection_changed(recent_chooser)¶

Signal Name:	`selection-changed`
Flags:	`RUN_LAST`
Parameters:	recent_chooser (`Gtk.RecentChooser`) – The object which received the signal

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.

New in version 2.10.

Property Details¶

Gtk.RecentChooser.props.filter¶

Name:	`filter`
Type:	`Gtk.RecentFilter`
Default Value:	`None`
Flags:	`READABLE`, `WRITABLE`

The Gtk.RecentFilter object to be used when displaying the recently used resources.

New in version 2.10.

Gtk.RecentChooser.props.limit¶

Name:	`limit`
Type:	`int`
Default Value:	`50`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

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

New in version 2.10.

Gtk.RecentChooser.props.local_only¶

Name:	`local-only`
Type:	`bool`
Default Value:	`True`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

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

New in version 2.10.

Gtk.RecentChooser.props.recent_manager¶

Name:	`recent-manager`
Type:	`Gtk.RecentManager`
Default Value:	`None`
Flags:	`WRITABLE`, `CONSTRUCT_ONLY`

The Gtk.RecentManager instance used by the Gtk.RecentChooser to display the list of recently used resources.

New in version 2.10.

Gtk.RecentChooser.props.select_multiple¶

Name:	`select-multiple`
Type:	`bool`
Default Value:	`False`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

Allow the user to select multiple resources.

New in version 2.10.

Gtk.RecentChooser.props.show_icons¶

Name:	`show-icons`
Type:	`bool`
Default Value:	`True`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

Whether this Gtk.RecentChooser should display an icon near the item.

New in version 2.10.

Gtk.RecentChooser.props.show_not_found¶

Name:	`show-not-found`
Type:	`bool`
Default Value:	`True`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

Whether this Gtk.RecentChooser 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).

New in version 2.10.

Gtk.RecentChooser.props.show_private¶

Name:	`show-private`
Type:	`bool`
Default Value:	`False`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

Whether the private items should be displayed

Gtk.RecentChooser.props.show_tips¶

Name:	`show-tips`
Type:	`bool`
Default Value:	`False`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

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

New in version 2.10.

Gtk.RecentChooser.props.sort_type¶

Name:	`sort-type`
Type:	`Gtk.RecentSortType`
Default Value:	`Gtk.RecentSortType.NONE`
Flags:	`READABLE`, `WRITABLE`, `EXPLICIT_NOTIFY`

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

New in version 2.10.