Class: Gtk::RecentFilter

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

Overview

A Gtk::RecentFilter can be used to restrict the files being shown in a Gtk::RecentChooser. Files can be filtered based on their name (with gtk_recent_filter_add_pattern()), on their mime type (with gtk_file_filter_add_mime_type()), on the application that has registered them (with gtk_recent_filter_add_application()), or by a custom filter function (with gtk_recent_filter_add_custom()).

Filtering by mime type 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::RecentFilter 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::RecentChooser, see gtk_recent_chooser_add_filter(), but it is also possible to manually use a filter on a file with gtk_recent_filter_filter().

Recently used files are supported since GTK+ 2.10.

## GtkRecentFilter as GtkBuildable

The GtkRecentFilter 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>, <pattern> or <application> has the same effect as calling gtk_recent_filter_add_mime_type(), gtk_recent_filter_add_pattern() or gtk_recent_filter_add_application().

An example of a UI definition fragment specifying GtkRecentFilter rules: |[ <object class=“GtkRecentFilter”>

<mime-types>
  <mime-type>text/plain</mime-type>
  <mime-type>image/png</mime-type>
</mime-types>
<patterns>
  <pattern>*.txt</pattern>
  <pattern>*.png</pattern>
</patterns>
<applications>
  <application>gimp</application>
  <application>gedit</application>
  <application>glade</application>
</applications>

</object> ]|

Instance Method Summary collapse

Instance Method Details

#add_age(days) ⇒ nil

Adds a rule that allows resources based on their age - that is, the number of days elapsed since they were last modified.

Parameters:

  • days (Integer)

    number of days

Returns:

  • (nil)

#add_application(application) ⇒ nil

Adds a rule that allows resources based on the name of the application that has registered them.

Parameters:

  • application (String)

    an application name

Returns:

  • (nil)

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

Adds a rule to a filter that allows resources 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::RecentFilterFlags)

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

  • func (Gtk::RecentFilterFunc)

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

  • data (GObject)

    data to pass to func

  • data_destroy (GLib::DestroyNotify)

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

Returns:

  • (nil)

#add_group(group) ⇒ nil

Adds a rule that allows resources based on the name of the group to which they belong

Parameters:

  • group (String)

    a group name

Returns:

  • (nil)

#add_mime_type(mime_type) ⇒ nil

Adds a rule that allows resources based on their registered MIME type.

Parameters:

  • mime_type (String)

    a MIME type

Returns:

  • (nil)

#add_pattern(pattern) ⇒ nil

Adds a rule that allows resources based on a pattern matching their display name.

Parameters:

  • pattern (String)

    a file pattern

Returns:

  • (nil)

#add_pixbuf_formatsnil

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::RecentFilterInfo filter_info should include the fields returned from gtk_recent_filter_get_needed(), and must set the Gtk::RecentFilterInfo.contains field of filter_info to indicate which fields have been set.

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

Parameters:

  • filter_info (Gtk::RecentFilterInfo)

    a Gtk::RecentFilterInfo containing information about a recently used resource

Returns:

  • (TrueClass)

    true if the file should be displayed

#nameString

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

Returns:

  • (String)

    the name of the filter, or nil. The returned string is owned by the filter object and should not be freed.

#name=(name) ⇒ nil

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

Parameters:

  • name (String)

    then human readable name of filter

Returns:

  • (nil)

#neededGtk::RecentFilterFlags

Gets the fields that need to be filled in for the Gtk::RecentFilterInfo passed to gtk_recent_filter_filter()

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

Returns:

  • (Gtk::RecentFilterFlags)

    bitfield of flags indicating needed fields when calling gtk_recent_filter_filter()

#newGtk::RecentFilter

Creates a new Gtk::RecentFilter with no rules added to it. Such filter does not accept any recently used resources, so is not particularly useful until you add rules with gtk_recent_filter_add_pattern(), gtk_recent_filter_add_mime_type(), gtk_recent_filter_add_application(), gtk_recent_filter_add_age(). To create a filter that accepts any recently used resource, use:

GtkRecentFilter *filter = gtk_recent_filter_new ();
gtk_recent_filter_add_pattern (filter, "*");

Returns: