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 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
g_icon_get_type(void)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
g_icon_class_init(gpointer g_class,gpointer class_data)102 g_icon_class_init (gpointer g_class,
103 gpointer class_data)
104 {
105 }
106
107 static void
g_icon_base_init(gpointer g_class)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
g_icon_hash(gconstpointer icon)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
g_icon_equal(GIcon * icon1,GIcon * icon2)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
g_icon_to_string_tokenized(GIcon * icon,GString * s)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 *
g_icon_to_string(GIcon * icon)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 *
g_icon_new_from_tokens(char ** tokens,GError ** error)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
ensure_builtin_icon_types(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 *
g_icon_new_for_string(const gchar * str,GError ** error)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