GtkRecentFilter

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

Synopsis

#include <gtk/gtk.h>

                    GtkRecentFilter;
                    GtkRecentFilterInfo;
enum                GtkRecentFilterFlags;
gboolean            (*GtkRecentFilterFunc)              (const GtkRecentFilterInfo *filter_info,
                                                         gpointer user_data);
GtkRecentFilter *   gtk_recent_filter_new               (void);
const gchar *       gtk_recent_filter_get_name          (GtkRecentFilter *filter);
void                gtk_recent_filter_set_name          (GtkRecentFilter *filter,
                                                         const gchar *name);
void                gtk_recent_filter_add_mime_type     (GtkRecentFilter *filter,
                                                         const gchar *mime_type);
void                gtk_recent_filter_add_pattern       (GtkRecentFilter *filter,
                                                         const gchar *pattern);
void                gtk_recent_filter_add_pixbuf_formats
                                                        (GtkRecentFilter *filter);
void                gtk_recent_filter_add_application   (GtkRecentFilter *filter,
                                                         const gchar *application);
void                gtk_recent_filter_add_group         (GtkRecentFilter *filter,
                                                         const gchar *group);
void                gtk_recent_filter_add_age           (GtkRecentFilter *filter,
                                                         gint days);
void                gtk_recent_filter_add_custom        (GtkRecentFilter *filter,
                                                         GtkRecentFilterFlags needed,
                                                         GtkRecentFilterFunc func,
                                                         gpointer data,
                                                         GDestroyNotify data_destroy);
GtkRecentFilterFlags  gtk_recent_filter_get_needed      (GtkRecentFilter *filter);
gboolean            gtk_recent_filter_filter            (GtkRecentFilter *filter,
                                                         const GtkRecentFilterInfo *filter_info);

Object Hierarchy

  GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkRecentFilter

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.

Details

GtkRecentFilter

typedef struct _GtkRecentFilter GtkRecentFilter;

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

GtkRecentFilterInfo

typedef struct {
  GtkRecentFilterFlags contains;

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

  gint age;
} GtkRecentFilterInfo;

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

GtkRecentFilterFlags contains;

 Flags indicating which of the following fields need are filled

const gchar *uri;

 the URI of the file being tested

const gchar *display_name;

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

const gchar *mime_type;

 the mime type of the file

const gchar **applications;

 the list of applications that have registered the file

const gchar **groups;

 the groups to which the file belongs to

gint age;

 the number of days elapsed since the file has been registered

enum GtkRecentFilterFlags

typedef enum {
  GTK_RECENT_FILTER_URI          = 1 << 0,
  GTK_RECENT_FILTER_DISPLAY_NAME = 1 << 1,
  GTK_RECENT_FILTER_MIME_TYPE    = 1 << 2,
  GTK_RECENT_FILTER_APPLICATION  = 1 << 3,
  GTK_RECENT_FILTER_GROUP        = 1 << 4,
  GTK_RECENT_FILTER_AGE          = 1 << 5
} GtkRecentFilterFlags;

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

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

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

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

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.

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.

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.

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.

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.

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.

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

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.

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.

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 structure 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.

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 structure filter_info should include the fields returned from gtk_recent_filter_get_needed().

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

filter :

 a GtkRecentFilter

filter_info :

 a GtkRecentFilterInfo structure containing information about a recently used resource

Returns :

 TRUE if the file should be displayed

Since 2.10

See Also

GtkRecentChooser

Generated by GTK-Doc V1.14