GTK+ Reference Manual |
---|
GtkFileFilterGtkFileFilter — A filter for selecting a file subset |
#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);
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().
typedef struct _GtkFileFilter GtkFileFilter;
The GtkFileFilter struct contains only private fields and should not be directly accessed.
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 |
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 |
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 |
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
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
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
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
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
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
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
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
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
<< GtkFileChooserWidget | GtkFontButton >> |