GtkFileFilter

GtkFileFilter — A filter for selecting a file subset

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkFileFilter

Implemented Interfaces

GtkFileFilter implements GtkBuildable.

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

GtkFileFilter as GtkBuildable

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> has the same effect as as calling gtk_file_filter_add_mime_type() or gtk_file_filter_add_pattern().

An example of 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>

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

[closure]

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.

[nullable]

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 GtkFileFilterInfo 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 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 containing information about a file.

 

Returns

TRUE if the file should be displayed

Since: 2.4


gtk_file_filter_new_from_gvariant ()

GtkFileFilter *
gtk_file_filter_new_from_gvariant (GVariant *variant);

Deserialize a file filter from an a{sv} variant in the format produced by gtk_file_filter_to_gvariant().

Parameters

variant

an a{sv} GVariant

 

Returns

a new GtkFileFilter object.

[transfer full]

Since: 3.22


gtk_file_filter_to_gvariant ()

GVariant *
gtk_file_filter_to_gvariant (GtkFileFilter *filter);

Serialize a file filter to an a{sv} variant.

Parameters

filter

a GtkFileFilter

 

Returns

a new, floating, GVariant.

[transfer none]

Since: 3.22

Types and Values

GtkFileFilter

typedef struct _GtkFileFilter GtkFileFilter;

struct GtkFileFilterInfo

struct GtkFileFilterInfo {
  GtkFileFilterFlags contains;

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

A GtkFileFilterInfo 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