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