GtkFileFilter

GtkFileFilter — A filter for selecting a file subset

Functions

gboolean (*GtkFileFilterFunc) ()
GtkFileFilter * gtk_file_filter_new ()
void gtk_file_filter_set_name ()
const gchar * gtk_file_filter_get_name ()
void gtk_file_filter_add_mime_type ()
void gtk_file_filter_add_pattern ()
void gtk_file_filter_add_pixbuf_formats ()
void gtk_file_filter_add_custom ()
GtkFileFilterFlags gtk_file_filter_get_needed ()
gboolean gtk_file_filter_filter ()

Types and Values

  GtkFileFilter
struct GtkFileFilterInfo
enum GtkFileFilterFlags

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkObject
            ╰── GtkFileFilter

Includes

#include <gtk/gtk.h>

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

Functions

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

Parameters

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:

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.

Parameters

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

Parameters

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 .

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

filter

a GtkFileFilter

  

filter_info

a GtkFileFilterInfo structure containing information about a file.

  

Returns

TRUE if the file should be displayed

Since 2.4

Types and Values

GtkFileFilter

typedef struct _GtkFileFilter GtkFileFilter;

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

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

Members

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

These flags indicate what parts of a GtkFileFilterInfo struct are filled or need to be filled.

Members

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

  

See Also

GtkFileChooser

Generated by GTK-Doc V1.21.1