|  |  |  | GTK+ 3 Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Implemented Interfaces | ||||
#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);
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().
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 90. 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/*</mime-type> </mime-types> <patterns> <pattern>*.txt</pattern> <pattern>*.png</pattern> </patterns> </object> | 
see_also: GtkFileChooser
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  | Flags indicating which of the following fields need are filled | 
| const gchar * | the filename of the file being tested | 
| const gchar * | the URI for the file being tested | 
| const gchar * | the string that will be used to display the file in the file chooser | 
| const gchar * | the mime type of the file | 
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.
gboolean (*GtkFileFilterFunc) (const GtkFileFilterInfo *filter_info,gpointer data);
The type of function that is used with custom filters, see
gtk_file_filter_add_custom().
Returns: TRUE if the file should be displayed
| 
 | a GtkFileFilterInfo that is filled according
to the neededflags passed togtk_file_filter_add_custom() | 
| 
 | user data passed to gtk_file_filter_add_custom(). [closure] | 
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
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.
| 
 | a GtkFileFilter | 
| 
 | the human-readable-name for the filter, or NULLto remove any existing name. [allow-none] | 
Since 2.4
const gchar *       gtk_file_filter_get_name            (GtkFileFilter *filter);
Gets the human-readable name for the filter. See gtk_file_filter_set_name().
| 
 | 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
void gtk_file_filter_add_mime_type (GtkFileFilter *filter,const gchar *mime_type);
Adds a rule allowing a given mime type to filter.
| 
 | A GtkFileFilter | 
| 
 | name of a MIME type | 
Since 2.4
void gtk_file_filter_add_pattern (GtkFileFilter *filter,const gchar *pattern);
Adds a rule allowing a shell style glob to a filter.
| 
 | a GtkFileFilter | 
| 
 | a shell style glob | 
Since 2.4
void                gtk_file_filter_add_pixbuf_formats  (GtkFileFilter *filter);
Adds a rule allowing image files in the formats supported by GdkPixbuf.
| 
 | a GtkFileFilter | 
Since 2.6
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.
| 
 | a GtkFileFilter | 
| 
 | bitfield of flags indicating the information that the custom filter function needs. | 
| 
 | callback function; if the function returns TRUE, then
the file will be displayed. | 
| 
 | data to pass to func | 
| 
 | function to call to free datawhen it is no longer needed. | 
Since 2.4
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.
| 
 | a GtkFileFilter | 
| Returns : | bitfield of flags indicating needed fields when
calling gtk_file_filter_filter() | 
Since 2.4
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.
| 
 | a GtkFileFilter | 
| 
 | a GtkFileFilterInfo structure containing information about a file. | 
| Returns : | TRUEif the file should be displayed | 
Since 2.4