Gtk.FileFilter¶

class — extends Filter, Buildable

Filters files by name or mime type.

GtkFileFilter can be used to restrict the files being shown in a file chooser. Files can be filtered based on their name (with FileFilter.add_pattern or FileFilter.add_suffix) or on their mime type (with FileFilter.add_mime_type).

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 GtkFileFilter allows wildcards for the subtype of a mime type, so you can e.g. filter for image/*.

Normally, file filters are used by adding them to a file chooser (see FileDialog.set_filters), but it is also possible to manually use a file filter on any FilterListModel containing GFileInfo objects.

GtkFileFilter as GtkBuildable¶

The GtkFileFilter implementation of the GtkBuildable interface supports adding rules using the <mime-types> and <patterns> and <suffixes> elements and listing the rules within. Specifying a <mime-type> or <pattern> or <suffix> has the same effect as as calling FileFilter.add_mime_type or FileFilter.add_pattern or FileFilter.add_suffix.

An example of a UI definition fragment specifying GtkFileFilter rules:

<object class="GtkFileFilter">
  <property name="name" translatable="yes">Text and Images</property>
  <mime-types>
    <mime-type>text/plain</mime-type>
    <mime-type>image/ *</mime-type>
  </mime-types>
  <patterns>
    <pattern>*.txt</pattern>
  </patterns>
  <suffixes>
    <suffix>png</suffix>
  </suffixes>
</object>

Constructors¶

new¶

@classmethod
def new(cls) -> FileFilter

Creates a new GtkFileFilter with no rules added to it.

Such a filter doesn’t accept any files, so is not particularly useful until you add rules with FileFilter.add_mime_type, FileFilter.add_pattern, FileFilter.add_suffix or FileFilter.add_pixbuf_formats.

To create a filter that accepts any file, use:

GtkFileFilter *filter = gtk_file_filter_new ();
gtk_file_filter_add_pattern (filter, "*");

new_from_gvariant¶

@classmethod
def new_from_gvariant(cls, variant: GLib.Variant) -> FileFilter

Deserialize a file filter from a GVariant.

The variant must be in the format produced by FileFilter.to_gvariant.

Parameters:

variant — an a{sv} GVariant

Methods¶

add_mime_type¶

def add_mime_type(self, mime_type: str) -> None

Adds a rule allowing a given mime type.

Parameters:

mime_type — name of a MIME type

add_mime_types¶

def add_mime_types(self, mime_types: list[str]) -> None

Adds a rule allowing a given array of mime types. It can for example be used with Gly.Loader.get_mime_types.

This is equivalent to calling FileFilter.add_mime_type for all the supported mime types.

Parameters:

mime_types — a None-terminated array of mime types

add_pattern¶

def add_pattern(self, pattern: str) -> None

Adds a rule allowing a shell style glob pattern.

Note that it depends on the platform whether pattern matching ignores case or not. On Windows, it does, on other platforms, it doesn't.

Parameters:

pattern — a shell style glob pattern

add_pixbuf_formats¶

def add_pixbuf_formats(self) -> None

:::warning Deprecated since 4.20 This API is deprecated. :::

Adds a rule allowing image files in the formats supported by GdkPixbuf.

This is equivalent to calling FileFilter.add_mime_type for all the supported mime types.

add_suffix¶

def add_suffix(self, suffix: str) -> None

Adds a suffix match rule to a filter.

This is similar to adding a match for the pattern "*.suffix"

An exaple to filter files with the suffix ".sub":

gtk_file_filter_add_suffix (filter, "sub");

Filters with multiple dots are allowed.

In contrast to pattern matches, suffix matches are always case-insensitive.

Parameters:

suffix — filename suffix to match

get_attributes¶

def get_attributes(self) -> list[str]

Gets the attributes that need to be filled in for the GFileInfo passed to this filter.

This function will not typically be used by applications; it is intended for use in file chooser implementation.

get_name¶

def get_name(self) -> str | None

Gets the human-readable name for the filter.

See FileFilter.set_name.

set_name¶

def set_name(self, name: str | None = ...) -> None

Sets a human-readable name of the filter.

This is the string that will be displayed in the user interface if there is a selectable list of filters.

Parameters:

name — the human-readable name for the filter

to_gvariant¶

def to_gvariant(self) -> GLib.Variant

Serialize a file filter to an a{sv} variant.

Properties¶

mime_types¶

mime_types: list[str]  # read/write

The MIME types that this filter matches.

name¶

name: str  # read/write

The human-readable name of the filter.

This is the string that will be displayed in the user interface if there is a selectable list of filters.

patterns¶

patterns: list[str]  # read/write

The patterns that this filter matches.

suffixes¶

suffixes: list[str]  # read/write

The suffixes that this filter matches.