manpagez: man pages & more
html files: gtk
Home | html | info | man

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_recent_filter_add_mime_type() or gtk_recent_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.

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

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

© manpagez.com 2000-2024
Individual documents may contain additional copyright information.