Gtk.FileFilter

Gtk.FileFilter — A filter for selecting a file subset

Object Hierarchy:

    GObject
    ╰── GInitiallyUnowned
        ╰── Gtk.FileFilter

Functions:

• new () -> Gtk.FileFilter
• set_name (self, name:str=None)
• get_name (self) -> str
• add_mime_type (self, mime_type:str)
• add_pattern (self, pattern:str)
• add_pixbuf_formats (self)
• add_custom (self, needed:Gtk.FileFilterFlags, func:Gtk.FileFilterFunc, data=None)
• get_needed (self) -> Gtk.FileFilterFlags
• filter (self, filter_info:Gtk.FileFilterInfo) -> bool

Description:

A Gtk.FileFilter can be used to restrict the files being shown in a Gtk.FileChooser. Files can be filtered based on their name (with Gtk.FileFilter::add_pattern()), on their mime type (with Gtk.FileFilter::add_mime_type()), or by a custom filter function (with Gtk.FileFilter::add_custom()).

Filtering by mime types 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.FileFilter 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.FileChooser, see Gtk.FileChooser::add_filter(), but it is also possible to manually use a filter on a file with Gtk.FileFilter::filter().

Example of add filters:

    def add_filters(self, dialog):                        
        filter_text = Gtk.FileFilter()
        filter_text.set_name("Text files")
        filter_text.add_mime_type("text/plain")
        dialog.add_filter(filter_text)

        filter_any = Gtk.FileFilter()
        filter_any.set_name("Any files")
        filter_any.add_pattern("*")
        dialog.add_filter(filter_any)

Gtk.FileFilter as GtkBuildable

The Gtk.FileFilter implementation of the GtkBuildable interface supports adding rules using the \, \ and \ elements and listing the rules within. Specifying a \ or \ has the same effect as as calling Gtk.FileFilter::add_mime_type() or Gtk.FileFilter::add_pattern().

• An example of a UI definition fragment specifying Gtk.FileFilter:

<object class="GtkFileFilter">
  <mime-types>
    <mime-type>text/plain</mime-type>
    <mime-type>image/ *</mime-type>
  </mime-types>
  <patterns>
    <pattern>*.txt</pattern>
    <pattern>*.png</pattern>
  </patterns>
</object>

Function Details:

new()

new () -> Gtk.FileFilter

Creates a new Gtk.FileFilter with no rules added to it.Such a filter doesn’t accept any files, so is notparticularly useful until you add rules withGtk.FileFilter:add_mime_type(), Gtk.FileFilter:add_pattern(),or Gtk.FileFilter:add_custom(). To create a filterthat accepts any file, use: Gtk.FileFilter filter = Gtk.FileFilter:new ();Gtk.FileFilter:add_pattern (filter, "");

• Returns: a new Gtk.FileFilter

• Since: 2.4

set_name()

set_name (self, name:str=None)

Sets the human-readable name of the filter; this is the stringthat will be displayed in the file selector user interface ifthere is a selectable list of filters.

• Since: 2.4

get_name()

get_name (self) -> str

Gets the human-readable name for the filter. See Gtk.FileFilter:set_name().

• Returns: The human-readable name of the filter,or None. This value is owned by GTK+ and must notbe modified or freed.

• Since: 2.4

add_mime_type()

add_mime_type (self, mime_type:str)

Adds a rule allowing a given mime type to filter.

• Since: 2.4

add_pattern()

add_pattern (self, pattern:str)

Adds a rule allowing a shell style glob to a filter.

• Since: 2.4

add_pixbuf_formats()

add_pixbuf_formats (self)

Adds a rule allowing image files in the formats supportedby GdkPixbuf.

• Since: 2.6

add_custom()

add_custom (self, needed:Gtk.FileFilterFlags, func:Gtk.FileFilterFunc, data=None)

Adds rule to a filter that allows files based on a custom callbackfunction. The bitfield needed which is passed in provides informationabout what sorts of information that the filter function needs;this allows GTK+ to avoid retrieving expensive information whenit isn’t needed by the filter.

• Since: 2.4

get_needed()

get_needed (self) -> Gtk.FileFilterFlags

Gets the fields that need to be filled in for the Gtk.FileFilterInfopassed to Gtk.FileFilter:filter() This function will not typically be used by applications; itis intended principally for use in the implementation ofGtk.FileChooser.

• Returns: bitfield of flags indicating needed fields whencalling Gtk.FileFilter:filter()

• Since: 2.4

filter()

filter (self, filter_info:Gtk.FileFilterInfo) -> bool

Tests whether a file should be displayed according to filter.The Gtk.FileFilterInfo filter_info should includethe fields returned from Gtk.FileFilter:get_needed(). This function will not typically be used by applications; itis intended principally for use in the implementation ofGtk.FileChooser.

• Returns: True if the file should be displayed

• Since: 2.4

Example:

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk

class FileFilter(Gtk.FileChooserDialog):
    def __init__(self):
        Gtk.FileChooserDialog.__init__(self)
        self.set_title("FileFilter")
        self.add_button("_Cancel", Gtk.ResponseType.CLOSE)
        self.add_button("_Open", Gtk.ResponseType.OK)
        self.connect("response", self.on_response)

        filefilter = Gtk.FileFilter()
        filefilter.set_name("All Items")
        filefilter.add_pattern("*")
        self.add_filter(filefilter)

        filefilter = Gtk.FileFilter()
        filefilter.set_name("Audio")
        filefilter.add_mime_type("audio/flac")
        filefilter.add_mime_type("audio/ogg")
        self.add_filter(filefilter)

        filefilter = Gtk.FileFilter()
        filefilter.set_name("Images")
        filefilter.add_pattern("*.png")
        filefilter.add_pattern("*.jpg")
        filefilter.add_pattern("*.bmp")
        self.add_filter(filefilter)

    def on_response(self, filechooserdialog, response):
        filechooserdialog.destroy()

dialog = FileFilter()
dialog.run()