Class: Gtk::FileFilter

Inherits:
Object
  • Object
show all
Defined in:
(unknown)

Overview

A GtkFileFilter can be used to restrict the files being shown in a Gtk::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 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_file_chooser_add_filter(), but it is also possible to manually use a filter on a file with gtk_file_filter_filter().

# GtkFileFilter as GtkBuildable

The GtkFileFilter implementation of the GtkBuildable 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 as calling gtk_file_filter_add_mime_type() or gtk_file_filter_add_pattern().

An example of a UI definition fragment specifying GtkFileFilter 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> ]|

Instance Method Summary collapse

Instance Method Details

#add_custom(needed, func, data, notify) ⇒ nil

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.

Parameters:

  • needed (Gtk::FileFilterFlags) —

    bitfield of flags indicating the information that the custom filter function needs.

  • func (Gtk::FileFilterFunc) —

    callback function; if the function returns true, then the file will be displayed.

  • data (GObject) —

    data to pass to func

  • notify (GLib::DestroyNotify) —

    function to call to free data when it is no longer needed.

Returns:

  • (nil)

#add_mime_type(mime_type) ⇒ nil

Adds a rule allowing a given mime type to filter.

Parameters:

  • mime_type (String) —

    name of a MIME type

Returns:

  • (nil)

#add_pattern(pattern) ⇒ nil

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

Parameters:

  • pattern (String) —

    a shell style glob

Returns:

  • (nil)

#add_pixbuf_formats ⇒ nil

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

Returns:

  • (nil)

#filter(filter_info) ⇒ TrueClass

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

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

Parameters:

  • filter_info (Gtk::FileFilterInfo) —

    a Gtk::FileFilterInfo containing information about a file.

Returns:

  • (TrueClass) —

    true if the file should be displayed

#name ⇒ String

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

Returns:

  • (String) —

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

#name=(name) ⇒ nil

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.

Parameters:

  • name (String) —

    the human-readable-name for the filter, or nil to remove any existing name.

Returns:

  • (nil)

#needed ⇒ Gtk::FileFilterFlags

Gets the fields that need to be filled in for the Gtk::FileFilterInfo passed to gtk_file_filter_filter()

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

Returns:

  • (Gtk::FileFilterFlags) —

    bitfield of flags indicating needed fields when calling gtk_file_filter_filter()

#new ⇒ Gtk::FileFilter

Creates a new Gtk::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 gtk_file_filter_add_mime_type(), gtk_file_filter_add_pattern(), or gtk_file_filter_add_custom(). To create a filter that accepts any file, use:

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

Returns:

#new_from_gvariant(variant) ⇒ Gtk::FileFilter

Deserialize a file filter from an asv variant in the format produced by gtk_file_filter_to_gvariant().

Parameters:

  • variant (GLib::Variant) —

    an asv #GVariant

Returns:

#to_gvariant ⇒ GLib::Variant

Serialize a file filter to an asv variant.

Returns:

  • (GLib::Variant) —

    a new, floating, #GVariant