GtkFileFilter

## GtkFileFilter GtkFileFilter — A filter for selecting a file subset |

## Synopsis

    #include <gtk/gtk.h>

                        GtkFileFilter;
    struct              GtkFileFilterInfo;
    enum                GtkFileFilterFlags;
    gboolean            (*GtkFileFilterFunc)                (const GtkFileFilterInfo *filter_info,
                                                             gpointer data);
    GtkFileFilter *     gtk_file_filter_new                 (void);
    void                gtk_file_filter_set_name            (GtkFileFilter *filter,
                                                             const gchar *name);
    const gchar *       gtk_file_filter_get_name            (GtkFileFilter *filter);
    void                gtk_file_filter_add_mime_type       (GtkFileFilter *filter,
                                                             const gchar *mime_type);
    void                gtk_file_filter_add_pattern         (GtkFileFilter *filter,
                                                             const gchar *pattern);
    void                gtk_file_filter_add_pixbuf_formats  (GtkFileFilter *filter);
    void                gtk_file_filter_add_custom          (GtkFileFilter *filter,
                                                             GtkFileFilterFlags needed,
                                                             GtkFileFilterFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);
    GtkFileFilterFlags  gtk_file_filter_get_needed          (GtkFileFilter *filter);
    gboolean            gtk_file_filter_filter              (GtkFileFilter *filter,
                                                             const GtkFileFilterInfo *filter_info);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GtkFileFilter

## Implemented Interfaces

GtkFileFilter implements GtkBuildable.

## Description

A GtkFileFilter can be used to restrict the files being shown in a GtkFileChooser. 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 GtkFileFilter 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 GtkFileChooser, 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> is the same as calling `gtk_recent_filter_add_mime_type()` or `gtk_recent_filter_add_pattern()`

Example 91. A UI definition fragment specifying GtkFileFilter rules

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    <object class="GtkFileFilter">
      <mime-types>
        <mime-type>text/plain</mime-type>
        <mime-type>image/&ast;</mime-type>
      </mime-types>
      <patterns>
        <pattern>*.txt</pattern>
        <pattern>*.png</pattern>
      </patterns>
    </object>

## Details

### GtkFileFilter

    typedef struct _GtkFileFilter GtkFileFilter;

### struct GtkFileFilterInfo

    struct GtkFileFilterInfo {
      GtkFileFilterFlags contains;

      const gchar *filename;
      const gchar *uri;
      const gchar *display_name;
      const gchar *mime_type;
    };

A 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
const gchar *`filename`; | the filename of the file being tested
const gchar *`uri`; | the URI for the file being tested
const gchar *`display_name`; | the string that will be used to display the file in the file chooser
const gchar *`mime_type`; | the mime type of the file

### enum GtkFileFilterFlags

    typedef enum {
      GTK_FILE_FILTER_FILENAME     = 1 << 0,
      GTK_FILE_FILTER_URI          = 1 << 1,
      GTK_FILE_FILTER_DISPLAY_NAME = 1 << 2,
      GTK_FILE_FILTER_MIME_TYPE    = 1 << 3
    } GtkFileFilterFlags;

These flags indicate what parts of a GtkFileFilterInfo 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

### GtkFileFilterFunc ()

    gboolean            (*GtkFileFilterFunc)                (const GtkFileFilterInfo *filter_info,
                                                             gpointer data);

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

`filter_info` : | a GtkFileFilterInfo that is filled according to the `needed` flags passed to `gtk_file_filter_add_custom()`
`data` : | user data passed to `gtk_file_filter_add_custom()`. [closure]
Returns : | `TRUE` if the file should be displayed

### gtk_file_filter_new ()

    GtkFileFilter *     gtk_file_filter_new                 (void);

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

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

Returns : | a new GtkFileFilter

Since 2.4

### gtk_file_filter_set_name ()

    void                gtk_file_filter_set_name            (GtkFileFilter *filter,
                                                             const gchar *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.

`filter` : | a GtkFileFilter
`name` : | the human-readable-name for the filter, or `NULL` to remove any existing name. [allow-none]

Since 2.4

### gtk_file_filter_get_name ()

    const gchar *       gtk_file_filter_get_name            (GtkFileFilter *filter);

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

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

Since 2.4

### gtk_file_filter_add_mime_type ()

    void                gtk_file_filter_add_mime_type       (GtkFileFilter *filter,
                                                             const gchar *mime_type);

Adds a rule allowing a given mime type to `filter`.

`filter` : | A GtkFileFilter
`mime_type` : | name of a MIME type

Since 2.4

### gtk_file_filter_add_pattern ()

    void                gtk_file_filter_add_pattern         (GtkFileFilter *filter,
                                                             const gchar *pattern);

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

`filter` : | a GtkFileFilter
`pattern` : | a shell style glob

Since 2.4

### gtk_file_filter_add_pixbuf_formats ()

    void                gtk_file_filter_add_pixbuf_formats  (GtkFileFilter *filter);

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

`filter` : | a GtkFileFilter

Since 2.6

### gtk_file_filter_add_custom ()

    void                gtk_file_filter_add_custom          (GtkFileFilter *filter,
                                                             GtkFileFilterFlags needed,
                                                             GtkFileFilterFunc func,
                                                             gpointer data,
                                                             GDestroyNotify notify);

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.

`filter` : | a GtkFileFilter
`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.

Since 2.4

### gtk_file_filter_get_needed ()

    GtkFileFilterFlags  gtk_file_filter_get_needed          (GtkFileFilter *filter);

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

`filter` : | a GtkFileFilter
Returns : | bitfield of flags indicating needed fields when calling `gtk_file_filter_filter()`

Since 2.4

### gtk_file_filter_filter ()

    gboolean            gtk_file_filter_filter              (GtkFileFilter *filter,
                                                             const GtkFileFilterInfo *filter_info);

Tests whether a file should be displayed according to `filter`. The GtkFileFilterInfo structure `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 GtkFileChooser.

`filter` : | a GtkFileFilter
`filter_info` : | a GtkFileFilterInfo structure containing information about a file.
Returns : | `TRUE` if the file should be displayed

Since 2.4

## See Also

GtkFileChooser