Pileus Git - ~andy/gtk/blob - gtk/gtkfilefilter.c

   1 /* GTK - The GIMP Toolkit
   2  * gtkfilefilter.c: Filters for selecting a file subset
   3  * Copyright (C) 2003, Red Hat, Inc.
   4  *
   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.
   9  *
  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.
  14  *
  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.
  19  */
  20
  21 /**
  22  * SECTION:gtkfilefilter
  23  * @Short_description: A filter for selecting a file subset
  24  * @Title: GtkFileFilter
  25  *
  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()).
  31  *
  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/&ast;.
  37  *
  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().
  41  *
  42  * <refsect2 id="GtkFileFilter-BUILDER-UI">
  43  * <title>GtkFileFilter as GtkBuildable</title>
  44  * <para>
  45  * The GtkFileFilter implementation of the GtkBuildable interface
  46  * supports adding rules using the &lt;mime-types&gt, &lt;patterns&gt and
  47  * &lt;applications&gt elements and listing the rules within. Specifying
  48  * a &lt;mime-type&gt or &lt;pattern&gt is the same
  49  * as calling gtk_recent_filter_add_mime_type() or gtk_recent_filter_add_pattern()
  50  *
  51  * <example>
  52  * <title>A UI definition fragment specifying GtkFileFilter rules</title>
  53  * <programlisting><![CDATA[
  54  * <object class="GtkFileFilter">
  55  *   <mime-types>
  56  *     <mime-type>text/plain</mime-type>
  57  *     <mime-type>image/&ast;</mime-type>
  58  *   </mime-types>
  59  *   <patterns>
  60  *     <pattern>*.txt</pattern>
  61  *     <pattern>*.png</pattern>
  62  *   </patterns>
  63  * </object>
  64  * ]]></programlisting>
  65  * </example>
  66  * </para>
  67  * </refsect2>
  68  *
  69  * @see_also: #GtkFileChooser
  70  */
  71
  72 #include "config.h"
  73 #include <string.h>
  74
  75 #include <gdk-pixbuf/gdk-pixbuf.h>
  76
  77 #include "gtkfilefilter.h"
  78 #include "gtkbuildable.h"
  79 #include "gtkintl.h"
  80 #include "gtkprivate.h"
  81
  82 typedef struct _GtkFileFilterClass GtkFileFilterClass;
  83 typedef struct _FilterRule FilterRule;
  84
  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))
  88
  89 typedef enum {
  90   FILTER_RULE_PATTERN,
  91   FILTER_RULE_MIME_TYPE,
  92   FILTER_RULE_PIXBUF_FORMATS,
  93   FILTER_RULE_CUSTOM
  94 } FilterRuleType;
  95
  96 struct _GtkFileFilterClass
  97 {
  98   GInitiallyUnownedClass parent_class;
  99 };
 100
 101 struct _GtkFileFilter
 102 {
 103   GInitiallyUnowned parent_instance;
 104
 105   gchar *name;
 106   GSList *rules;
 107
 108   GtkFileFilterFlags needed;
 109 };
 110
 111 struct _FilterRule
 112 {
 113   FilterRuleType type;
 114   GtkFileFilterFlags needed;
 115
 116   union {
 117     gchar *pattern;
 118     gchar *mime_type;
 119     GSList *pixbuf_formats;
 120     struct {
 121       GtkFileFilterFunc func;
 122       gpointer data;
 123       GDestroyNotify notify;
 124     } custom;
 125   } u;
 126 };
 127
 128 static void gtk_file_filter_finalize   (GObject            *object);
 129
 130
 131 static void     gtk_file_filter_buildable_init                 (GtkBuildableIface *iface);
 132 static gboolean gtk_file_filter_buildable_custom_tag_start     (GtkBuildable  *buildable,
 133                                                                 GtkBuilder    *builder,
 134                                                                 GObject       *child,
 135                                                                 const gchar   *tagname,
 136                                                                 GMarkupParser *parser,
 137                                                                 gpointer      *data);
 138 static void     gtk_file_filter_buildable_custom_tag_end       (GtkBuildable  *buildable,
 139                                                                 GtkBuilder    *builder,
 140                                                                 GObject       *child,
 141                                                                 const gchar   *tagname,
 142                                                                 gpointer      *data);
 143
 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))
 147
 148 static void
 149 gtk_file_filter_init (GtkFileFilter *object)
 150 {
 151 }
 152
 153 static void
 154 gtk_file_filter_class_init (GtkFileFilterClass *class)
 155 {
 156   GObjectClass *gobject_class = G_OBJECT_CLASS (class);
 157
 158   gobject_class->finalize = gtk_file_filter_finalize;
 159 }
 160
 161 static void
 162 filter_rule_free (FilterRule *rule)
 163 {
 164   switch (rule->type)
 165     {
 166     case FILTER_RULE_MIME_TYPE:
 167       g_free (rule->u.mime_type);
 168       break;
 169     case FILTER_RULE_PATTERN:
 170       g_free (rule->u.pattern);
 171       break;
 172     case FILTER_RULE_CUSTOM:
 173       if (rule->u.custom.notify)
 174         rule->u.custom.notify (rule->u.custom.data);
 175       break;
 176     case FILTER_RULE_PIXBUF_FORMATS:
 177       g_slist_free (rule->u.pixbuf_formats);
 178       break;
 179     default:
 180       g_assert_not_reached ();
 181     }
 182
 183   g_slice_free (FilterRule, rule);
 184 }
 185
 186 static void
 187 gtk_file_filter_finalize (GObject  *object)
 188 {
 189   GtkFileFilter *filter = GTK_FILE_FILTER (object);
 190
 191   g_slist_foreach (filter->rules, (GFunc)filter_rule_free, NULL);
 192   g_slist_free (filter->rules);
 193
 194   g_free (filter->name);
 195
 196   G_OBJECT_CLASS (gtk_file_filter_parent_class)->finalize (object);
 197 }
 198
 199 /*
 200  * GtkBuildable implementation
 201  */
 202 static void
 203 gtk_file_filter_buildable_init (GtkBuildableIface *iface)
 204 {
 205   iface->custom_tag_start = gtk_file_filter_buildable_custom_tag_start;
 206   iface->custom_tag_end = gtk_file_filter_buildable_custom_tag_end;
 207 }
 208
 209 typedef enum {
 210   PARSE_MIME_TYPES,
 211   PARSE_PATTERNS
 212 } ParserType;
 213
 214 typedef struct {
 215   GtkFileFilter *filter;
 216   ParserType     type;
 217   GString       *string;
 218   gboolean       parsing;
 219 } SubParserData;
 220
 221 static void
 222 parser_start_element (GMarkupParseContext *context,
 223                       const gchar         *element_name,
 224                       const gchar        **names,
 225                       const gchar        **values,
 226                       gpointer             user_data,
 227                       GError             **error)
 228 {
 229   SubParserData *parser_data = (SubParserData*)user_data;
 230
 231   if (strcmp (element_name, "mime-types") == 0)
 232     return;
 233   else if (strcmp (element_name, "mime-type") == 0)
 234     {
 235       parser_data->parsing = TRUE;
 236       return;
 237     }
 238   else if (strcmp (element_name, "patterns") == 0)
 239     return;
 240   else if (strcmp (element_name, "pattern") == 0)
 241     {
 242       parser_data->parsing = TRUE;
 243       return;
 244     }
 245   else
 246     g_warning ("Unsupported tag for GtkFileFilter: %s\n", element_name);
 247 }
 248
 249 static void
 250 parser_text_element (GMarkupParseContext *context,
 251                      const gchar         *text,
 252                      gsize                text_len,
 253                      gpointer             user_data,
 254                      GError             **error)
 255 {
 256   SubParserData *parser_data = (SubParserData*)user_data;
 257
 258   if (parser_data->parsing)
 259     g_string_append_len (parser_data->string, text, text_len);
 260 }
 261
 262 static void
 263 parser_end_element (GMarkupParseContext *context,
 264                     const gchar         *element_name,
 265                     gpointer             user_data,
 266                     GError             **error)
 267 {
 268   SubParserData *parser_data = (SubParserData*)user_data;
 269
 270   if (parser_data->string)
 271     {
 272       switch (parser_data->type)
 273         {
 274         case PARSE_MIME_TYPES:
 275           gtk_file_filter_add_mime_type (parser_data->filter, parser_data->string->str);
 276           break;
 277         case PARSE_PATTERNS:
 278           gtk_file_filter_add_pattern (parser_data->filter, parser_data->string->str);
 279           break;
 280         default:
 281           break;
 282         }
 283     }
 284
 285   g_string_set_size (parser_data->string, 0);
 286   parser_data->parsing = FALSE;
 287 }
 288
 289 static const GMarkupParser sub_parser =
 290   {
 291     parser_start_element,
 292     parser_end_element,
 293     parser_text_element,
 294   };
 295
 296 static gboolean
 297 gtk_file_filter_buildable_custom_tag_start (GtkBuildable  *buildable,
 298                                               GtkBuilder    *builder,
 299                                               GObject       *child,
 300                                               const gchar   *tagname,
 301                                               GMarkupParser *parser,
 302                                               gpointer      *data)
 303 {
 304   SubParserData *parser_data = NULL;
 305
 306   if (strcmp (tagname, "mime-types") == 0)
 307     {
 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);
 312
 313       *parser = sub_parser;
 314       *data = parser_data;
 315     }
 316   else if (strcmp (tagname, "patterns") == 0)
 317     {
 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);
 322
 323       *parser = sub_parser;
 324       *data = parser_data;
 325     }
 326
 327   return parser_data != NULL;
 328 }
 329
 330 static void
 331 gtk_file_filter_buildable_custom_tag_end (GtkBuildable *buildable,
 332                                           GtkBuilder   *builder,
 333                                           GObject      *child,
 334                                           const gchar  *tagname,
 335                                           gpointer     *data)
 336 {
 337   if (strcmp (tagname, "mime-types") == 0 ||
 338       strcmp (tagname, "patterns") == 0)
 339     {
 340       SubParserData *parser_data = (SubParserData*)data;
 341
 342       g_string_free (parser_data->string, TRUE);
 343       g_slice_free (SubParserData, parser_data);
 344     }
 345 }
 346
 347
 348 /**
 349  * gtk_file_filter_new:
 350  *
 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:
 357  * |[
 358  * GtkFileFilter *filter = gtk_file_filter_new ();
 359  * gtk_file_filter_add_pattern (filter, "*");
 360  * ]|
 361  *
 362  * Return value: a new #GtkFileFilter
 363  *
 364  * Since: 2.4
 365  **/
 366 GtkFileFilter *
 367 gtk_file_filter_new (void)
 368 {
 369   return g_object_new (GTK_TYPE_FILE_FILTER, NULL);
 370 }
 371
 372 /**
 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.
 377  *
 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.
 381  *
 382  * Since: 2.4
 383  **/
 384 void
 385 gtk_file_filter_set_name (GtkFileFilter *filter,
 386                           const gchar   *name)
 387 {
 388   g_return_if_fail (GTK_IS_FILE_FILTER (filter));
 389
 390   g_free (filter->name);
 391
 392   filter->name = g_strdup (name);
 393 }
 394
 395 /**
 396  * gtk_file_filter_get_name:
 397  * @filter: a #GtkFileFilter
 398  *
 399  * Gets the human-readable name for the filter. See gtk_file_filter_set_name().
 400  *
 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.
 404  *
 405  * Since: 2.4
 406  **/
 407 G_CONST_RETURN gchar *
 408 gtk_file_filter_get_name (GtkFileFilter *filter)
 409 {
 410   g_return_val_if_fail (GTK_IS_FILE_FILTER (filter), NULL);
 411
 412   return filter->name;
 413 }
 414
 415 static void
 416 file_filter_add_rule (GtkFileFilter *filter,
 417                       FilterRule    *rule)
 418 {
 419   filter->needed |= rule->needed;
 420   filter->rules = g_slist_append (filter->rules, rule);
 421 }
 422
 423 /**
 424  * gtk_file_filter_add_mime_type:
 425  * @filter: A #GtkFileFilter
 426  * @mime_type: name of a MIME type
 427  *
 428  * Adds a rule allowing a given mime type to @filter.
 429  *
 430  * Since: 2.4
 431  **/
 432 void
 433 gtk_file_filter_add_mime_type (GtkFileFilter *filter,
 434                                const gchar   *mime_type)
 435 {
 436   FilterRule *rule;
 437
 438   g_return_if_fail (GTK_IS_FILE_FILTER (filter));
 439   g_return_if_fail (mime_type != NULL);
 440
 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);
 445
 446   file_filter_add_rule (filter, rule);
 447 }
 448
 449 /**
 450  * gtk_file_filter_add_pattern:
 451  * @filter: a #GtkFileFilter
 452  * @pattern: a shell style glob
 453  *
 454  * Adds a rule allowing a shell style glob to a filter.
 455  *
 456  * Since: 2.4
 457  **/
 458 void
 459 gtk_file_filter_add_pattern (GtkFileFilter *filter,
 460                              const gchar   *pattern)
 461 {
 462   FilterRule *rule;
 463
 464   g_return_if_fail (GTK_IS_FILE_FILTER (filter));
 465   g_return_if_fail (pattern != NULL);
 466
 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);
 471
 472   file_filter_add_rule (filter, rule);
 473 }
 474
 475 /**
 476  * gtk_file_filter_add_pixbuf_formats:
 477  * @filter: a #GtkFileFilter
 478  *
 479  * Adds a rule allowing image files in the formats supported
 480  * by GdkPixbuf.
 481  *
 482  * Since: 2.6
 483  **/
 484 void
 485 gtk_file_filter_add_pixbuf_formats (GtkFileFilter *filter)
 486 {
 487   FilterRule *rule;
 488
 489   g_return_if_fail (GTK_IS_FILE_FILTER (filter));
 490
 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);
 496 }
 497
 498
 499 /**
 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.
 508  *
 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.
 514  *
 515  * Since: 2.4
 516  **/
 517 void
 518 gtk_file_filter_add_custom (GtkFileFilter         *filter,
 519                             GtkFileFilterFlags     needed,
 520                             GtkFileFilterFunc      func,
 521                             gpointer               data,
 522                             GDestroyNotify         notify)
 523 {
 524   FilterRule *rule;
 525
 526   g_return_if_fail (GTK_IS_FILE_FILTER (filter));
 527   g_return_if_fail (func != NULL);
 528
 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;
 535
 536   file_filter_add_rule (filter, rule);
 537 }
 538
 539 /**
 540  * gtk_file_filter_get_needed:
 541  * @filter: a #GtkFileFilter
 542  *
 543  * Gets the fields that need to be filled in for the structure
 544  * passed to gtk_file_filter_filter()
 545  *
 546  * This function will not typically be used by applications; it
 547  * is intended principally for use in the implementation of
 548  * #GtkFileChooser.
 549  *
 550  * Return value: bitfield of flags indicating needed fields when
 551  *   calling gtk_file_filter_filter()
 552  *
 553  * Since: 2.4
 554  **/
 555 GtkFileFilterFlags
 556 gtk_file_filter_get_needed (GtkFileFilter *filter)
 557 {
 558   return filter->needed;
 559 }
 560
 561 /**
 562  * gtk_file_filter_filter:
 563  * @filter: a #GtkFileFilter
 564  * @filter_info: a #GtkFileFilterInfo structure containing information
 565  *  about a file.
 566  *
 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().
 570  *
 571  * This function will not typically be used by applications; it
 572  * is intended principally for use in the implementation of
 573  * #GtkFileChooser.
 574  *
 575  * Return value: %TRUE if the file should be displayed
 576  *
 577  * Since: 2.4
 578  **/
 579 gboolean
 580 gtk_file_filter_filter (GtkFileFilter           *filter,
 581                         const GtkFileFilterInfo *filter_info)
 582 {
 583   GSList *tmp_list;
 584
 585   for (tmp_list = filter->rules; tmp_list; tmp_list = tmp_list->next)
 586     {
 587       FilterRule *rule = tmp_list->data;
 588
 589       if ((filter_info->contains & rule->needed) != rule->needed)
 590         continue;
 591
 592       switch (rule->type)
 593         {
 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))
 597             return TRUE;
 598           break;
 599         case FILTER_RULE_PATTERN:
 600           if (filter_info->display_name != NULL &&
 601               _gtk_fnmatch (rule->u.pattern, filter_info->display_name, FALSE))
 602             return TRUE;
 603           break;
 604         case FILTER_RULE_PIXBUF_FORMATS:
 605           {
 606             GSList *list;
 607
 608             if (!filter_info->mime_type)
 609               break;
 610
 611             for (list = rule->u.pixbuf_formats; list; list = list->next)
 612               {
 613                 int i;
 614                 gchar **mime_types;
 615
 616                 mime_types = gdk_pixbuf_format_get_mime_types (list->data);
 617
 618                 for (i = 0; mime_types[i] != NULL; i++)
 619                   {
 620                     if (strcmp (mime_types[i], filter_info->mime_type) == 0)
 621                       {
 622                         g_strfreev (mime_types);
 623                         return TRUE;
 624                       }
 625                   }
 626
 627                 g_strfreev (mime_types);
 628               }
 629             break;
 630           }
 631         case FILTER_RULE_CUSTOM:
 632           if (rule->u.custom.func (filter_info, rule->u.custom.data))
 633             return TRUE;
 634           break;
 635         }
 636     }
 637
 638   return FALSE;
 639 }