Gtk.RecentChooser

g GObject.GInterface GObject.GInterface Gtk.RecentChooser Gtk.RecentChooser GObject.GInterface->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:

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:

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.