gtk.FileFilter
Prev | The gtk Class Reference | Next

## gtk.FileFilter

gtk.FileFilter — a filter for selecting a file subset (new in PyGTK 2.4)

## Synopsis

    class gtk.FileFilter(gtk.Object):
        gtk.FileFilter()
        def set_name(name)
        def get_name()
        def add_mime_type(mime_type)
        def add_pattern(pattern)
        def add_custom(needed, func, data)
        def get_needed()
        def filter(filter_info)
        def add_pixbuf_formats()

## Ancestry

    +-- gobject.GObject
      +-- gtk.Object
        +-- gtk.FileFilter

## gtk.FileFilter Properties

gtk.Object Properties

## gtk.FileFilter Signal Prototypes

gobject.GObject Signal Prototypes

gtk.Object Signal Prototypes

## Description

### Note

This widget is available in PyGTK 2.4 and above.

A `gtk.FileFilter` is an object that filters files based on a set of rules that it contains. The categories of information that `gtk.FileFilter` uses to accept or reject the file are given by the GTK FileFilter Flags Constants:

`gtk.FILE_FILTER_FILENAME` | The full path name of the file.
`gtk.FILE_FILTER_URI` | The URI of the file.
`gtk.FILE_FILTER_DISPLAY_NAME` | The simple name of the file as displayed in a file chooser.
`gtk.FILE_FILTER_MIME_TYPE` | The MIME type of the file.

The `add_pattern`() method adds a rule that only uses the display name (`gtk.FILE_FILTER_DISPLAY_NAME`) for filtering. The `add_mime_type`() method adds a rule that only uses the mime type (`gtk.FILE_FILTER_MIME_TYPE`) for filtering. To use the file URI (`gtk.FILE_FILTER_URI`) or filename (`gtk.FILE_FILTER_FILENAME`) you have to create a custom filter rule using a callback function that is registered with the `add_custom`() method.

The pattern rule uses file globbing to match the file display name:

- '*' matches any combination of characters e.g.. "a*c" matches "abc", "a bridge tic", "aaabbbc" and so on.
- '?' matches any single character e.g. "a?c" matches "abc", aZc" and so on but not "abbc".
- '[' and ']' enclose a set of characters that can be matched; ranges of characters can be included by separating the start and end with a dash (e.g. "a-z" include all the lowercase letters). e.g. "a[0-9]c" matches "a3c" and "a9c" but not "a28c" or "abc".
- '\' escapes the next character to allow "*", "?", "[" and "]" to be matched literally.

The MIME type requires an exact match (no pattern matching).

## Constructor

        gtk.FileFilter()

Returns : | a new `gtk.FileFilter`

### Note

This constructor is available in PyGTK 2.4 and above.

Creates a new `gtk.FileFilter` with no rules added to it. Such a filter doesn't pass any files, so it's not particularly useful until you add rules with the `add_mime_type()`, `add_pattern()` or `add_custom()` methods. To create a filter that accepts any file, use:

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

## Methods

### gtk.FileFilter.set_name

        def set_name(name)

`name` : | the human-readable-name for the filter.

### Note

This method is available in PyGTK 2.4 and above.

The `set_name`() method sets the human-readable name of the filter to the string in `name`. The string in `name` will be displayed in the file chooser user interface if there is a selectable list of filters.

### gtk.FileFilter.get_name

        def get_name()

Returns : | The human-readable name of the filter, or `None`.

### Note

This method is available in PyGTK 2.4 and above.

The `get_name`() method returns the human-readable name for the filter or `None` if the name has not been set. See the `set_name()` method.

### gtk.FileFilter.add_mime_type

        def add_mime_type(mime_type)

`mime_type` : | the name of a MIME type

### Note

This method is available in PyGTK 2.4 and above.

The `add_mime_type`() method adds a rule allowing the mime type specified by `mime_type` to be matched. Sets the needs value to `gtk.FILE_FILTER_MIME_TYPE` (see the `get_needed`() method for more information).

### gtk.FileFilter.add_pattern

        def add_pattern(pattern)

`pattern` : | a shell style glob pattern

### Note

This method is available in PyGTK 2.4 and above.

The `add_pattern`() method adds a rule allowing the shell style glob pattern specified by `pattern` to filter file names. Sets the needs value to `gtk.FILE_FILTER_DISPLAY_NAME` (see the `get_needed`() method for more information).

The pattern rule uses file globbing to match the file display name:

- '*' matches any combination of characters e.g.. "a*c" matches "abc", "a bridge tic", "aaabbbc" and so on.
- '?' matches any single character e.g. "a?c" matches "abc", aZc" and so on but not "abbc".
- '[' and ']' enclose a set of characters that can be matched; ranges of characters can be included by separating the start and end with a dash (e.g. "a-z" include all the lowercase letters). e.g. "a[0-9]c" matches "a3c" and "a9c" but not "a28c" or "abc".
- '\' escapes the next character to allow "*", "?", "[" and "]" to be matched literally.

### gtk.FileFilter.add_custom

        def add_custom(needed, func, data)

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

### Note

This method is available in PyGTK 2.4 and above.

The `add_custom`() method adds a rule to a filter that allows files to be filtered based on a custom callback function specified by `func`. The bitfield `needed` provides information about what sorts of information that the filter function needs; this allows GTK+ to avoid retrieving expensive information when it isn't needed by the filter. `needed` is a combination of:

`gtk.FILE_FILTER_FILENAME` | The full path name of the file.
`gtk.FILE_FILTER_URI` | The URI of the file.
`gtk.FILE_FILTER_DISPLAY_NAME` | The simple name of the file as displayed in a file chooser.
`gtk.FILE_FILTER_MIME_TYPE` | The MIME type of the file.

The signature of `func` is:

      def filefilterfunction(filter_info, data):

where `filter_info` is a 4-tuple where each item is either a string or `None`. The strings correspond to: the full pathname of the file, the URI of the file, the display name of the file and the MIME type of the file. `data` is the value passed in as the `data` parameter in the `add_custom`() method. Using a custom filter function is the only way to filter files based on file URIs or full file pathnames.

### gtk.FileFilter.get_needed

        def get_needed()

Returns : | a bitfield of flags indicating the needed fields when calling `filter()`

### Note

This method is available in PyGTK 2.4 and above.

The `get_needed`() method returns the information that is needed by the `gtk.FileFilter` to filter the file info using the `filter()`

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

### gtk.FileFilter.filter

        def filter(filter_info)

`filter_info` : | a 4-tuple containing the information about a file.
Returns : | `True` if the file should be displayed

### Note

This method is available in PyGTK 2.4 and above.

The `filter`() method tests whether a file should be displayed according to the file filter rules. The 4-tuple `filter_info` should include the fields returned from the `get_needed()` method:

- the full pathname of the file if needs includes `gtk.FILE_FILTER_FILENAME`
- the URI of the file is needs includes `gtk.FILE_FILTER_URI`
- the display name (without the path) if the file if needs includes `gtk.FILE_FILTER_DISPLAY_NAME`
- the MIME type of the file if needs includes `gtk.FILE_FILTER_MIME_TYPE`

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

### gtk.FileFilter.add_pixbuf_formats

        def add_pixbuf_formats()

### Note

This method is available in PyGTK 2.6 and above.

The `add_pixbuf_formats`() method adds a rule allowing image files in the formats supported by `gtk.gdk.Pixbuf`.

Prev | Up | Next
gtk.FileChooserWidget | Home | gtk.FileSelection