GtkRecentFilter

GtkRecentFilter — A filter for selecting a subset of recently used files

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkRecentFilter

Implemented Interfaces

GtkRecentFilter implements GtkBuildable.

Includes

#include <gtk/gtk.h>

Description

A GtkRecentFilter can be used to restrict the files being shown in a GtkRecentChooser. Files can be filtered based on their name (with gtk_recent_filter_add_pattern()), on their mime type (with gtk_file_filter_add_mime_type()), on the application that has registered them (with gtk_recent_filter_add_application()), or by a custom filter function (with gtk_recent_filter_add_custom()).

Filtering by mime type 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 GtkRecentFilter 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 GtkRecentChooser, see gtk_recent_chooser_add_filter(), but it is also possible to manually use a filter on a file with gtk_recent_filter_filter().

Recently used files are supported since GTK+ 2.10.

GtkRecentFilter as GtkBuildable

The GtkRecentFilter 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>, <pattern> or <application> has the same effect as calling gtk_recent_filter_add_mime_type(), gtk_recent_filter_add_pattern() or gtk_recent_filter_add_application().

An example of a UI definition fragment specifying GtkRecentFilter rules:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<object class="GtkRecentFilter">
  <mime-types>
    <mime-type>text/plain</mime-type>
    <mime-type>image/png</mime-type>
  </mime-types>
  <patterns>
    <pattern>*.txt</pattern>
    <pattern>*.png</pattern>
  </patterns>
  <applications>
    <application>gimp</application>
    <application>gedit</application>
    <application>glade</application>
  </applications>
</object>

Functions

GtkRecentFilterFunc ()

gboolean
(*GtkRecentFilterFunc) (const GtkRecentFilterInfo *filter_info,
                        gpointer user_data);

The type of function that is used with custom filters, see gtk_recent_filter_add_custom().

Parameters

filter_info

a GtkRecentFilterInfo that is filled according to the needed flags passed to gtk_recent_filter_add_custom()

 

user_data

user data passed to gtk_recent_filter_add_custom()

 

Returns

TRUE if the file should be displayed


gtk_recent_filter_new ()

GtkRecentFilter *
gtk_recent_filter_new (void);

Creates a new GtkRecentFilter with no rules added to it. Such filter does not accept any recently used resources, so is not particularly useful until you add rules with gtk_recent_filter_add_pattern(), gtk_recent_filter_add_mime_type(), gtk_recent_filter_add_application(), gtk_recent_filter_add_age(). To create a filter that accepts any recently used resource, use:

1
2
GtkRecentFilter *filter = gtk_recent_filter_new ();
gtk_recent_filter_add_pattern (filter, "*");

Returns

a new GtkRecentFilter

Since: 2.10


gtk_recent_filter_get_name ()

const gchar *
gtk_recent_filter_get_name (GtkRecentFilter *filter);

Gets the human-readable name for the filter. See gtk_recent_filter_set_name().

Parameters

filter

a GtkRecentFilter

 

Returns

the name of the filter, or NULL. The returned string is owned by the filter object and should not be freed.

[nullable]

Since: 2.10


gtk_recent_filter_set_name ()

void
gtk_recent_filter_set_name (GtkRecentFilter *filter,
                            const gchar *name);

Sets the human-readable name of the filter; this is the string that will be displayed in the recently used resources selector user interface if there is a selectable list of filters.

Parameters

filter

a GtkRecentFilter

 

name

then human readable name of filter

 

Since: 2.10


gtk_recent_filter_add_mime_type ()

void
gtk_recent_filter_add_mime_type (GtkRecentFilter *filter,
                                 const gchar *mime_type);

Adds a rule that allows resources based on their registered MIME type.

Parameters

filter

a GtkRecentFilter

 

mime_type

a MIME type

 

Since: 2.10


gtk_recent_filter_add_pattern ()

void
gtk_recent_filter_add_pattern (GtkRecentFilter *filter,
                               const gchar *pattern);

Adds a rule that allows resources based on a pattern matching their display name.

Parameters

filter

a GtkRecentFilter

 

pattern

a file pattern

 

Since: 2.10


gtk_recent_filter_add_pixbuf_formats ()

void
gtk_recent_filter_add_pixbuf_formats (GtkRecentFilter *filter);

Adds a rule allowing image files in the formats supported by GdkPixbuf.

Parameters

filter

a GtkRecentFilter

 

Since: 2.10


gtk_recent_filter_add_application ()

void
gtk_recent_filter_add_application (GtkRecentFilter *filter,
                                   const gchar *application);

Adds a rule that allows resources based on the name of the application that has registered them.

Parameters

filter

a GtkRecentFilter

 

application

an application name

 

Since: 2.10


gtk_recent_filter_add_group ()

void
gtk_recent_filter_add_group (GtkRecentFilter *filter,
                             const gchar *group);

Adds a rule that allows resources based on the name of the group to which they belong

Parameters

filter

a GtkRecentFilter

 

group

a group name

 

Since: 2.10


gtk_recent_filter_add_age ()

void
gtk_recent_filter_add_age (GtkRecentFilter *filter,
                           gint days);

Adds a rule that allows resources based on their age - that is, the number of days elapsed since they were last modified.

Parameters

filter

a GtkRecentFilter

 

days

number of days

 

Since: 2.10


gtk_recent_filter_add_custom ()

void
gtk_recent_filter_add_custom (GtkRecentFilter *filter,
                              GtkRecentFilterFlags needed,
                              GtkRecentFilterFunc func,
                              gpointer data,
                              GDestroyNotify data_destroy);

Adds a rule to a filter that allows resources 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 GtkRecentFilter

 

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

 

data_destroy

function to call to free data when it is no longer needed.

 

Since: 2.10


gtk_recent_filter_get_needed ()

GtkRecentFilterFlags
gtk_recent_filter_get_needed (GtkRecentFilter *filter);

Gets the fields that need to be filled in for the GtkRecentFilterInfo passed to gtk_recent_filter_filter()

This function will not typically be used by applications; it is intended principally for use in the implementation of GtkRecentChooser.

Parameters

filter

a GtkRecentFilter

 

Returns

bitfield of flags indicating needed fields when calling gtk_recent_filter_filter()

Since: 2.10


gtk_recent_filter_filter ()

gboolean
gtk_recent_filter_filter (GtkRecentFilter *filter,
                          const GtkRecentFilterInfo *filter_info);

Tests whether a file should be displayed according to filter . The GtkRecentFilterInfo filter_info should include the fields returned from gtk_recent_filter_get_needed(), and must set the GtkRecentFilterInfo.contains field of filter_info to indicate which fields have been set.

This function will not typically be used by applications; it is intended principally for use in the implementation of GtkRecentChooser.

Parameters

filter

a GtkRecentFilter

 

filter_info

a GtkRecentFilterInfo containing information about a recently used resource

 

Returns

TRUE if the file should be displayed

Since: 2.10

Types and Values

GtkRecentFilter

typedef struct _GtkRecentFilter GtkRecentFilter;

struct GtkRecentFilterInfo

struct GtkRecentFilterInfo {
  GtkRecentFilterFlags contains;

  const gchar *uri;
  const gchar *display_name;
  const gchar *mime_type;
  const gchar **applications;
  const gchar **groups;

  gint age;
};

A GtkRecentFilterInfo struct is used to pass information about the tested file to gtk_recent_filter_filter().

Members

GtkRecentFilterFlags contains;

GtkRecentFilterFlags to indicate which fields are set.

 

const gchar *uri;

The URI of the file being tested.

[nullable]

const gchar *display_name;

The string that will be used to display the file in the recent chooser.

[nullable]

const gchar *mime_type;

MIME type of the file.

[nullable]

const gchar **applications;

The list of applications that have registered the file.

[nullable][array zero-terminated=1]

const gchar **groups;

The groups to which the file belongs to.

[nullable][array zero-terminated=1]

gint age;

The number of days elapsed since the file has been registered.

 

enum GtkRecentFilterFlags

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

Members

GTK_RECENT_FILTER_URI

the URI of the file being tested

 

GTK_RECENT_FILTER_DISPLAY_NAME

the string that will be used to display the file in the recent chooser

 

GTK_RECENT_FILTER_MIME_TYPE

the mime type of the file

 

GTK_RECENT_FILTER_APPLICATION

the list of applications that have registered the file

 

GTK_RECENT_FILTER_GROUP

the groups to which the file belongs to

 

GTK_RECENT_FILTER_AGE

the number of days elapsed since the file has been registered