A filter for selecting a file subset

Description

A Gnome::Gtk3::FileFilter can be used to restrict the files being shown in a Gnome::Gtk3::FileChooser. Files can be filtered based on their name (with gtk_file_filter_add_pattern()), on their mime type (with gtk_file_filter_add_mime_type()), or by a custom filter function (with gtk_file_filter_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 Gnome::Gtk3::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 Gnome::Gtk3::FileChooser, see gtk_file_chooser_add_filter(), but it is also possible to manually use a filter on a file with gtk_file_filter_filter().

Gnome::Gtk3::FileFilter as Gnome::Gtk3::Buildable

The Gnome::Gtk3::FileFilter implementation of the Gnome::Gtk3::Buildable interface supports adding rules using the <mime-types>, <patterns> and <applications> elements and listing the rules within. Specifying a <mime-type> or <pattern> has the same effect as calling gtk_file_filter_add_mime_type() or gtk_file_filter_add_pattern().

An example of a UI definition fragment specifying Gnome::Gtk3::FileFilter rules:

<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>

See Also

Gnome::Gtk3::FileChooser

Synopsis

Declaration

unit class Gnome::Gtk3::FileFilter;
also is Gnome::GObject::InitiallyUnowned;
also does Gnome::Gtk3::Buildable;

Uml Diagram

Types

enum GtkFileFilterFlags

These flags indicate what parts of a Gnome::Gtk3::FileFilterInfo struct are filled or need to be filled.

• GTK_FILE_FILTER_FILENAME: the filename of the file being tested

• GTK_FILE_FILTER_URI: the URI for the file being tested

• GTK_FILE_FILTER_DISPLAY_NAME: the string that will be used to display the file in the file chooser

• GTK_FILE_FILTER_MIME_TYPE: the mime type of the file

class N-GtkFileFilterInfo

A N-GtkFileFilterInfo-struct is used to pass information about the tested file to gtk_file_filter_filter().

• GtkFileFilterFlags $.contains: Flags indicating which of the following fields need are filled

• Str $.filename: the filename of the file being tested

• Str $.uri: the URI for the file being tested

• Str $.display_name: the string that will be used to display the file in the file chooser

• Str $.mime_type: the mime type of the file

Methods

new

default, no options

Create a new plain object.

multi method new ( )

:variant

Deserialize a file filter from an a{sv} variant in the format produced by to_gvariant().

multi method new ( N-GObject :$variant! )

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-GObject :$native-object! )

:build-id

Create an object using a native object from a builder. See also Gnome::GObject::Object.

multi method new ( Str :$build-id! )

add-custom

Adds rule to a filter that allows files based on a custom callback function. The bitfield needed which is passed in 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.

method add-custom ( GtkFileFilterFlags $needed, GtkFileFilterFunc $func, Pointer $data, GDestroyNotify $notify )

• $needed; bitfield of 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

• $notify; function to call to free data when it is no longer needed.

add-mime-type

Adds a rule allowing a given mime type to filter.

method add-mime-type ( Str $mime_type )

• $mime_type; name of a MIME type

add-pattern

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

method add-pattern ( Str $pattern )

• $pattern; a shell style glob

add-pixbuf-formats

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

method add-pixbuf-formats ( )

filter

Tests whether a file should be displayed according to filter. The Gnome::Gtk3::FileFilterInfo filter_info should include the fields returned from get_needed().

This function will not typically be used by applications; it is intended principally for use in the implementation of Gnome::Gtk3::FileChooser.

Returns: True if the file should be displayed

method filter ( GtkFileFilterInfo $filter_info --> Bool )

• $filter_info; a Gnome::Gtk3::FileFilterInfo containing information about a file.

get-name

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

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

method get-name ( --> Str )

get-needed

Gets the fields that need to be filled in for the Gnome::Gtk3::FileFilterInfo passed to filter()

This function will not typically be used by applications; it is intended principally for use in the implementation of Gnome::Gtk3::FileChooser.

Returns: bitfield of flags indicating needed fields when calling filter()

method get-needed ( --> GtkFileFilterFlags )

set-name

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

method set-name ( Str $name )

• $name; the human-readable-name for the filter, or undefined to remove any existing name.

to-gvariant

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

Returns: a new, floating, Gnome::Glib::Variant

method to-gvariant ( --> N-GObject )

_gtk_file_filter_new

Creates a new Gnome::Gtk3::FileFilter with no rules added to it. Such a filter doesn’t accept any files, so is not particularly useful until you add rules with add_mime_type(), add_pattern(), or add_custom(). To create a filter that accepts any file, use: |[<!-- language="C" --> GtkFileFilter *filter = new(); add_pattern (filter, "*"); ]|

Returns: a new Gnome::Gtk3::FileFilter

method _gtk_file_filter_new ( --> N-GObject )

_gtk_file_filter_new_from_gvariant

Deserialize a file filter from an a{sv} variant in the format produced by to_gvariant().

Returns: a new Gnome::Gtk3::FileFilter object

method _gtk_file_filter_new_from_gvariant ( N-GObject() $variant --> N-GObject )

• $variant; an a{sv} Gnome::Gio::Variant