1 /* GTK - The GIMP Toolkit
2 * gtkrecentfilter.h - Filter object for recently used resources
3 * Copyright (C) 2006, Emmanuele Bassi
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
20 * SECTION:gtkrecentfilter
21 * @Short_Description: A filter for selecting a subset of recently used files
22 * @Title: GtkRecentFilter
24 * A #GtkRecentFilter can be used to restrict the files being shown
25 * in a #GtkRecentChooser. Files can be filtered based on their name
26 * (with gtk_recent_filter_add_pattern()), on their mime type (with
27 * gtk_file_filter_add_mime_type()), on the application that has
28 * registered them (with gtk_recent_filter_add_application()), or by
29 * a custom filter function (with gtk_recent_filter_add_custom()).
31 * Filtering by mime type handles aliasing and subclassing of mime
32 * types; e.g. a filter for text/plain also matches a file with mime
33 * type application/rtf, since application/rtf is a subclass of text/plain.
34 * Note that #GtkRecentFilter allows wildcards for the subtype of a
35 * mime type, so you can e.g. filter for image/<!-- -->*.
37 * Normally, filters are used by adding them to a #GtkRecentChooser,
38 * see gtk_recent_chooser_add_filter(), but it is also possible to
39 * manually use a filter on a file with gtk_recent_filter_filter().
41 * Recently used files are supported since GTK+ 2.10.
43 * <refsect2 id="GtkRecentFilter-BUILDER-UI">
44 * <title>GtkRecentFilter as GtkBuildable</title>
46 * The GtkRecentFilter implementation of the GtkBuildable interface
47 * supports adding rules using the <mime-types>, <patterns> and
48 * <applications> elements and listing the rules within. Specifying
49 * a <mime-type>, <pattern> or <application> is the same
50 * as calling gtk_recent_filter_add_mime_type(), gtk_recent_filter_add_pattern()
51 * or gtk_recent_filter_add_application().
54 * <title>A UI definition fragment specifying GtkRecentFilter rules</title>
55 * <programlisting><![CDATA[
56 * <object class="GtkRecentFilter">
58 * <mime-type>text/plain</mime-type>
59 * <mime-type>image/png</mime-type>
62 * <pattern>*.txt</pattern>
63 * <pattern>*.png</pattern>
66 * <application>gimp</application>
67 * <application>gedit</application>
68 * <application>glade</application>
71 * ]]></programlisting>
80 #include <gdk-pixbuf/gdk-pixbuf.h>
82 #include "gtkrecentfilter.h"
83 #include "gtkbuildable.h"
85 #include "gtkprivate.h"
87 static void gtk_recent_filter_buildable_init (GtkBuildableIface *iface);
88 static gboolean gtk_recent_filter_buildable_custom_tag_start (GtkBuildable *buildable,
92 GMarkupParser *parser,
94 static void gtk_recent_filter_buildable_custom_tag_end (GtkBuildable *buildable,
100 typedef struct _GtkRecentFilterClass GtkRecentFilterClass;
101 typedef struct _FilterRule FilterRule;
105 FILTER_RULE_DISPLAY_NAME,
106 FILTER_RULE_MIME_TYPE,
107 FILTER_RULE_PIXBUF_FORMATS,
108 FILTER_RULE_APPLICATION,
114 struct _GtkRecentFilter
116 GInitiallyUnowned parent_instance;
121 GtkRecentFilterFlags needed;
124 struct _GtkRecentFilterClass
126 GInitiallyUnownedClass parent_class;
132 GtkRecentFilterFlags needed;
138 GSList *pixbuf_formats;
143 GtkRecentFilterFunc func;
145 GDestroyNotify data_destroy;
150 G_DEFINE_TYPE_WITH_CODE (GtkRecentFilter, gtk_recent_filter, G_TYPE_INITIALLY_UNOWNED,
151 G_IMPLEMENT_INTERFACE (GTK_TYPE_BUILDABLE,
152 gtk_recent_filter_buildable_init))
156 filter_rule_free (FilterRule *rule)
160 case FILTER_RULE_MIME_TYPE:
161 g_free (rule->u.mime_type);
163 case FILTER_RULE_URI:
164 g_free (rule->u.uri);
166 case FILTER_RULE_DISPLAY_NAME:
167 g_free (rule->u.pattern);
169 case FILTER_RULE_PIXBUF_FORMATS:
170 g_slist_free (rule->u.pixbuf_formats);
172 case FILTER_RULE_AGE:
174 case FILTER_RULE_APPLICATION:
175 g_free (rule->u.application);
177 case FILTER_RULE_GROUP:
178 g_free (rule->u.group);
180 case FILTER_RULE_CUSTOM:
181 if (rule->u.custom.data_destroy)
182 rule->u.custom.data_destroy (rule->u.custom.data);
185 g_assert_not_reached ();
193 gtk_recent_filter_finalize (GObject *object)
195 GtkRecentFilter *filter = GTK_RECENT_FILTER (object);
197 g_free (filter->name);
201 g_slist_foreach (filter->rules,
202 (GFunc) filter_rule_free,
204 g_slist_free (filter->rules);
207 G_OBJECT_CLASS (gtk_recent_filter_parent_class)->finalize (object);
211 gtk_recent_filter_class_init (GtkRecentFilterClass *klass)
213 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
215 gobject_class->finalize = gtk_recent_filter_finalize;
219 gtk_recent_filter_init (GtkRecentFilter *filter)
226 * GtkBuildable implementation
229 gtk_recent_filter_buildable_init (GtkBuildableIface *iface)
231 iface->custom_tag_start = gtk_recent_filter_buildable_custom_tag_start;
232 iface->custom_tag_end = gtk_recent_filter_buildable_custom_tag_end;
243 GtkRecentFilter *filter;
250 parser_start_element (GMarkupParseContext *context,
251 const gchar *element_name,
253 const gchar **values,
257 SubParserData *parser_data = (SubParserData*)user_data;
259 if (strcmp (element_name, "mime-types") == 0)
261 else if (strcmp (element_name, "mime-type") == 0)
263 parser_data->parsing = TRUE;
266 else if (strcmp (element_name, "patterns") == 0)
268 else if (strcmp (element_name, "pattern") == 0)
270 parser_data->parsing = TRUE;
273 else if (strcmp (element_name, "applications") == 0)
275 else if (strcmp (element_name, "application") == 0)
277 parser_data->parsing = TRUE;
281 g_warning ("Unsupported tag for GtkRecentFilter: %s\n", element_name);
285 parser_text_element (GMarkupParseContext *context,
291 SubParserData *parser_data = (SubParserData*)user_data;
293 if (parser_data->parsing)
294 g_string_append_len (parser_data->string, text, text_len);
298 parser_end_element (GMarkupParseContext *context,
299 const gchar *element_name,
303 SubParserData *parser_data = (SubParserData*)user_data;
305 if (parser_data->string)
307 switch (parser_data->type)
309 case PARSE_MIME_TYPES:
310 gtk_recent_filter_add_mime_type (parser_data->filter, parser_data->string->str);
313 gtk_recent_filter_add_pattern (parser_data->filter, parser_data->string->str);
315 case PARSE_APPLICATIONS:
316 gtk_recent_filter_add_application (parser_data->filter, parser_data->string->str);
323 g_string_set_size (parser_data->string, 0);
324 parser_data->parsing = FALSE;
327 static const GMarkupParser sub_parser =
329 parser_start_element,
335 gtk_recent_filter_buildable_custom_tag_start (GtkBuildable *buildable,
338 const gchar *tagname,
339 GMarkupParser *parser,
342 SubParserData *parser_data = NULL;
344 if (strcmp (tagname, "mime-types") == 0)
346 parser_data = g_slice_new0 (SubParserData);
347 parser_data->string = g_string_new ("");
348 parser_data->type = PARSE_MIME_TYPES;
349 parser_data->filter = GTK_RECENT_FILTER (buildable);
351 *parser = sub_parser;
354 else if (strcmp (tagname, "patterns") == 0)
356 parser_data = g_slice_new0 (SubParserData);
357 parser_data->string = g_string_new ("");
358 parser_data->type = PARSE_PATTERNS;
359 parser_data->filter = GTK_RECENT_FILTER (buildable);
361 *parser = sub_parser;
364 else if (strcmp (tagname, "applications") == 0)
366 parser_data = g_slice_new0 (SubParserData);
367 parser_data->string = g_string_new ("");
368 parser_data->type = PARSE_APPLICATIONS;
369 parser_data->filter = GTK_RECENT_FILTER (buildable);
371 *parser = sub_parser;
375 return parser_data != NULL;
379 gtk_recent_filter_buildable_custom_tag_end (GtkBuildable *buildable,
382 const gchar *tagname,
385 if (strcmp (tagname, "mime-types") == 0 ||
386 strcmp (tagname, "patterns") == 0 ||
387 strcmp (tagname, "applications") == 0)
389 SubParserData *parser_data = (SubParserData*)data;
391 g_string_free (parser_data->string, TRUE);
392 g_slice_free (SubParserData, parser_data);
401 * gtk_recent_filter_new:
403 * Creates a new #GtkRecentFilter with no rules added to it.
404 * Such filter does not accept any recently used resources, so is not
405 * particularly useful until you add rules with
406 * gtk_recent_filter_add_pattern(), gtk_recent_filter_add_mime_type(),
407 * gtk_recent_filter_add_application(), gtk_recent_filter_add_age().
408 * To create a filter that accepts any recently used resource, use:
410 * GtkRecentFilter *filter = gtk_recent_filter_new ();
411 * gtk_recent_filter_add_pattern (filter, "*");
414 * Return value: a new #GtkRecentFilter
419 gtk_recent_filter_new (void)
421 return g_object_new (GTK_TYPE_RECENT_FILTER, NULL);
425 * gtk_recent_filter_set_name:
426 * @filter: a #GtkRecentFilter
427 * @name: then human readable name of @filter
429 * Sets the human-readable name of the filter; this is the string
430 * that will be displayed in the recently used resources selector
431 * user interface if there is a selectable list of filters.
436 gtk_recent_filter_set_name (GtkRecentFilter *filter,
439 g_return_if_fail (GTK_IS_RECENT_FILTER (filter));
441 g_free (filter->name);
444 filter->name = g_strdup (name);
448 * gtk_recent_filter_get_name:
449 * @filter: a #GtkRecentFilter
451 * Gets the human-readable name for the filter.
452 * See gtk_recent_filter_set_name().
454 * Return value: the name of the filter, or %NULL. The returned string
455 * is owned by the filter object and should not be freed.
460 gtk_recent_filter_get_name (GtkRecentFilter *filter)
462 g_return_val_if_fail (GTK_IS_RECENT_FILTER (filter), NULL);
468 * gtk_recent_filter_get_needed:
469 * @filter: a #GtkRecentFilter
471 * Gets the fields that need to be filled in for the structure
472 * passed to gtk_recent_filter_filter()
474 * This function will not typically be used by applications; it
475 * is intended principally for use in the implementation of
478 * Return value: bitfield of flags indicating needed fields when
479 * calling gtk_recent_filter_filter()
484 gtk_recent_filter_get_needed (GtkRecentFilter *filter)
486 return filter->needed;
490 recent_filter_add_rule (GtkRecentFilter *filter,
493 filter->needed |= rule->needed;
494 filter->rules = g_slist_append (filter->rules, rule);
498 * gtk_recent_filter_add_mime_type:
499 * @filter: a #GtkRecentFilter
500 * @mime_type: a MIME type
502 * Adds a rule that allows resources based on their registered MIME type.
507 gtk_recent_filter_add_mime_type (GtkRecentFilter *filter,
508 const gchar *mime_type)
512 g_return_if_fail (GTK_IS_RECENT_FILTER (filter));
513 g_return_if_fail (mime_type != NULL);
515 rule = g_new0 (FilterRule, 1);
516 rule->type = FILTER_RULE_MIME_TYPE;
517 rule->needed = GTK_RECENT_FILTER_MIME_TYPE;
518 rule->u.mime_type = g_strdup (mime_type);
520 recent_filter_add_rule (filter, rule);
524 * gtk_recent_filter_add_pattern:
525 * @filter: a #GtkRecentFilter
526 * @pattern: a file pattern
528 * Adds a rule that allows resources based on a pattern matching their
534 gtk_recent_filter_add_pattern (GtkRecentFilter *filter,
535 const gchar *pattern)
539 g_return_if_fail (GTK_IS_RECENT_FILTER (filter));
540 g_return_if_fail (pattern != NULL);
542 rule = g_new0 (FilterRule, 1);
543 rule->type = FILTER_RULE_DISPLAY_NAME;
544 rule->needed = GTK_RECENT_FILTER_DISPLAY_NAME;
545 rule->u.pattern = g_strdup (pattern);
547 recent_filter_add_rule (filter, rule);
551 * gtk_recent_filter_add_pixbuf_formats:
552 * @filter: a #GtkRecentFilter
554 * Adds a rule allowing image files in the formats supported
560 gtk_recent_filter_add_pixbuf_formats (GtkRecentFilter *filter)
564 g_return_if_fail (GTK_IS_RECENT_FILTER (filter));
566 rule = g_new0 (FilterRule, 1);
567 rule->type = FILTER_RULE_PIXBUF_FORMATS;
568 rule->needed = GTK_RECENT_FILTER_MIME_TYPE;
569 rule->u.pixbuf_formats = gdk_pixbuf_get_formats ();
571 recent_filter_add_rule (filter, rule);
575 * gtk_recent_filter_add_application:
576 * @filter: a #GtkRecentFilter
577 * @application: an application name
579 * Adds a rule that allows resources based on the name of the application
580 * that has registered them.
585 gtk_recent_filter_add_application (GtkRecentFilter *filter,
586 const gchar *application)
590 g_return_if_fail (GTK_IS_RECENT_FILTER (filter));
591 g_return_if_fail (application != NULL);
593 rule = g_new0 (FilterRule, 1);
594 rule->type = FILTER_RULE_APPLICATION;
595 rule->needed = GTK_RECENT_FILTER_APPLICATION;
596 rule->u.application = g_strdup (application);
598 recent_filter_add_rule (filter, rule);
602 * gtk_recent_filter_add_group:
603 * @filter: a #GtkRecentFilter
604 * @group: a group name
606 * Adds a rule that allows resources based on the name of the group
607 * to which they belong
612 gtk_recent_filter_add_group (GtkRecentFilter *filter,
617 g_return_if_fail (GTK_IS_RECENT_FILTER (filter));
618 g_return_if_fail (group != NULL);
620 rule = g_new0 (FilterRule, 1);
621 rule->type = FILTER_RULE_GROUP;
622 rule->needed = GTK_RECENT_FILTER_GROUP;
623 rule->u.group = g_strdup (group);
625 recent_filter_add_rule (filter, rule);
629 * gtk_recent_filter_add_age:
630 * @filter: a #GtkRecentFilter
631 * @days: number of days
633 * Adds a rule that allows resources based on their age - that is, the number
634 * of days elapsed since they were last modified.
639 gtk_recent_filter_add_age (GtkRecentFilter *filter,
644 g_return_if_fail (GTK_IS_RECENT_FILTER (filter));
646 rule = g_new0 (FilterRule, 1);
647 rule->type = FILTER_RULE_AGE;
648 rule->needed = GTK_RECENT_FILTER_AGE;
651 recent_filter_add_rule (filter, rule);
655 * gtk_recent_filter_add_custom:
656 * @filter: a #GtkRecentFilter
657 * @needed: bitfield of flags indicating the information that the custom
658 * filter function needs.
659 * @func: callback function; if the function returns %TRUE, then
660 * the file will be displayed.
661 * @data: data to pass to @func
662 * @data_destroy: function to call to free @data when it is no longer needed.
664 * Adds a rule to a filter that allows resources based on a custom callback
665 * function. The bitfield @needed which is passed in provides information
666 * about what sorts of information that the filter function needs;
667 * this allows GTK+ to avoid retrieving expensive information when
668 * it isn't needed by the filter.
673 gtk_recent_filter_add_custom (GtkRecentFilter *filter,
674 GtkRecentFilterFlags needed,
675 GtkRecentFilterFunc func,
677 GDestroyNotify data_destroy)
681 g_return_if_fail (GTK_IS_RECENT_FILTER (filter));
682 g_return_if_fail (func != NULL);
684 rule = g_new0 (FilterRule, 1);
685 rule->type = FILTER_RULE_CUSTOM;
686 rule->needed = needed;
687 rule->u.custom.func = func;
688 rule->u.custom.data = data;
689 rule->u.custom.data_destroy = data_destroy;
691 recent_filter_add_rule (filter, rule);
696 * gtk_recent_filter_filter:
697 * @filter: a #GtkRecentFilter
698 * @filter_info: a #GtkRecentFilterInfo structure containing information
699 * about a recently used resource
701 * Tests whether a file should be displayed according to @filter.
702 * The #GtkRecentFilterInfo structure @filter_info should include
703 * the fields returned from gtk_recent_filter_get_needed().
705 * This function will not typically be used by applications; it
706 * is intended principally for use in the implementation of
709 * Return value: %TRUE if the file should be displayed
714 gtk_recent_filter_filter (GtkRecentFilter *filter,
715 const GtkRecentFilterInfo *filter_info)
719 g_return_val_if_fail (GTK_IS_RECENT_FILTER (filter), FALSE);
720 g_return_val_if_fail (filter_info != NULL, FALSE);
722 for (l = filter->rules; l != NULL; l = l->next)
724 FilterRule *rule = (FilterRule *) l->data;
726 if ((filter_info->contains & rule->needed) != rule->needed)
731 case FILTER_RULE_MIME_TYPE:
732 if (filter_info->mime_type != NULL &&
733 g_content_type_is_a (filter_info->mime_type, rule->u.mime_type))
736 case FILTER_RULE_APPLICATION:
737 if (filter_info->applications)
741 for (i = 0; filter_info->applications[i] != NULL; i++)
743 if (strcmp (filter_info->applications[i], rule->u.application) == 0)
748 case FILTER_RULE_GROUP:
749 if (filter_info->groups)
753 for (i = 0; filter_info->groups[i] != NULL; i++)
755 if (strcmp (filter_info->groups[i], rule->u.group) == 0)
760 case FILTER_RULE_PIXBUF_FORMATS:
763 if (!filter_info->mime_type)
766 for (list = rule->u.pixbuf_formats; list; list = list->next)
771 mime_types = gdk_pixbuf_format_get_mime_types (list->data);
773 for (i = 0; mime_types[i] != NULL; i++)
775 if (strcmp (mime_types[i], filter_info->mime_type) == 0)
777 g_strfreev (mime_types);
782 g_strfreev (mime_types);
786 case FILTER_RULE_URI:
787 if ((filter_info->uri != NULL) &&
788 _gtk_fnmatch (rule->u.uri, filter_info->uri, FALSE))
791 case FILTER_RULE_DISPLAY_NAME:
792 if ((filter_info->display_name != NULL) &&
793 _gtk_fnmatch (rule->u.pattern, filter_info->display_name, FALSE))
796 case FILTER_RULE_AGE:
797 if ((filter_info->age != -1) &&
798 (filter_info->age < rule->u.age))
801 case FILTER_RULE_CUSTOM:
802 if (rule->u.custom.func (filter_info, rule->u.custom.data))