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 "gfile.h"
  32 #include "gioerror.h"
  33
  34 #include "glibintl.h"
  35
  36 #include "gioalias.h"
  37
  38 /* There versioning of this is implicit, version 1 would be ".1 " */
  39 #define G_ICON_SERIALIZATION_MAGIC0 ". "
  40
  41 /**
  42  * SECTION:gicon
  43  * @short_description: Interface for icons
  44  * @include: gio/gio.h
  45  *
  46  * #GIcon is a very minimal interface for icons. It provides functions
  47  * for checking the equality of two icons, hashing of icons and
  48  * serializing an icon to and from strings.
  49  *
  50  * #GIcon does not provide the actual pixmap for the icon as this is out
  51  * of GIO's scope, however implementations of #GIcon may contain the name
  52  * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
  53  *
  54  * To obtain a hash of a #GIcon, see g_icon_hash().
  55  *
  56  * To check if two #GIcons are equal, see g_icon_equal().
  57  *
  58  * For serializing a #GIcon, use g_icon_to_string() and
  59  * g_icon_new_for_string().
  60  *
  61  * If your application or library provides one or more #GIcon
  62  * implementations you need to ensure that each #GType is registered
  63  * with the type system prior to calling g_icon_new_for_string().
  64  **/
  65
  66 typedef GIconIface GIconInterface;
  67 G_DEFINE_INTERFACE(GIcon, g_icon, G_TYPE_OBJECT)
  68
  69 static void
  70 g_icon_default_init (GIconInterface *iface)
  71 {
  72 }
  73
  74 /**
  75  * g_icon_hash:
  76  * @icon: #gconstpointer to an icon object.
  77  *
  78  * Gets a hash for an icon.
  79  *
  80  * Returns: a #guint containing a hash for the @icon, suitable for
  81  * use in a #GHashTable or similar data structure.
  82  **/
  83 guint
  84 g_icon_hash (gconstpointer icon)
  85 {
  86   GIconIface *iface;
  87
  88   g_return_val_if_fail (G_IS_ICON (icon), 0);
  89
  90   iface = G_ICON_GET_IFACE (icon);
  91
  92   return (* iface->hash) ((GIcon *)icon);
  93 }
  94
  95 /**
  96  * g_icon_equal:
  97  * @icon1: pointer to the first #GIcon.
  98  * @icon2: pointer to the second #GIcon.
  99  *
 100  * Checks if two icons are equal.
 101  *
 102  * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
 103  **/
 104 gboolean
 105 g_icon_equal (GIcon *icon1,
 106               GIcon *icon2)
 107 {
 108   GIconIface *iface;
 109
 110   if (icon1 == NULL && icon2 == NULL)
 111     return TRUE;
 112
 113   if (icon1 == NULL || icon2 == NULL)
 114     return FALSE;
 115
 116   if (G_TYPE_FROM_INSTANCE (icon1) != G_TYPE_FROM_INSTANCE (icon2))
 117     return FALSE;
 118
 119   iface = G_ICON_GET_IFACE (icon1);
 120
 121   return (* iface->equal) (icon1, icon2);
 122 }
 123
 124 static gboolean
 125 g_icon_to_string_tokenized (GIcon *icon, GString *s)
 126 {
 127   char *ret;
 128   GPtrArray *tokens;
 129   gint version;
 130   GIconIface *icon_iface;
 131   int i;
 132
 133   g_return_val_if_fail (icon != NULL, FALSE);
 134   g_return_val_if_fail (G_IS_ICON (icon), FALSE);
 135
 136   ret = NULL;
 137
 138   icon_iface = G_ICON_GET_IFACE (icon);
 139   if (icon_iface->to_tokens == NULL)
 140     return FALSE;
 141
 142   tokens = g_ptr_array_new ();
 143   if (!icon_iface->to_tokens (icon, tokens, &version))
 144     {
 145       g_ptr_array_free (tokens, TRUE);
 146       return FALSE;
 147     }
 148
 149   /* format: TypeName[.Version] <token_0> .. <token_N-1>
 150      version 0 is implicit and can be omitted
 151      all the tokens are url escaped to ensure they have no spaces in them */
 152
 153   g_string_append (s, g_type_name_from_instance ((GTypeInstance *)icon));
 154   if (version != 0)
 155     g_string_append_printf (s, ".%d", version);
 156
 157   for (i = 0; i < tokens->len; i++)
 158     {
 159       char *token;
 160
 161       token = g_ptr_array_index (tokens, i);
 162
 163       g_string_append_c (s, ' ');
 164       /* We really only need to escape spaces here, so allow lots of otherwise reserved chars */
 165       g_string_append_uri_escaped (s, token,
 166                                    G_URI_RESERVED_CHARS_ALLOWED_IN_PATH, TRUE);
 167
 168       g_free (token);
 169     }
 170
 171   g_ptr_array_free (tokens, TRUE);
 172
 173   return TRUE;
 174 }
 175
 176 /**
 177  * g_icon_to_string:
 178  * @icon: a #GIcon.
 179  *
 180  * Generates a textual representation of @icon that can be used for
 181  * serialization such as when passing @icon to a different process or
 182  * saving it to persistent storage. Use g_icon_new_for_string() to
 183  * get @icon back from the returned string.
 184  *
 185  * The encoding of the returned string is proprietary to #GIcon except
 186  * in the following two cases
 187  *
 188  * <itemizedlist>
 189  * <listitem><para>
 190  *     If @icon is a #GFileIcon, the returned string is a native path
 191  *     (such as <literal>/path/to/my icon.png</literal>) without escaping
 192  *     if the #GFile for @icon is a native file.  If the file is not
 193  *     native, the returned string is the result of g_file_get_uri()
 194  *     (such as <literal>sftp://path/to/my%%20icon.png</literal>).
 195  * </para></listitem>
 196  * <listitem><para>
 197  *    If @icon is a #GThemedIcon with exactly one name, the encoding is
 198  *    simply the name (such as <literal>network-server</literal>).
 199  * </para></listitem>
 200  * </itemizedlist>
 201  *
 202  * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't
 203  * be serialized. Use g_free() to free.
 204  *
 205  * Since: 2.20
 206  */
 207 gchar *
 208 g_icon_to_string (GIcon *icon)
 209 {
 210   gchar *ret;
 211
 212   g_return_val_if_fail (icon != NULL, NULL);
 213   g_return_val_if_fail (G_IS_ICON (icon), NULL);
 214
 215   ret = NULL;
 216
 217   if (G_IS_FILE_ICON (icon))
 218     {
 219       GFile *file;
 220
 221       file = g_file_icon_get_file (G_FILE_ICON (icon));
 222       if (g_file_is_native (file))
 223         {
 224           ret = g_file_get_path (file);
 225           if (!g_utf8_validate (ret, -1, NULL))
 226             {
 227               g_free (ret);
 228               ret = NULL;
 229             }
 230         }
 231       else
 232         ret = g_file_get_uri (file);
 233     }
 234   else if (G_IS_THEMED_ICON (icon))
 235     {
 236       const char * const *names;
 237
 238       names = g_themed_icon_get_names (G_THEMED_ICON (icon));
 239       if (names != NULL &&
 240           names[0] != NULL &&
 241           names[0][0] != '.' && /* Allowing icons starting with dot would break G_ICON_SERIALIZATION_MAGIC0 */
 242           g_utf8_validate (names[0], -1, NULL) && /* Only return utf8 strings */
 243           names[1] == NULL)
 244         ret = g_strdup (names[0]);
 245     }
 246
 247   if (ret == NULL)
 248     {
 249       GString *s;
 250
 251       s = g_string_new (G_ICON_SERIALIZATION_MAGIC0);
 252
 253       if (g_icon_to_string_tokenized (icon, s))
 254         ret = g_string_free (s, FALSE);
 255       else
 256         g_string_free (s, TRUE);
 257     }
 258
 259   return ret;
 260 }
 261
 262 static GIcon *
 263 g_icon_new_from_tokens (char   **tokens,
 264                         GError **error)
 265 {
 266   GIcon *icon;
 267   char *typename, *version_str;
 268   GType type;
 269   gpointer klass;
 270   GIconIface *icon_iface;
 271   gint version;
 272   char *endp;
 273   int num_tokens;
 274   int i;
 275
 276   icon = NULL;
 277   klass = NULL;
 278
 279   num_tokens = g_strv_length (tokens);
 280
 281   if (num_tokens < 1)
 282     {
 283       g_set_error (error,
 284                    G_IO_ERROR,
 285                    G_IO_ERROR_INVALID_ARGUMENT,
 286                    _("Wrong number of tokens (%d)"),
 287                    num_tokens);
 288       goto out;
 289     }
 290
 291   typename = tokens[0];
 292   version_str = strchr (typename, '.');
 293   if (version_str)
 294     {
 295       *version_str = 0;
 296       version_str += 1;
 297     }
 298
 299
 300   type = g_type_from_name (tokens[0]);
 301   if (type == 0)
 302     {
 303       g_set_error (error,
 304                    G_IO_ERROR,
 305                    G_IO_ERROR_INVALID_ARGUMENT,
 306                    _("No type for class name %s"),
 307                    tokens[0]);
 308       goto out;
 309     }
 310
 311   if (!g_type_is_a (type, G_TYPE_ICON))
 312     {
 313       g_set_error (error,
 314                    G_IO_ERROR,
 315                    G_IO_ERROR_INVALID_ARGUMENT,
 316                    _("Type %s does not implement the GIcon interface"),
 317                    tokens[0]);
 318       goto out;
 319     }
 320
 321   klass = g_type_class_ref (type);
 322   if (klass == NULL)
 323     {
 324       g_set_error (error,
 325                    G_IO_ERROR,
 326                    G_IO_ERROR_INVALID_ARGUMENT,
 327                    _("Type %s is not classed"),
 328                    tokens[0]);
 329       goto out;
 330     }
 331
 332   version = 0;
 333   if (version_str)
 334     {
 335       version = strtol (version_str, &endp, 10);
 336       if (endp == NULL || *endp != '\0')
 337         {
 338           g_set_error (error,
 339                        G_IO_ERROR,
 340                        G_IO_ERROR_INVALID_ARGUMENT,
 341                        _("Malformed version number: %s"),
 342                        version_str);
 343           goto out;
 344         }
 345     }
 346
 347   icon_iface = g_type_interface_peek (klass, G_TYPE_ICON);
 348   g_assert (icon_iface != NULL);
 349
 350   if (icon_iface->from_tokens == NULL)
 351     {
 352       g_set_error (error,
 353                    G_IO_ERROR,
 354                    G_IO_ERROR_INVALID_ARGUMENT,
 355                    _("Type %s does not implement from_tokens() on the GIcon interface"),
 356                    tokens[0]);
 357       goto out;
 358     }
 359
 360   for (i = 1;  i < num_tokens; i++)
 361     {
 362       char *escaped;
 363
 364       escaped = tokens[i];
 365       tokens[i] = g_uri_unescape_string (escaped, NULL);
 366       g_free (escaped);
 367     }
 368
 369   icon = icon_iface->from_tokens (tokens + 1, num_tokens - 1, version, error);
 370
 371  out:
 372   if (klass != NULL)
 373     g_type_class_unref (klass);
 374   return icon;
 375 }
 376
 377 static void
 378 ensure_builtin_icon_types (void)
 379 {
 380   static volatile GType t;
 381   t = g_themed_icon_get_type ();
 382   t = g_file_icon_get_type ();
 383   t = g_emblemed_icon_get_type ();
 384   t = g_emblem_get_type ();
 385 }
 386
 387 /**
 388  * g_icon_new_for_string:
 389  * @str: A string obtained via g_icon_to_string().
 390  * @error: Return location for error.
 391  *
 392  * Generate a #GIcon instance from @str. This function can fail if
 393  * @str is not valid - see g_icon_to_string() for discussion.
 394  *
 395  * If your application or library provides one or more #GIcon
 396  * implementations you need to ensure that each #GType is registered
 397  * with the type system prior to calling g_icon_new_for_string().
 398  *
 399  * Returns: An object implementing the #GIcon interface or %NULL if
 400  * @error is set.
 401  *
 402  * Since: 2.20
 403  **/
 404 GIcon *
 405 g_icon_new_for_string (const gchar   *str,
 406                        GError       **error)
 407 {
 408   GIcon *icon;
 409
 410   g_return_val_if_fail (str != NULL, NULL);
 411
 412   ensure_builtin_icon_types ();
 413
 414   icon = NULL;
 415
 416   if (*str == '.')
 417     {
 418       if (g_str_has_prefix (str, G_ICON_SERIALIZATION_MAGIC0))
 419         {
 420           gchar **tokens;
 421
 422           /* handle tokenized encoding */
 423           tokens = g_strsplit (str + sizeof (G_ICON_SERIALIZATION_MAGIC0) - 1, " ", 0);
 424           icon = g_icon_new_from_tokens (tokens, error);
 425           g_strfreev (tokens);
 426         }
 427       else
 428         g_set_error_literal (error,
 429                              G_IO_ERROR,
 430                              G_IO_ERROR_INVALID_ARGUMENT,
 431                              _("Can't handle the supplied version the icon encoding"));
 432     }
 433   else
 434     {
 435       gchar *scheme;
 436
 437       /* handle special GFileIcon and GThemedIcon cases */
 438       scheme = g_uri_parse_scheme (str);
 439       if (scheme != NULL || str[0] == '/')
 440         {
 441           GFile *location;
 442           location = g_file_new_for_commandline_arg (str);
 443           icon = g_file_icon_new (location);
 444           g_object_unref (location);
 445         }
 446       else
 447         icon = g_themed_icon_new (str);
 448       g_free (scheme);
 449     }
 450
 451   return icon;
 452 }
 453
 454
 455 #define __G_ICON_C__
 456 #include "gioaliasdef.c"