gio/gicon.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright (C) 2006-2007 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
  16  * Public 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  * Author: Alexander Larsson <alexl@redhat.com>
  21  */
  22
  23 #include "config.h"
  24 #include <stdlib.h>
  25 #include <string.h>
  26
  27 #include "gicon.h"
  28 #include "gthemedicon.h"
  29 #include "gfileicon.h"
  30 #include "gemblemedicon.h"
  31 #include "gbytesicon.h"
  32 #include "gfile.h"
  33 #include "gioerror.h"
  34 #include "gioenumtypes.h"
  35 #include "gvfs.h"
  36
  37 #include "glibintl.h"
  38
  39
  40 /* There versioning of this is implicit, version 1 would be ".1 " */
  41 #define G_ICON_SERIALIZATION_MAGIC0 ". "
  42
  43 /**
  44  * SECTION:gicon
  45  * @short_description: Interface for icons
  46  * @include: gio/gio.h
  47  *
  48  * #GIcon is a very minimal interface for icons. It provides functions
  49  * for checking the equality of two icons, hashing of icons and
  50  * serializing an icon to and from strings.
  51  *
  52  * #GIcon does not provide the actual pixmap for the icon as this is out
  53  * of GIO's scope, however implementations of #GIcon may contain the name
  54  * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
  55  *
  56  * To obtain a hash of a #GIcon, see g_icon_hash().
  57  *
  58  * To check if two #GIcons are equal, see g_icon_equal().
  59  *
  60  * For serializing a #GIcon, use g_icon_serialize() and
  61  * g_icon_deserialize().
  62  *
  63  * If you want to consume #GIcon (for example, in a toolkit) you must
  64  * be prepared to handle at least the three following cases:
  65  * #GLoadableIcon, #GThemedIcon and #GEmblemedIcon.  It may also make
  66  * sense to have fast-paths for other cases (like handling #GdkPixbuf
  67  * directly, for example) but all compliant #GIcon implementations
  68  * outside of GIO must implement #GLoadableIcon.
  69  *
  70  * If your application or library provides one or more #GIcon
  71  * implementations you need to ensure that your new implementation also
  72  * implements #GLoadableIcon.  Additionally, you must provide an
  73  * implementation of g_icon_serialize() that gives a result that is
  74  * understood by g_icon_deserialize(), yielding one of the built-in icon
  75  * types.
  76  **/
  77
  78 typedef GIconIface GIconInterface;
  79 G_DEFINE_INTERFACE(GIcon, g_icon, G_TYPE_OBJECT)
  80
  81 static void
  82 g_icon_default_init (GIconInterface *iface)
  83 {
  84 }
  85
  86 /**
  87  * g_icon_hash:
  88  * @icon: #gconstpointer to an icon object.
  89  *
  90  * Gets a hash for an icon.
  91  *
  92  * Virtual: hash
  93  * Returns: a #guint containing a hash for the @icon, suitable for
  94  * use in a #GHashTable or similar data structure.
  95  **/
  96 guint
  97 g_icon_hash (gconstpointer icon)
  98 {
  99   GIconIface *iface;
 100
 101   g_return_val_if_fail (G_IS_ICON (icon), 0);
 102
 103   iface = G_ICON_GET_IFACE (icon);
 104
 105   return (* iface->hash) ((GIcon *)icon);
 106 }
 107
 108 /**
 109  * g_icon_equal:
 110  * @icon1: (allow-none): pointer to the first #GIcon.
 111  * @icon2: (allow-none): pointer to the second #GIcon.
 112  *
 113  * Checks if two icons are equal.
 114  *
 115  * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
 116  **/
 117 gboolean
 118 g_icon_equal (GIcon *icon1,
 119               GIcon *icon2)
 120 {
 121   GIconIface *iface;
 122
 123   if (icon1 == NULL && icon2 == NULL)
 124     return TRUE;
 125
 126   if (icon1 == NULL || icon2 == NULL)
 127     return FALSE;
 128
 129   if (G_TYPE_FROM_INSTANCE (icon1) != G_TYPE_FROM_INSTANCE (icon2))
 130     return FALSE;
 131
 132   iface = G_ICON_GET_IFACE (icon1);
 133
 134   return (* iface->equal) (icon1, icon2);
 135 }
 136
 137 static gboolean
 138 g_icon_to_string_tokenized (GIcon *icon, GString *s)
 139 {
 140   GPtrArray *tokens;
 141   gint version;
 142   GIconIface *icon_iface;
 143   int i;
 144
 145   g_return_val_if_fail (icon != NULL, FALSE);
 146   g_return_val_if_fail (G_IS_ICON (icon), FALSE);
 147
 148   icon_iface = G_ICON_GET_IFACE (icon);
 149   if (icon_iface->to_tokens == NULL)
 150     return FALSE;
 151
 152   tokens = g_ptr_array_new ();
 153   if (!icon_iface->to_tokens (icon, tokens, &version))
 154     {
 155       g_ptr_array_free (tokens, TRUE);
 156       return FALSE;
 157     }
 158
 159   /* format: TypeName[.Version] <token_0> .. <token_N-1>
 160      version 0 is implicit and can be omitted
 161      all the tokens are url escaped to ensure they have no spaces in them */
 162
 163   g_string_append (s, g_type_name_from_instance ((GTypeInstance *)icon));
 164   if (version != 0)
 165     g_string_append_printf (s, ".%d", version);
 166
 167   for (i = 0; i < tokens->len; i++)
 168     {
 169       char *token;
 170
 171       token = g_ptr_array_index (tokens, i);
 172
 173       g_string_append_c (s, ' ');
 174       /* We really only need to escape spaces here, so allow lots of otherwise reserved chars */
 175       g_string_append_uri_escaped (s, token,
 176                                    G_URI_RESERVED_CHARS_ALLOWED_IN_PATH, TRUE);
 177
 178       g_free (token);
 179     }
 180
 181   g_ptr_array_free (tokens, TRUE);
 182
 183   return TRUE;
 184 }
 185
 186 /**
 187  * g_icon_to_string:
 188  * @icon: a #GIcon.
 189  *
 190  * Generates a textual representation of @icon that can be used for
 191  * serialization such as when passing @icon to a different process or
 192  * saving it to persistent storage. Use g_icon_new_for_string() to
 193  * get @icon back from the returned string.
 194  *
 195  * The encoding of the returned string is proprietary to #GIcon except
 196  * in the following two cases
 197  *
 198  * <itemizedlist>
 199  * <listitem><para>
 200  *     If @icon is a #GFileIcon, the returned string is a native path
 201  *     (such as <literal>/path/to/my icon.png</literal>) without escaping
 202  *     if the #GFile for @icon is a native file.  If the file is not
 203  *     native, the returned string is the result of g_file_get_uri()
 204  *     (such as <literal>sftp://path/to/my&percnt;20icon.png</literal>).
 205  * </para></listitem>
 206  * <listitem><para>
 207  *    If @icon is a #GThemedIcon with exactly one name, the encoding is
 208  *    simply the name (such as <literal>network-server</literal>).
 209  * </para></listitem>
 210  * </itemizedlist>
 211  *
 212  * Virtual: to_tokens
 213  * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't
 214  * be serialized. Use g_free() to free.
 215  *
 216  * Since: 2.20
 217  */
 218 gchar *
 219 g_icon_to_string (GIcon *icon)
 220 {
 221   gchar *ret;
 222
 223   g_return_val_if_fail (icon != NULL, NULL);
 224   g_return_val_if_fail (G_IS_ICON (icon), NULL);
 225
 226   ret = NULL;
 227
 228   if (G_IS_FILE_ICON (icon))
 229     {
 230       GFile *file;
 231
 232       file = g_file_icon_get_file (G_FILE_ICON (icon));
 233       if (g_file_is_native (file))
 234         {
 235           ret = g_file_get_path (file);
 236           if (!g_utf8_validate (ret, -1, NULL))
 237             {
 238               g_free (ret);
 239               ret = NULL;
 240             }
 241         }
 242       else
 243         ret = g_file_get_uri (file);
 244     }
 245   else if (G_IS_THEMED_ICON (icon))
 246     {
 247       const char * const *names;
 248
 249       names = g_themed_icon_get_names (G_THEMED_ICON (icon));
 250       if (names != NULL &&
 251           names[0] != NULL &&
 252           names[0][0] != '.' && /* Allowing icons starting with dot would break G_ICON_SERIALIZATION_MAGIC0 */
 253           g_utf8_validate (names[0], -1, NULL) && /* Only return utf8 strings */
 254           names[1] == NULL)
 255         ret = g_strdup (names[0]);
 256     }
 257
 258   if (ret == NULL)
 259     {
 260       GString *s;
 261
 262       s = g_string_new (G_ICON_SERIALIZATION_MAGIC0);
 263
 264       if (g_icon_to_string_tokenized (icon, s))
 265         ret = g_string_free (s, FALSE);
 266       else
 267         g_string_free (s, TRUE);
 268     }
 269
 270   return ret;
 271 }
 272
 273 static GIcon *
 274 g_icon_new_from_tokens (char   **tokens,
 275                         GError **error)
 276 {
 277   GIcon *icon;
 278   char *typename, *version_str;
 279   GType type;
 280   gpointer klass;
 281   GIconIface *icon_iface;
 282   gint version;
 283   char *endp;
 284   int num_tokens;
 285   int i;
 286
 287   icon = NULL;
 288   klass = NULL;
 289
 290   num_tokens = g_strv_length (tokens);
 291
 292   if (num_tokens < 1)
 293     {
 294       g_set_error (error,
 295                    G_IO_ERROR,
 296                    G_IO_ERROR_INVALID_ARGUMENT,
 297                    _("Wrong number of tokens (%d)"),
 298                    num_tokens);
 299       goto out;
 300     }
 301
 302   typename = tokens[0];
 303   version_str = strchr (typename, '.');
 304   if (version_str)
 305     {
 306       *version_str = 0;
 307       version_str += 1;
 308     }
 309
 310
 311   type = g_type_from_name (tokens[0]);
 312   if (type == 0)
 313     {
 314       g_set_error (error,
 315                    G_IO_ERROR,
 316                    G_IO_ERROR_INVALID_ARGUMENT,
 317                    _("No type for class name %s"),
 318                    tokens[0]);
 319       goto out;
 320     }
 321
 322   if (!g_type_is_a (type, G_TYPE_ICON))
 323     {
 324       g_set_error (error,
 325                    G_IO_ERROR,
 326                    G_IO_ERROR_INVALID_ARGUMENT,
 327                    _("Type %s does not implement the GIcon interface"),
 328                    tokens[0]);
 329       goto out;
 330     }
 331
 332   klass = g_type_class_ref (type);
 333   if (klass == NULL)
 334     {
 335       g_set_error (error,
 336                    G_IO_ERROR,
 337                    G_IO_ERROR_INVALID_ARGUMENT,
 338                    _("Type %s is not classed"),
 339                    tokens[0]);
 340       goto out;
 341     }
 342
 343   version = 0;
 344   if (version_str)
 345     {
 346       version = strtol (version_str, &endp, 10);
 347       if (endp == NULL || *endp != '\0')
 348         {
 349           g_set_error (error,
 350                        G_IO_ERROR,
 351                        G_IO_ERROR_INVALID_ARGUMENT,
 352                        _("Malformed version number: %s"),
 353                        version_str);
 354           goto out;
 355         }
 356     }
 357
 358   icon_iface = g_type_interface_peek (klass, G_TYPE_ICON);
 359   g_assert (icon_iface != NULL);
 360
 361   if (icon_iface->from_tokens == NULL)
 362     {
 363       g_set_error (error,
 364                    G_IO_ERROR,
 365                    G_IO_ERROR_INVALID_ARGUMENT,
 366                    _("Type %s does not implement from_tokens() on the GIcon interface"),
 367                    tokens[0]);
 368       goto out;
 369     }
 370
 371   for (i = 1;  i < num_tokens; i++)
 372     {
 373       char *escaped;
 374
 375       escaped = tokens[i];
 376       tokens[i] = g_uri_unescape_string (escaped, NULL);
 377       g_free (escaped);
 378     }
 379
 380   icon = icon_iface->from_tokens (tokens + 1, num_tokens - 1, version, error);
 381
 382  out:
 383   if (klass != NULL)
 384     g_type_class_unref (klass);
 385   return icon;
 386 }
 387
 388 static void
 389 ensure_builtin_icon_types (void)
 390 {
 391   g_type_ensure (G_TYPE_THEMED_ICON);
 392   g_type_ensure (G_TYPE_FILE_ICON);
 393   g_type_ensure (G_TYPE_EMBLEMED_ICON);
 394   g_type_ensure (G_TYPE_EMBLEM);
 395 }
 396
 397 /* handles the 'simple' cases: GFileIcon and GThemedIcon */
 398 static GIcon *
 399 g_icon_new_for_string_simple (const gchar *str)
 400 {
 401   gchar *scheme;
 402   GIcon *icon;
 403
 404   if (str[0] == '.')
 405     return NULL;
 406
 407   /* handle special GFileIcon and GThemedIcon cases */
 408   scheme = g_uri_parse_scheme (str);
 409   if (scheme != NULL || str[0] == '/' || str[0] == G_DIR_SEPARATOR)
 410     {
 411       GFile *location;
 412       location = g_file_new_for_commandline_arg (str);
 413       icon = g_file_icon_new (location);
 414       g_object_unref (location);
 415     }
 416   else
 417     icon = g_themed_icon_new (str);
 418
 419   g_free (scheme);
 420
 421   return icon;
 422 }
 423
 424 /**
 425  * g_icon_new_for_string:
 426  * @str: A string obtained via g_icon_to_string().
 427  * @error: Return location for error.
 428  *
 429  * Generate a #GIcon instance from @str. This function can fail if
 430  * @str is not valid - see g_icon_to_string() for discussion.
 431  *
 432  * If your application or library provides one or more #GIcon
 433  * implementations you need to ensure that each #GType is registered
 434  * with the type system prior to calling g_icon_new_for_string().
 435  *
 436  * Returns: (transfer full): An object implementing the #GIcon
 437  *          interface or %NULL if @error is set.
 438  *
 439  * Since: 2.20
 440  **/
 441 GIcon *
 442 g_icon_new_for_string (const gchar   *str,
 443                        GError       **error)
 444 {
 445   GIcon *icon = NULL;
 446
 447   g_return_val_if_fail (str != NULL, NULL);
 448
 449   icon = g_icon_new_for_string_simple (str);
 450   if (icon)
 451     return icon;
 452
 453   ensure_builtin_icon_types ();
 454
 455   if (g_str_has_prefix (str, G_ICON_SERIALIZATION_MAGIC0))
 456     {
 457       gchar **tokens;
 458
 459       /* handle tokenized encoding */
 460       tokens = g_strsplit (str + sizeof (G_ICON_SERIALIZATION_MAGIC0) - 1, " ", 0);
 461       icon = g_icon_new_from_tokens (tokens, error);
 462       g_strfreev (tokens);
 463     }
 464   else
 465     g_set_error_literal (error,
 466                          G_IO_ERROR,
 467                          G_IO_ERROR_INVALID_ARGUMENT,
 468                          _("Can't handle the supplied version of the icon encoding"));
 469
 470   return icon;
 471 }
 472
 473 static GEmblem *
 474 g_icon_deserialize_emblem (GVariant *value)
 475 {
 476   GVariant *emblem_metadata;
 477   GVariant *emblem_data;
 478   const gchar *origin_nick;
 479   GIcon *emblem_icon;
 480   GEmblem *emblem;
 481
 482   g_variant_get (value, "(v@a{sv})", &emblem_data, &emblem_metadata);
 483
 484   emblem = NULL;
 485
 486   emblem_icon = g_icon_deserialize (emblem_data);
 487   if (emblem_icon != NULL)
 488     {
 489       /* Check if we should create it with an origin. */
 490       if (g_variant_lookup (emblem_metadata, "origin", "&s", &origin_nick))
 491         {
 492           GEnumClass *origin_class;
 493           GEnumValue *origin_value;
 494
 495           origin_class = g_type_class_ref (G_TYPE_EMBLEM_ORIGIN);
 496           origin_value = g_enum_get_value_by_nick (origin_class, origin_nick);
 497           if (origin_value)
 498             emblem = g_emblem_new_with_origin (emblem_icon, origin_value->value);
 499           g_type_class_unref (origin_class);
 500         }
 501
 502       /* We didn't create it with an origin, so do it without. */
 503       if (emblem == NULL)
 504         emblem = g_emblem_new (emblem_icon);
 505
 506       g_object_unref (emblem_icon);
 507     }
 508
 509   g_variant_unref (emblem_metadata);
 510   g_variant_unref (emblem_data);
 511
 512   return emblem;
 513 }
 514
 515 static GIcon *
 516 g_icon_deserialize_emblemed (GVariant *value)
 517 {
 518   GVariantIter *emblems;
 519   GVariant *icon_data;
 520   GIcon *main_icon;
 521   GIcon *icon;
 522
 523   g_variant_get (value, "(va(va{sv}))", &icon_data, &emblems);
 524   main_icon = g_icon_deserialize (icon_data);
 525
 526   if (main_icon)
 527     {
 528       GVariant *emblem_data;
 529
 530       icon = g_emblemed_icon_new (main_icon, NULL);
 531
 532       while ((emblem_data = g_variant_iter_next_value (emblems)))
 533         {
 534           GEmblem *emblem;
 535
 536           emblem = g_icon_deserialize_emblem (emblem_data);
 537
 538           if (emblem)
 539             {
 540               g_emblemed_icon_add_emblem (G_EMBLEMED_ICON (icon), emblem);
 541               g_object_unref (emblem);
 542             }
 543
 544           g_variant_unref (emblem_data);
 545         }
 546
 547       g_object_unref (main_icon);
 548     }
 549   else
 550     icon = NULL;
 551
 552   g_variant_iter_free (emblems);
 553   g_variant_unref (icon_data);
 554
 555   return icon;
 556 }
 557
 558 /**
 559  * g_icon_deserialize:
 560  * @value: a #GVariant created with g_icon_serialize()
 561  *
 562  * Deserializes a #GIcon previously serialized using g_icon_serialize().
 563  *
 564  * Returns: (transfer full): a #GIcon, or %NULL when deserialization fails.
 565  *
 566  * Since: 2.38
 567  */
 568 GIcon *
 569 g_icon_deserialize (GVariant *value)
 570 {
 571   const gchar *tag;
 572   GVariant *val;
 573   GIcon *icon;
 574
 575   g_return_val_if_fail (value != NULL, NULL);
 576   g_return_val_if_fail (g_variant_is_of_type (value, G_VARIANT_TYPE_STRING) ||
 577                         g_variant_is_of_type (value, G_VARIANT_TYPE ("(sv)")), NULL);
 578
 579   /* Handle some special cases directly so that people can hard-code
 580    * stuff into GMenuModel xml files without resorting to using GVariant
 581    * text format to describe one of the explicitly-tagged possibilities
 582    * below.
 583    */
 584   if (g_variant_is_of_type (value, G_VARIANT_TYPE_STRING))
 585     return g_icon_new_for_string_simple (g_variant_get_string (value, NULL));
 586
 587   /* Otherwise, use the tagged union format */
 588   g_variant_get (value, "(&sv)", &tag, &val);
 589
 590   icon = NULL;
 591
 592   if (g_str_equal (tag, "file") && g_variant_is_of_type (val, G_VARIANT_TYPE_STRING))
 593     {
 594       GFile *file;
 595
 596       file = g_file_new_for_commandline_arg (g_variant_get_string (val, NULL));
 597       icon = g_file_icon_new (file);
 598       g_object_unref (file);
 599     }
 600   else if (g_str_equal (tag, "themed") && g_variant_is_of_type (val, G_VARIANT_TYPE_STRING_ARRAY))
 601     {
 602       const gchar **names;
 603       gsize size;
 604
 605       names = g_variant_get_strv (val, &size);
 606       icon = g_themed_icon_new_from_names ((gchar **) names, size);
 607       g_free (names);
 608     }
 609   else if (g_str_equal (tag, "bytes") && g_variant_is_of_type (val, G_VARIANT_TYPE_BYTESTRING))
 610     {
 611       GBytes *bytes;
 612
 613       bytes = g_variant_get_data_as_bytes (val);
 614       icon = g_bytes_icon_new (bytes);
 615       g_bytes_unref (bytes);
 616     }
 617   else if (g_str_equal (tag, "emblem") && g_variant_is_of_type (val, G_VARIANT_TYPE ("(va{sv})")))
 618     {
 619       GEmblem *emblem;
 620
 621       emblem = g_icon_deserialize_emblem (val);
 622       if (emblem)
 623         icon = G_ICON (emblem);
 624     }
 625   else if (g_str_equal (tag, "emblemed") && g_variant_is_of_type (val, G_VARIANT_TYPE ("(va(va{sv}))")))
 626     {
 627       icon = g_icon_deserialize_emblemed (val);
 628     }
 629   else if (g_str_equal (tag, "gvfs"))
 630     {
 631       GVfsClass *class;
 632       GVfs *vfs;
 633
 634       vfs = g_vfs_get_default ();
 635       class = G_VFS_GET_CLASS (vfs);
 636       if (class->deserialize_icon)
 637         icon = (* class->deserialize_icon) (vfs, val);
 638     }
 639
 640   g_variant_unref (val);
 641
 642   return icon;
 643 }
 644
 645 /**
 646  * g_icon_serialize:
 647  * @icon: a #GIcon
 648  *
 649  * Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved
 650  * back by calling g_icon_deserialize() on the returned value.
 651  * As serialization will avoid using raw icon data when possible, it only
 652  * makes sense to transfer the #GVariant between processes on the same machine,
 653  * (as opposed to over the network), and within the same file system namespace.
 654  *
 655  * Returns: (transfer full): a #GVariant, or %NULL when serialization fails.
 656  *
 657  * Since: 2.38
 658  */
 659 GVariant *
 660 g_icon_serialize (GIcon *icon)
 661 {
 662   GIconInterface *iface;
 663   GVariant *result;
 664
 665   iface = G_ICON_GET_IFACE (icon);
 666
 667   if (!iface->serialize)
 668     {
 669       g_critical ("g_icon_serialize() on icon type '%s' is not implemented", G_OBJECT_TYPE_NAME (icon));
 670       return NULL;
 671     }
 672
 673   result = (* iface->serialize) (icon);
 674
 675   if (result)
 676     {
 677       g_variant_take_ref (result);
 678
 679       if (!g_variant_is_of_type (result, G_VARIANT_TYPE ("(sv)")))
 680         {
 681           g_critical ("g_icon_serialize() on icon type '%s' returned GVariant of type '%s' but it must return "
 682                       "one with type '(sv)'", G_OBJECT_TYPE_NAME (icon), g_variant_get_type_string (result));
 683           g_variant_unref (result);
 684           result = NULL;
 685         }
 686     }
 687
 688   return result;
 689 }