gtk.FileFilter

gtk.FileFilter
Prev	The gtk Class Reference	Next

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