GtkFileFilter

GtkFileFilter — A filter for selecting a file subset

Synopsis


#include <gtk/gtk.h>


            GtkFileFilter;
            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
   +----GtkObject
         +----GtkFileFilter

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().

Details

GtkFileFilter

typedef struct _GtkFileFilter GtkFileFilter;

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

GtkFileFilterInfo

typedef struct {
  GtkFileFilterFlags contains;
  
  const gchar *filename;
  const gchar *uri;
  const gchar *display_name;
  const gchar *mime_type;
} GtkFileFilterInfo;

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

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 ()

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

GtkFileFilter

Synopsis

Object Hierarchy

Description

Details

GtkFileFilter

GtkFileFilterInfo

enum GtkFileFilterFlags

GtkFileFilterFunc ()

gtk_file_filter_new ()

gtk_file_filter_set_name ()

gtk_file_filter_get_name ()

gtk_file_filter_add_mime_type ()

gtk_file_filter_add_pattern ()

gtk_file_filter_add_pixbuf_formats ()

gtk_file_filter_add_custom ()

gtk_file_filter_get_needed ()

gtk_file_filter_filter ()

See Also