1 /* GTK - The GIMP Toolkit
2 * gtkfilefilter.c: Filters for selecting a file subset
3 * Copyright (C) 2003, Red Hat, Inc.
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, write to the
17 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 * Boston, MA 02111-1307, USA.
22 * SECTION:gtkfilefilter
23 * @Short_description: A filter for selecting a file subset
24 * @Title: GtkFileFilter
26 * A GtkFileFilter can be used to restrict the files being shown in a
27 * #GtkFileChooser. Files can be filtered based on their name (with
28 * gtk_file_filter_add_pattern()), on their mime type (with
29 * gtk_file_filter_add_mime_type()), or by a custom filter function
30 * (with gtk_file_filter_add_custom()).
32 * Filtering by mime types handles aliasing and subclassing of mime
33 * types; e.g. a filter for text/plain also matches a file with mime
34 * type application/rtf, since application/rtf is a subclass of
35 * text/plain. Note that #GtkFileFilter allows wildcards for the
36 * subtype of a mime type, so you can e.g. filter for image/*.
38 * Normally, filters are used by adding them to a #GtkFileChooser,
39 * see gtk_file_chooser_add_filter(), but it is also possible
40 * to manually use a filter on a file with gtk_file_filter_filter().
42 * <refsect2 id="GtkFileFilter-BUILDER-UI">
43 * <title>GtkFileFilter as GtkBuildable</title>
45 * The GtkFileFilter implementation of the GtkBuildable interface
46 * supports adding rules using the <mime-types>, <patterns> and
47 * <applications> elements and listing the rules within. Specifying
48 * a <mime-type> or <pattern> is the same
49 * as calling gtk_recent_filter_add_mime_type() or gtk_recent_filter_add_pattern()
52 * <title>A UI definition fragment specifying GtkFileFilter rules</title>
53 * <programlisting><![CDATA[
54 * <object class="GtkFileFilter">
56 * <mime-type>text/plain</mime-type>
57 * <mime-type>image/*</mime-type>
60 * <pattern>*.txt</pattern>
61 * <pattern>*.png</pattern>
64 * ]]></programlisting>
69 * @see_also: #GtkFileChooser
75 #include <gdk-pixbuf/gdk-pixbuf.h>
77 #include "gtkfilefilter.h"
78 #include "gtkbuildable.h"
80 #include "gtkprivate.h"
82 typedef struct _GtkFileFilterClass GtkFileFilterClass;
83 typedef struct _FilterRule FilterRule;
85 #define GTK_FILE_FILTER_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GTK_TYPE_FILE_FILTER, GtkFileFilterClass))
86 #define GTK_IS_FILE_FILTER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_FILE_FILTER))
87 #define GTK_FILE_FILTER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_FILE_FILTER, GtkFileFilterClass))
91 FILTER_RULE_MIME_TYPE,
92 FILTER_RULE_PIXBUF_FORMATS,
96 struct _GtkFileFilterClass
98 GInitiallyUnownedClass parent_class;
101 struct _GtkFileFilter
103 GInitiallyUnowned parent_instance;
108 GtkFileFilterFlags needed;
114 GtkFileFilterFlags needed;
119 GSList *pixbuf_formats;
121 GtkFileFilterFunc func;
123 GDestroyNotify notify;
128 static void gtk_file_filter_finalize (GObject *object);
131 static void gtk_file_filter_buildable_init (GtkBuildableIface *iface);
132 static gboolean gtk_file_filter_buildable_custom_tag_start (GtkBuildable *buildable,
135 const gchar *tagname,
136 GMarkupParser *parser,
138 static void gtk_file_filter_buildable_custom_tag_end (GtkBuildable *buildable,
141 const gchar *tagname,
144 G_DEFINE_TYPE_WITH_CODE (GtkFileFilter, gtk_file_filter, G_TYPE_INITIALLY_UNOWNED,
145 G_IMPLEMENT_INTERFACE (GTK_TYPE_BUILDABLE,
146 gtk_file_filter_buildable_init))
149 gtk_file_filter_init (GtkFileFilter *object)
154 gtk_file_filter_class_init (GtkFileFilterClass *class)
156 GObjectClass *gobject_class = G_OBJECT_CLASS (class);
158 gobject_class->finalize = gtk_file_filter_finalize;
162 filter_rule_free (FilterRule *rule)
166 case FILTER_RULE_MIME_TYPE:
167 g_free (rule->u.mime_type);
169 case FILTER_RULE_PATTERN:
170 g_free (rule->u.pattern);
172 case FILTER_RULE_CUSTOM:
173 if (rule->u.custom.notify)
174 rule->u.custom.notify (rule->u.custom.data);
176 case FILTER_RULE_PIXBUF_FORMATS:
177 g_slist_free (rule->u.pixbuf_formats);
180 g_assert_not_reached ();
183 g_slice_free (FilterRule, rule);
187 gtk_file_filter_finalize (GObject *object)
189 GtkFileFilter *filter = GTK_FILE_FILTER (object);
191 g_slist_foreach (filter->rules, (GFunc)filter_rule_free, NULL);
192 g_slist_free (filter->rules);
194 g_free (filter->name);
196 G_OBJECT_CLASS (gtk_file_filter_parent_class)->finalize (object);
200 * GtkBuildable implementation
203 gtk_file_filter_buildable_init (GtkBuildableIface *iface)
205 iface->custom_tag_start = gtk_file_filter_buildable_custom_tag_start;
206 iface->custom_tag_end = gtk_file_filter_buildable_custom_tag_end;
215 GtkFileFilter *filter;
222 parser_start_element (GMarkupParseContext *context,
223 const gchar *element_name,
225 const gchar **values,
229 SubParserData *parser_data = (SubParserData*)user_data;
231 if (strcmp (element_name, "mime-types") == 0)
233 else if (strcmp (element_name, "mime-type") == 0)
235 parser_data->parsing = TRUE;
238 else if (strcmp (element_name, "patterns") == 0)
240 else if (strcmp (element_name, "pattern") == 0)
242 parser_data->parsing = TRUE;
246 g_warning ("Unsupported tag for GtkFileFilter: %s\n", element_name);
250 parser_text_element (GMarkupParseContext *context,
256 SubParserData *parser_data = (SubParserData*)user_data;
258 if (parser_data->parsing)
259 g_string_append_len (parser_data->string, text, text_len);
263 parser_end_element (GMarkupParseContext *context,
264 const gchar *element_name,
268 SubParserData *parser_data = (SubParserData*)user_data;
270 if (parser_data->string)
272 switch (parser_data->type)
274 case PARSE_MIME_TYPES:
275 gtk_file_filter_add_mime_type (parser_data->filter, parser_data->string->str);
278 gtk_file_filter_add_pattern (parser_data->filter, parser_data->string->str);
285 g_string_set_size (parser_data->string, 0);
286 parser_data->parsing = FALSE;
289 static const GMarkupParser sub_parser =
291 parser_start_element,
297 gtk_file_filter_buildable_custom_tag_start (GtkBuildable *buildable,
300 const gchar *tagname,
301 GMarkupParser *parser,
304 SubParserData *parser_data = NULL;
306 if (strcmp (tagname, "mime-types") == 0)
308 parser_data = g_slice_new0 (SubParserData);
309 parser_data->string = g_string_new ("");
310 parser_data->type = PARSE_MIME_TYPES;
311 parser_data->filter = GTK_FILE_FILTER (buildable);
313 *parser = sub_parser;
316 else if (strcmp (tagname, "patterns") == 0)
318 parser_data = g_slice_new0 (SubParserData);
319 parser_data->string = g_string_new ("");
320 parser_data->type = PARSE_PATTERNS;
321 parser_data->filter = GTK_FILE_FILTER (buildable);
323 *parser = sub_parser;
327 return parser_data != NULL;
331 gtk_file_filter_buildable_custom_tag_end (GtkBuildable *buildable,
334 const gchar *tagname,
337 if (strcmp (tagname, "mime-types") == 0 ||
338 strcmp (tagname, "patterns") == 0)
340 SubParserData *parser_data = (SubParserData*)data;
342 g_string_free (parser_data->string, TRUE);
343 g_slice_free (SubParserData, parser_data);
349 * gtk_file_filter_new:
351 * Creates a new #GtkFileFilter with no rules added to it.
352 * Such a filter doesn't accept any files, so is not
353 * particularly useful until you add rules with
354 * gtk_file_filter_add_mime_type(), gtk_file_filter_add_pattern(),
355 * or gtk_file_filter_add_custom(). To create a filter
356 * that accepts any file, use:
358 * GtkFileFilter *filter = gtk_file_filter_new ();
359 * gtk_file_filter_add_pattern (filter, "*");
362 * Return value: a new #GtkFileFilter
367 gtk_file_filter_new (void)
369 return g_object_new (GTK_TYPE_FILE_FILTER, NULL);
373 * gtk_file_filter_set_name:
374 * @filter: a #GtkFileFilter
375 * @name: (allow-none): the human-readable-name for the filter, or %NULL
376 * to remove any existing name.
378 * Sets the human-readable name of the filter; this is the string
379 * that will be displayed in the file selector user interface if
380 * there is a selectable list of filters.
385 gtk_file_filter_set_name (GtkFileFilter *filter,
388 g_return_if_fail (GTK_IS_FILE_FILTER (filter));
390 g_free (filter->name);
392 filter->name = g_strdup (name);
396 * gtk_file_filter_get_name:
397 * @filter: a #GtkFileFilter
399 * Gets the human-readable name for the filter. See gtk_file_filter_set_name().
401 * Return value: The human-readable name of the filter,
402 * or %NULL. This value is owned by GTK+ and must not
403 * be modified or freed.
408 gtk_file_filter_get_name (GtkFileFilter *filter)
410 g_return_val_if_fail (GTK_IS_FILE_FILTER (filter), NULL);
416 file_filter_add_rule (GtkFileFilter *filter,
419 filter->needed |= rule->needed;
420 filter->rules = g_slist_append (filter->rules, rule);
424 * gtk_file_filter_add_mime_type:
425 * @filter: A #GtkFileFilter
426 * @mime_type: name of a MIME type
428 * Adds a rule allowing a given mime type to @filter.
433 gtk_file_filter_add_mime_type (GtkFileFilter *filter,
434 const gchar *mime_type)
438 g_return_if_fail (GTK_IS_FILE_FILTER (filter));
439 g_return_if_fail (mime_type != NULL);
441 rule = g_slice_new (FilterRule);
442 rule->type = FILTER_RULE_MIME_TYPE;
443 rule->needed = GTK_FILE_FILTER_MIME_TYPE;
444 rule->u.mime_type = g_strdup (mime_type);
446 file_filter_add_rule (filter, rule);
450 * gtk_file_filter_add_pattern:
451 * @filter: a #GtkFileFilter
452 * @pattern: a shell style glob
454 * Adds a rule allowing a shell style glob to a filter.
459 gtk_file_filter_add_pattern (GtkFileFilter *filter,
460 const gchar *pattern)
464 g_return_if_fail (GTK_IS_FILE_FILTER (filter));
465 g_return_if_fail (pattern != NULL);
467 rule = g_slice_new (FilterRule);
468 rule->type = FILTER_RULE_PATTERN;
469 rule->needed = GTK_FILE_FILTER_DISPLAY_NAME;
470 rule->u.pattern = g_strdup (pattern);
472 file_filter_add_rule (filter, rule);
476 * gtk_file_filter_add_pixbuf_formats:
477 * @filter: a #GtkFileFilter
479 * Adds a rule allowing image files in the formats supported
485 gtk_file_filter_add_pixbuf_formats (GtkFileFilter *filter)
489 g_return_if_fail (GTK_IS_FILE_FILTER (filter));
491 rule = g_slice_new (FilterRule);
492 rule->type = FILTER_RULE_PIXBUF_FORMATS;
493 rule->needed = GTK_FILE_FILTER_MIME_TYPE;
494 rule->u.pixbuf_formats = gdk_pixbuf_get_formats ();
495 file_filter_add_rule (filter, rule);
500 * gtk_file_filter_add_custom:
501 * @filter: a #GtkFileFilter
502 * @needed: bitfield of flags indicating the information that the custom
503 * filter function needs.
504 * @func: callback function; if the function returns %TRUE, then
505 * the file will be displayed.
506 * @data: data to pass to @func
507 * @notify: function to call to free @data when it is no longer needed.
509 * Adds rule to a filter that allows files based on a custom callback
510 * function. The bitfield @needed which is passed in provides information
511 * about what sorts of information that the filter function needs;
512 * this allows GTK+ to avoid retrieving expensive information when
513 * it isn't needed by the filter.
518 gtk_file_filter_add_custom (GtkFileFilter *filter,
519 GtkFileFilterFlags needed,
520 GtkFileFilterFunc func,
522 GDestroyNotify notify)
526 g_return_if_fail (GTK_IS_FILE_FILTER (filter));
527 g_return_if_fail (func != NULL);
529 rule = g_slice_new (FilterRule);
530 rule->type = FILTER_RULE_CUSTOM;
531 rule->needed = needed;
532 rule->u.custom.func = func;
533 rule->u.custom.data = data;
534 rule->u.custom.notify = notify;
536 file_filter_add_rule (filter, rule);
540 * gtk_file_filter_get_needed:
541 * @filter: a #GtkFileFilter
543 * Gets the fields that need to be filled in for the structure
544 * passed to gtk_file_filter_filter()
546 * This function will not typically be used by applications; it
547 * is intended principally for use in the implementation of
550 * Return value: bitfield of flags indicating needed fields when
551 * calling gtk_file_filter_filter()
556 gtk_file_filter_get_needed (GtkFileFilter *filter)
558 return filter->needed;
562 * gtk_file_filter_filter:
563 * @filter: a #GtkFileFilter
564 * @filter_info: a #GtkFileFilterInfo structure containing information
567 * Tests whether a file should be displayed according to @filter.
568 * The #GtkFileFilterInfo structure @filter_info should include
569 * the fields returned from gtk_file_filter_get_needed().
571 * This function will not typically be used by applications; it
572 * is intended principally for use in the implementation of
575 * Return value: %TRUE if the file should be displayed
580 gtk_file_filter_filter (GtkFileFilter *filter,
581 const GtkFileFilterInfo *filter_info)
585 for (tmp_list = filter->rules; tmp_list; tmp_list = tmp_list->next)
587 FilterRule *rule = tmp_list->data;
589 if ((filter_info->contains & rule->needed) != rule->needed)
594 case FILTER_RULE_MIME_TYPE:
595 if (filter_info->mime_type != NULL &&
596 g_content_type_is_a (filter_info->mime_type, rule->u.mime_type))
599 case FILTER_RULE_PATTERN:
600 if (filter_info->display_name != NULL &&
601 _gtk_fnmatch (rule->u.pattern, filter_info->display_name, FALSE))
604 case FILTER_RULE_PIXBUF_FORMATS:
608 if (!filter_info->mime_type)
611 for (list = rule->u.pixbuf_formats; list; list = list->next)
616 mime_types = gdk_pixbuf_format_get_mime_types (list->data);
618 for (i = 0; mime_types[i] != NULL; i++)
620 if (strcmp (mime_types[i], filter_info->mime_type) == 0)
622 g_strfreev (mime_types);
627 g_strfreev (mime_types);
631 case FILTER_RULE_CUSTOM:
632 if (rule->u.custom.func (filter_info, rule->u.custom.data))