## GtkFileFilter

GtkFileFilter — A filter for selecting a file subset

## Synopsis

    #include <gtk/gtk.h>

    struct      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);
    G_CONST_RETURN 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_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
       +----GtkObject
             +----GtkFileFilter

## Description

## Details

### struct GtkFileFilter

    struct GtkFileFilter;

### struct GtkFileFilterInfo

    struct GtkFileFilterInfo {

      GtkFileFilterFlags contains;

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

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

### GtkFileFilterFunc ()

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

`filter_info` : |
`data` : |
Returns : |

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

    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.

Since 2.4

### gtk_file_filter_get_name ()

    G_CONST_RETURN 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_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 feom `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