GtkFileFilter

GtkFileFilter — Filtering files

Functions

GtkFileFilter * gtk_file_filter_new ()
void gtk_file_filter_set_name ()
const char * 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 ()
const char ** gtk_file_filter_get_attributes ()
GtkFileFilter * gtk_file_filter_new_from_gvariant ()
GVariant * gtk_file_filter_to_gvariant ()

Properties

char * name Read / Write

Types and Values

GtkFileFilter

Object Hierarchy

    GObject
    ╰── GtkFilter
        ╰── 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()) or on their mime type (with gtk_file_filter_add_mime_type()).

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, file filters are used by adding them to a GtkFileChooser (see gtk_file_chooser_add_filter()), but it is also possible to manually use a file filter on any GtkFilterListModel containing GFileInfo objects.

GtkFileFilter as GtkBuildable

The GtkFileFilter implementation of the GtkBuildable interface supports adding rules using the <mime-types> and <patterns> 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:

Functions

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

To create a filter that accepts any file, use:

<object class="GtkFileFilter">
  <property name="name" translatable="yes">Text and Images</property>
  <mime-types>
    <mime-type>text/plain</mime-type>
    <mime-type>image/ *</mime-type>
  </mime-types>
  <patterns>
    <pattern>*.txt</pattern>
    <pattern>*.png</pattern>
  </patterns>
</object>

Returns

a new GtkFileFilter

gtk_file_filter_set_name ()

void
gtk_file_filter_set_name (GtkFileFilter *filter,
                          const char *name);

Sets a human-readable name of the filter; this is the string that will be displayed in the file chooser 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]

gtk_file_filter_get_name ()

const char *
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]

gtk_file_filter_add_mime_type ()

void
gtk_file_filter_add_mime_type (GtkFileFilter *filter,
                               const char *mime_type);

Adds a rule allowing a given mime type to filter .

Parameters

filter

A GtkFileFilter

mime_type

name of a MIME type

gtk_file_filter_add_pattern ()

void
gtk_file_filter_add_pattern (GtkFileFilter *filter,
                             const char *pattern);

Adds a rule allowing a shell style glob to a filter.

Parameters

filter

a GtkFileFilter

pattern

a shell style glob

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.

This is equivalent to calling gtk_file_filter_add_mime_type() for all the supported mime types.

Parameters

filter

a GtkFileFilter

gtk_file_filter_get_attributes ()

const char **
gtk_file_filter_get_attributes (GtkFileFilter *filter);

Gets the attributes that need to be filled in for the GFileInfo passed to this 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

the attributes.

[transfer none]

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]

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]

Types and Values

GtkFileFilter

typedef struct _GtkFileFilter GtkFileFilter;

Property Details

The “name” property

  “name”                     char *

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.

Owner: GtkFileFilter

Flags: Read / Write

Default value: NULL

See Also

GtkFileChooser

© 2005–2020 The GNOME Project
Licensed under the GNU Lesser General Public License version 2.1 or later.
https://developer.gnome.org/gtk4/4.0/GtkFileFilter.html