gtk.RecentFilter
Prev | The gtk Class Reference | Next

## gtk.RecentFilter

gtk.RecentFilter — A filter for selecting a subset of recently used files (new in PyGTK 2.10)

## Synopsis

    class gtk.RecentFilter(gtk.Object):
        gtk.RecentFilter()
        def set_name(name)
        def get_name()
        def add_mime_type(mime_type)
        def add_pattern(pattern)
        def add_pixbuf_formats()
        def add_application(application)
        def add_group(group)
        def add_age(days)
        def add_custom(needed, func, data)
        def get_needed()
        def filter(filter_info)

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.RecentFilter

## gtk.RecentFilter Properties

gtk.Object Properties

## gtk.RecentFilter Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

## Description

A `gtk.RecentFilter` can be used to restrict the files being shown in a `gtk.RecentChooser`. Files can be filtered based on their name (with the `gtk.RecentFilter.add_pattern()` method), on their mime type (with the `gtk.FileFilter.add_mime_type()` method), on the application that has registered them (with the `gtk.RecentFilter.add_application()` method), or by a custom filter function (with the `gtk.RecentFilter.add_custom()` method).

Filtering by mime type handles aliasing and subclassing of mime types; e.g. a filter for "text/plain" also matches a file with mime type "application/rtf", since "application/rtf" is a subclass of "text/plain". Note that `gtk.RecentFilter` allows wildcards for the subtype of a mime type, so you can e.g. filter for "image/*".

Normally, filters are used by adding them to a `gtk.RecentChooser`, see the `gtk.RecentChooser.add_filter()` method, but it is also possible to manually use a filter on a file with the `gtk.RecentFilter.filter()` method.

Recently used files are supported since GTK+ 2.10.

## Constructor

### gtk.RecentFilter

        gtk.RecentFilter()

Returns : | a new `gtk.RecentFilter`

### Note

This constructor is available in PyGTK 2.10 and above.

Creates a new `gtk.RecentFilter` with no rules added to it. Such a filter does not accept any recently used resources, so is not particularly useful until you add rules with the `gtk.RecentFilter.add_pattern()`, `gtk.RecentFilter.add_mime_type()`, `gtk.RecentFilter.add_application()`, `gtk.RecentFilter.add_age()` methods. To create a filter that accepts any recently used resource, use:

          filter = gtk.RecentFilter()
          filter.add_pattern("*")

## Methods

### gtk.RecentFilter.set_name

        def set_name(name)

`name` : | the human readable name

### Note

This method is available in PyGTK 2.10 and above.

Sets the human-readable name of the filter; this is the string that will be displayed in the recently used resources selector user interface if there is a selectable list of filters.

### gtk.RecentFilter.get_name

        def get_name()

Returns : | the name of the filter, or `None`.

### Note

This method is available in PyGTK 2.10 and above.

Returns the human-readable name for the filter. See the `gtk.RecentFilter.set_name()` method.

### gtk.RecentFilter.add_mime_type

        def add_mime_type(mime_type)

`mime_type` : | a MIME type

### Note

This method is available in PyGTK 2.10 and above.

Adds a rule that filters resources based on their registered MIME type.

### gtk.RecentFilter.add_pattern

        def add_pattern(pattern)

`pattern` : | a file pattern

### Note

This method is available in PyGTK 2.10 and above.

Adds a rule that filters resources based on a pattern matching their display name.

### gtk.RecentFilter.add_pixbuf_formats

        def add_pixbuf_formats()

### Note

This method is available in PyGTK 2.10 and above.

Adds a rule that filters image files based on the formats supported by `gtk.gdk.Pixbuf`.

### gtk.RecentFilter.add_application

        def add_application(application)

`application` : | an application name

### Note

This method is available in PyGTK 2.10 and above.

Adds a rule that filters resources based on the name of the application that has registered them.

### gtk.RecentFilter.add_group

        def add_group(group)

`group` : | a group name

### Note

This method is available in PyGTK 2.10 and above.

Adds a rule that filters resources based on the name of the group to which they belong

### gtk.RecentFilter.add_age

        def add_age(days)

`days` : | number of days

### Note

This method is available in PyGTK 2.10 and above.

Adds a rule that filters resources based on their age - that is, the number of days elapsed since they were last modified.

### gtk.RecentFilter.add_custom

        def add_custom(needed, func, data)

`needed` : | a combination of the GTK Recent Filter Flags indicating the information that the custom filter function needs.
`func` : | callback function; if the function returns `True`, then the file will be displayed.
`data` : | data to pass to `func`

### Note

This method is available in PyGTK 2.10 and above.

Adds a rule to a filter that filters resources based on a custom callback function. `needed` is a combination of the GTK Recent Filter Flags which provides information about what sorts of information that the filter function needs; this allows PyGTK to avoid retrieving expensive information when it isn't needed by the filter.

The signature of the filter function is:

      def func(filterinfo, user_data):

where `filterinfo` is a dict containing the info requested by `needed` as key-value pairs and `user_data` is `data`. The possible `filterinfo` keys are: "uri", "display_name", "mime_type", "applications", "age" and "groups".

### gtk.RecentFilter.get_needed

        def get_needed()

Returns : | a combination of the GTK Recent Filter Flags indicating what fields are used for filtering when calling the `gtk.RecentFilter.filter()` method

### Note

This method is available in PyGTK 2.10 and above.

Returns a combination of the GTK Recent Filter Flags indicating what fields are used for filtering.

This method will not typically be used by applications; it is intended principally for use in the implementation of `gtk.RecentChooser`.

### gtk.RecentFilter.filter

        def filter(filter_info)

`filter_info` : | a filter info dict containing information about a recently used resource
Returns : | `True` if the file should be displayed

### Note

This method is available in PyGTK 2.10 and above.

Returns `True` if a file should be displayed. `filter_info` is a dict that should include the key-value pairs as specified by the return flags from the `gtk.RecentFilter.get_needed()` method. The possible `filter_info` keys are: "uri", "display_name", "mime_type", "applications", "age" and "groups".

This method will not typically be used by applications; it is intended principally for use in the implementation of `gtk.RecentChooser`.

Prev | Up | Next
gtk.RecentChooser | Home | gtk.RecentInfo