gtk.RecentChooser
Prev | The gtk Class Reference | Next

## gtk.RecentChooser

gtk.RecentChooser — an interface implemented by `gtk.RecentChooserWidget`, `gtk.RecentChooserMenu` and `gtk.RecentChooserDialog` (new in PyGTK 2.10)

## Synopsis

    class gtk.RecentChooser:
        def set_show_private(show_private)
        def get_show_private()
        def set_show_not_found(show_not_found)
        def get_show_not_found()
        def set_select_multiple(select_multiple)
        def get_select_multiple()
        def set_limit(limit)
        def get_limit()
        def set_local_only(local_only)
        def get_local_only()
        def set_show_tips(show_tips)
        def get_show_tips()
        def set_show_numbers(show_numbers)
        def get_show_numbers()
        def set_show_icons(show_icons)
        def get_show_icons()
        def set_sort_type(sort_type)
        def get_sort_type()
        def set_sort_func(sort_func, sort_data=None)
        def set_current_uri(uri)
        def get_current_uri()
        def get_current_item()
        def select_uri(uri)
        def unselect_uri(uri)
        def select_all()
        def unselect_all()
        def get_items()
        def get_uris()
        def add_filter(filter)
        def remove_filter(filter)
        def list_filters()
        def set_filter(filter)
        def get_filter()

## Ancestry

    +-- gtk.RecentChooser

## gtk.RecentChooser Properties

"filter" | Read-Write | The current `gtk.RecentFilter` for selecting which resources are displayed
"limit" | Read-Write | The maximum number of items to be displayed
"local-only" | Read-Write | if `True` the selected resource(s) should be limited to local file: URIs
"recent-manager" | Write-Construct Only | The RecentManager object to use
"select-multiple" | Read-Write | if `True` allow multiple items to be selected
"show-icons" | Read-Write | if `True` there should be an icon near the item
"show-not-found" | Read-Write | if `True` the items pointing to unavailable resources should be displayed
"show-private" | Read-Write | if `True` the private items should be displayed
"show-tips" | Read-Write | if `True` there should be a tooltip on the item
"sort-type" | Read-Write | The sorting order of the items displayed - one of the GTK Recent Sort Type Constants

## gtk.RecentChooser Signal Prototypes

"item-activated | `def callback(`chooser`, `user_param1`, `...`)`
"selection-changed | `def callback(`chooser`, `user_param1`, `...`)`

## Description

`gtk.RecentChooser` is an interface that can be implemented by widgets displaying the list of recently used files. In PyGTK, the main objects that implement this interface are `gtk.RecentChooserWidget`, `gtk.RecentChooserDialog` and `gtk.RecentChooserMenu`.

Recently used files are supported since GTK+ 2.10.

## Methods

### gtk.RecentChooser.set_show_private

        def set_show_private(show_private)

`show_private` : | if `True` show private items

### Note

This method is available in PyGTK 2.10 and above.

Sets the "show-private" property to the value of `show_private`. If `show_private` is `True` show recently used resources marked registered as private.

### gtk.RecentChooser.get_show_private

        def get_show_private()

Returns : | `True` if the recent chooser should show private items.

### Note

This method is available in PyGTK 2.10 and above.

Returns `True` if recently used resources registered as private should be displayed.

### gtk.RecentChooser.set_show_not_found

        def set_show_not_found(show_not_found)

`show_not_found` : | if `True` show the local items we didn't find

### Note

This method is available in PyGTK 2.10 and above.

Sets the "show-not'found" property to the value specified by `show_not_found`. If `show_not_found` is `True`, display the recently used resources that it didn't find. This only applies to local resources.

### gtk.RecentChooser.get_show_not_found

        def get_show_not_found()

Returns : | `True` if the resources not found should be displayed.

### Note

This method is available in PyGTK 2.10 and above.

Returns `True` if the recently used resources that were not found shoudl be shown.

### gtk.RecentChooser.set_select_multiple

        def set_select_multiple(select_multiple)

`select_multiple` : | if `True` more than one item can be selected

### Note

This method is available in PyGTK 2.10 and above.

Sets the "select-multiple" property to the value of `select_multiple`. If `select_mulitple` is `True` multiple items can be selected.

### gtk.RecentChooser.get_select_multiple

        def get_select_multiple()

Returns : | `True` if more than one item can be selected.

### Note

This method is available in PyGTK 2.10 and above.

Returns `True` if multiple items can be selected.

### gtk.RecentChooser.set_limit

        def set_limit(limit)

`limit` : | a positive integer, or -1 for all items

### Note

This method is available in PyGTK 2.10 and above.

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

### gtk.RecentChooser.get_limit

        def get_limit()

Returns : | A positive integer, or -1 meaning that all items are returned.

### Note

This method is available in PyGTK 2.10 and above.

Returns the number of items that can be returned by the `gtk.RecentChooser.get_items()` and `gtk.RecentChooser.get_uris()` methods.

### gtk.RecentChooser.set_local_only

        def set_local_only(local_only)

`local_only` : | if `True` only local files can be shown

### Note

This method is available in PyGTK 2.10 and above.

Sets the "local-only" property to the value of `local_only`. If `local_only` is `True` 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 resources shown are guaranteed to be accessible through the operating system native file system.

### gtk.RecentChooser.get_local_only

        def get_local_only()

Returns : | `True` if only local resources should be shown.

### Note

This method is available in PyGTK 2.10 and above.

Returns `True` if only local resources should be shown in the recently used resources selector. See the `gtk.RecentChooser.set_local_only()` method.

### gtk.RecentChooser.set_show_tips

        def set_show_tips(show_tips)

`show_tips` : | if `True` tooltips should be shown

### Note

This method is available in PyGTK 2.10 and above.

Sets the "show-tips" property to the value of `show_tips`. If `show_tips` is `True`, show a tooltips on the widget.

### gtk.RecentChooser.get_show_tips

        def get_show_tips()

Returns : | `True` if the recent chooser should show tooltips.

### Note

This method is available in PyGTK 2.10 and above.

Returns `True` if tooltips should be displayed.

### gtk.RecentChooser.set_show_numbers

        def set_show_numbers(show_numbers)

`show_numbers` : | if `True` show numbers

### Note

This method is available in PyGTK 2.10 and above.

### Warning

This method is deprecated in PyGTK 2.12 and above and should not be used in newly-written code. Use `gtk.RecentChooserMenu.set_show_numbers`() instead.

Sets the "show-number" property to the value of `show_numbers`. If `show_numbers` is `True`, show recently used resources prepended by a unique number.

### gtk.RecentChooser.get_show_numbers

        def get_show_numbers()

Returns : | `True` if the recent chooser should show display numbers.

### Note

This method is available in PyGTK 2.10 and above.

### Warning

This method is deprecated in PyGTK 2.12 and above and should not be used in newly-written code. Use `gtk.RecentChooserMenu.get_show_numbers`() instead.

Returns `True` if recently used resources should be displayed prepended by a unique number.

### gtk.RecentChooser.set_show_icons

        def set_show_icons(show_icons)

`show_icons` : | if `True` show an icon near the resource

### Note

This method is available in PyGTK 2.10 and above.

Sets the "show-icon" property to the value of `show_icon`. If `show_icon` is `True`, show an icon near the resource when displaying it.

### gtk.RecentChooser.get_show_icons

        def get_show_icons()

Returns : | `True` if the icons should be displayed.

### Note

This method is available in PyGTK 2.10 and above.

Returns `True` if an icon should be shown near the resource.

### gtk.RecentChooser.set_sort_type

        def set_sort_type(sort_type)

`sort_type` : | the sort order that the chooser should use - one of the GTK Recent Sort Type Constants

### Note

This method is available in PyGTK 2.10 and above.

Sets the sorting order of the recently used resources list to the value specified by sort_type which must be one of the GTK Recent Sort Type Constants.

### gtk.RecentChooser.get_sort_type

        def get_sort_type()

Returns : | the sorting order - one of the GTK Recent Sort Type Constants.

### Note

This method is available in PyGTK 2.10 and above.

Returns the value set by the `gtk.RecentChooser.set_sort_type()` method..

### gtk.RecentChooser.set_sort_func

        def set_sort_func(sort_func, sort_data=None)

`sort_func` : | the comparison function
`sort_data` : | user data to pass to `sort_func`, or `None`

### Note

This method is available in PyGTK 2.10 and above.

Sets the comparison function specified by `sort_func` to be used when sorting. If the "sort-type" property is set to `gtk.RECENT_SORT_CUSTOM`, the chooser will sort using this function.

The signature of the comparison function is:

      def sort_func(a, b, data):

where `a` and `b` are two `gtk.RecentInfo` objects and `data` is `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.

### gtk.RecentChooser.set_current_uri

        def set_current_uri(uri)

`uri` : | a URI
Returns : | `True` if the URI was found.

### Note

This method is available in PyGTK 2.10 and above.

Sets `uri` as the current URI. Raises the gobject.GError exception when an error occurs.

### gtk.RecentChooser.get_current_uri

        def get_current_uri()

Returns : | a URI.

### Note

This method is available in PyGTK 2.10 and above.

Returns the currently selected URI.

### gtk.RecentChooser.get_current_item

        def get_current_item()

Returns : | a `gtk.RecentInfo` object.

### Note

This method is available in PyGTK 2.10 and above.

Returns the `gtk.RecentInfo` for the currently selected item.

### gtk.RecentChooser.select_uri

        def select_uri(uri)

`uri` : | a URI
Returns : | `True` if `uri` was found.

### Note

This method is available in PyGTK 2.10 and above.

Selects `uri`. Raises the gobject.GError exception when an error occurs.

### gtk.RecentChooser.unselect_uri

        def unselect_uri(uri)

`uri` : | a URI

### Note

This method is available in PyGTK 2.10 and above.

Unselects `uri`.

### gtk.RecentChooser.select_all

        def select_all()

### Note

This method is available in PyGTK 2.10 and above.

Selects all the items inside `chooser`, if the "select-multiple" property is `True`.

### gtk.RecentChooser.unselect_all

        def unselect_all()

### Note

This method is available in PyGTK 2.10 and above.

Unselects all the items.

### gtk.RecentChooser.get_items

        def get_items()

Returns : | A list of `gtk.RecentInfo` objects.

### Note

This method is available in PyGTK 2.10 and above.

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

### gtk.RecentChooser.get_uris

        def get_uris()

Returns : | A list of strings.

### Note

This method is available in PyGTK 2.10 and above.

Returns a list of the URIs of the recently used resources.

The return value of this function is affected by the "sort-type" and "limit" properties>.

### gtk.RecentChooser.add_filter

        def add_filter(filter)

`filter` : | a `gtk.RecentFilter`

### Note

This method is available in PyGTK 2.10 and above.

Adds `filter` to the list of `gtk.RecentFilter` objects.

If no previous filter objects were defined, this method will call the `gtk.RecentChooser.set_filter()` method.

### gtk.RecentChooser.remove_filter

        def remove_filter(filter)

`filter` : | a `gtk.RecentFilter`

### Note

This method is available in PyGTK 2.10 and above.

Removes `filter` from the list of `gtk.RecentFilter` objects.

### gtk.RecentChooser.list_filters

        def list_filters()

Returns : | A list of `gtk.RecentFilter` objects..

### Note

This method is available in PyGTK 2.10 and above.

Returns a list of the `gtk.RecentFilter` objects.

### gtk.RecentChooser.set_filter

        def set_filter(filter)

`filter` : | a `gtk.RecentFilter`

### Note

This method is available in PyGTK 2.10 and above.

Sets `filter` as the current `gtk.RecentFilter` object used by the recent chooser to filter the displayed recently used resources.

### gtk.RecentChooser.get_filter

        def get_filter()

Returns : | a `gtk.RecentFilter` object.

### Note

This method is available in PyGTK 2.10 and above.

Returns the currently used `gtk.RecentFilter` object.

## Signals

### The "item-activated" gtk.RecentChooser Signal

        def callback(chooser, user_param1, ...)

`chooser` : | the object which received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.10 and above.

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.

### The "selection-changed" gtk.RecentChooser Signal

        def callback(chooser, user_param1, ...)

`chooser` : | the object which received the signal
`user_param1` : | the first user parameter (if any) specified with the `connect`() method
`...` : | additional user parameters (if any)

### Note

This signal is available in GTK+ 2.10 and above.

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 methods to change the selection.

Prev | Up | Next
gtk.RecentChooserWidget | Home | gtk.RecentFilter