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