GtkRecentFilter
3
GTK Library

# GtkRecentFilter

A filter for selecting a subset of recently used files

## Synopsis

    #include <gtk/gtk.h>

                        GtkRecentFilter;
                        GtkRecentFilterInfo;
    enum                GtkRecentFilterFlags;
    gboolean            (*GtkRecentFilterFunc)              (const GtkRecentFilterInfo *filter_info,
                                                             gpointer user_data);
    GtkRecentFilter *   gtk_recent_filter_new               (void);
    const gchar *       gtk_recent_filter_get_name          (GtkRecentFilter *filter);
    void                gtk_recent_filter_set_name          (GtkRecentFilter *filter,
                                                             const gchar *name);
    void                gtk_recent_filter_add_mime_type     (GtkRecentFilter *filter,
                                                             const gchar *mime_type);
    void                gtk_recent_filter_add_pattern       (GtkRecentFilter *filter,
                                                             const gchar *pattern);
    void                gtk_recent_filter_add_pixbuf_formats
                                                            (GtkRecentFilter *filter);
    void                gtk_recent_filter_add_application   (GtkRecentFilter *filter,
                                                             const gchar *application);
    void                gtk_recent_filter_add_group         (GtkRecentFilter *filter,
                                                             const gchar *group);
    void                gtk_recent_filter_add_age           (GtkRecentFilter *filter,
                                                             gint days);
    void                gtk_recent_filter_add_custom        (GtkRecentFilter *filter,
                                                             GtkRecentFilterFlags needed,
                                                             GtkRecentFilterFunc func,
                                                             gpointer data,
                                                             GDestroyNotify data_destroy);
    GtkRecentFilterFlags  gtk_recent_filter_get_needed      (GtkRecentFilter *filter);
    gboolean            gtk_recent_filter_filter            (GtkRecentFilter *filter,
                                                             const GtkRecentFilterInfo *filter_info);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkObject
                   +----GtkRecentFilter

## Description

A GtkRecentFilter can be used to restrict the files being shown in a GtkRecentChooser. 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 GtkRecentFilter 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 GtkRecentChooser, 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.

## Details

### GtkRecentFilter

    typedef struct _GtkRecentFilter GtkRecentFilter;

The GtkRecentFilter struct contains only private fields and should not be directly accessed.

### GtkRecentFilterInfo

    typedef struct {
      GtkRecentFilterFlags contains;

      const gchar *uri;
      const gchar *display_name;
      const gchar *mime_type;
      const gchar **applications;
      const gchar **groups;

      gint age;
    } GtkRecentFilterInfo;

A GtkRecentFilterInfo struct is used to pass information about the tested file to `gtk_recent_filter_filter()`.

GtkRecentFilterFlags contains;

  Flags indicating which of the following fields need are filled

const gchar *uri;

  the URI of the file being tested

const gchar *display_name;

  the string that will be used to display the file in the recent chooser

const gchar *mime_type;

  the mime type of the file

const gchar **applications;

  the list of applications that have registered the file

const gchar **groups;

  the groups to which the file belongs to

gint age;

  the number of days elapsed since the file has been registered

### enum GtkRecentFilterFlags

    typedef enum {
      GTK_RECENT_FILTER_URI          = 1 << 0,
      GTK_RECENT_FILTER_DISPLAY_NAME = 1 << 1,
      GTK_RECENT_FILTER_MIME_TYPE    = 1 << 2,
      GTK_RECENT_FILTER_APPLICATION  = 1 << 3,
      GTK_RECENT_FILTER_GROUP        = 1 << 4,
      GTK_RECENT_FILTER_AGE          = 1 << 5
    } GtkRecentFilterFlags;

These flags indicate what parts of a GtkRecentFilterInfo struct are filled or need to be filled.

`GTK_RECENT_FILTER_URI`

  the URI of the file being tested

`GTK_RECENT_FILTER_DISPLAY_NAME`

  the string that will be used to display the file in the recent chooser

`GTK_RECENT_FILTER_MIME_TYPE`

  the mime type of the file

`GTK_RECENT_FILTER_APPLICATION`

  the list of applications that have registered the file

`GTK_RECENT_FILTER_GROUP`

  the groups to which the file belongs to

`GTK_RECENT_FILTER_AGE`

  the number of days elapsed since the file has been registered

### GtkRecentFilterFunc ()

    gboolean            (*GtkRecentFilterFunc)              (const GtkRecentFilterInfo *filter_info,
                                                             gpointer user_data);

The type of function that is used with custom filters, see `gtk_recent_filter_add_custom()`.

`filter_info` :

  a GtkRecentFilterInfo that is filled according to the `needed` flags passed to `gtk_recent_filter_add_custom()`

`user_data` :

  user data passed to `gtk_recent_filter_add_custom()`

Returns :

  %TRUE if the file should be displayed

### gtk_recent_filter_new ()

    GtkRecentFilter *   gtk_recent_filter_new               (void);

Creates a new GtkRecentFilter 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 :

  a new GtkRecentFilter

Since 2.10

### gtk_recent_filter_get_name ()

    const gchar *       gtk_recent_filter_get_name          (GtkRecentFilter *filter);

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

`filter` :

  a GtkRecentFilter

Returns :

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

Since 2.10

### gtk_recent_filter_set_name ()

    void                gtk_recent_filter_set_name          (GtkRecentFilter *filter,
                                                             const gchar *name);

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.

`filter` :

  a GtkRecentFilter

`name` :

  then human readable name of `filter`

Since 2.10

### gtk_recent_filter_add_mime_type ()

    void                gtk_recent_filter_add_mime_type     (GtkRecentFilter *filter,
                                                             const gchar *mime_type);

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

`filter` :

  a GtkRecentFilter

`mime_type` :

  a MIME type

Since 2.10

### gtk_recent_filter_add_pattern ()

    void                gtk_recent_filter_add_pattern       (GtkRecentFilter *filter,
                                                             const gchar *pattern);

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

`filter` :

  a GtkRecentFilter

`pattern` :

  a file pattern

Since 2.10

### gtk_recent_filter_add_pixbuf_formats ()

    void                gtk_recent_filter_add_pixbuf_formats
                                                            (GtkRecentFilter *filter);

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

`filter` :

  a GtkRecentFilter

Since 2.10

### gtk_recent_filter_add_application ()

    void                gtk_recent_filter_add_application   (GtkRecentFilter *filter,
                                                             const gchar *application);

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

`filter` :

  a GtkRecentFilter

`application` :

  an application name

Since 2.10

### gtk_recent_filter_add_group ()

    void                gtk_recent_filter_add_group         (GtkRecentFilter *filter,
                                                             const gchar *group);

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

`filter` :

  a GtkRecentFilter

`group` :

  a group name

Since 2.10

### gtk_recent_filter_add_age ()

    void                gtk_recent_filter_add_age           (GtkRecentFilter *filter,
                                                             gint days);

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

`filter` :

  a GtkRecentFilter

`days` :

  number of days

Since 2.10

### gtk_recent_filter_add_custom ()

    void                gtk_recent_filter_add_custom        (GtkRecentFilter *filter,
                                                             GtkRecentFilterFlags needed,
                                                             GtkRecentFilterFunc func,
                                                             gpointer data,
                                                             GDestroyNotify data_destroy);

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.

`filter` :

  a GtkRecentFilter

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

`data_destroy` :

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

Since 2.10

### gtk_recent_filter_get_needed ()

    GtkRecentFilterFlags  gtk_recent_filter_get_needed      (GtkRecentFilter *filter);

Gets the fields that need to be filled in for the structure 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 GtkRecentChooser.

`filter` :

  a GtkRecentFilter

Returns :

  bitfield of flags indicating needed fields when calling `gtk_recent_filter_filter()`

Since 2.10

### gtk_recent_filter_filter ()

    gboolean            gtk_recent_filter_filter            (GtkRecentFilter *filter,
                                                             const GtkRecentFilterInfo *filter_info);

Tests whether a file should be displayed according to `filter`. The GtkRecentFilterInfo structure `filter_info` should include the fields returned from `gtk_recent_filter_get_needed()`.

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

`filter` :

  a GtkRecentFilter

`filter_info` :

  a GtkRecentFilterInfo structure containing information about a recently used resource

Returns :

  `TRUE` if the file should be displayed

Since 2.10

## See Also

GtkRecentChooser