1 /* GIO - GLib Input, Output and Streaming Library
2 *
3 * Copyright (C) 2006-2007 Red Hat, Inc.
4 *
5 * SPDX-License-Identifier: LGPL-2.1-or-later
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General
18 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
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 * GIcon:
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 [class@Gio.ThemedIcon]), or the path to an icon
53 * (see [iface@Gio.LoadableIcon]).
54 *
55 * To obtain a hash of a `GIcon`, see [method@Gio.Icon.hash].
56 *
57 * To check if two `GIcon`s are equal, see [method@Gio.Icon.equal].
58 *
59 * For serializing a `GIcon`, use [method@Gio.Icon.serialize] and
60 * [func@Gio.Icon.deserialize].
61 *
62 * If you want to consume `GIcon` (for example, in a toolkit) you must
63 * be prepared to handle at least the three following cases:
64 * [iface@Gio.LoadableIcon], [class@Gio.ThemedIcon] and [class@Gio.EmblemedIcon].
65 * It may also make sense to have fast-paths for other cases (like handling
66 * [class@GdkPixbuf.Pixbuf] directly, for example) but all compliant `GIcon`
67 * implementations outside of GIO must implement [iface@Gio.LoadableIcon].
68 *
69 * If your application or library provides one or more `GIcon`
70 * implementations you need to ensure that your new implementation also
71 * implements [iface@Gio.LoadableIcon]. Additionally, you must provide an
72 * implementation of [method@Gio.Icon.serialize] that gives a result that is
73 * understood by [func@Gio.Icon.deserialize], yielding one of the built-in
74 * icon types.
75 **/
76
77 typedef GIconIface GIconInterface;
78 G_DEFINE_INTERFACE(GIcon, g_icon, G_TYPE_OBJECT)
79
80 static void
81 g_icon_default_init (GIconInterface *iface)
82 {
83 }
84
85 /**
86 * g_icon_hash: (virtual hash)
87 * @icon: (not nullable) (type Gio.Icon): #gconstpointer to an icon object.
88 *
89 * Gets a hash for an icon.
90 *
91 * Returns: a #guint containing a hash for the @icon, suitable for
92 * use in a #GHashTable or similar data structure.
93 **/
94 guint
95 g_icon_hash (gconstpointer icon)
96 {
97 GIconIface *iface;
98
99 g_return_val_if_fail (G_IS_ICON (icon), 0);
100
101 iface = G_ICON_GET_IFACE (icon);
102
103 return (* iface->hash) ((GIcon *)icon);
104 }
105
106 /**
107 * g_icon_equal: (virtual equal)
108 * @icon1: (nullable): pointer to the first #GIcon.
109 * @icon2: (nullable): pointer to the second #GIcon.
110 *
111 * Checks if two icons are equal.
112 *
113 * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
114 **/
115 gboolean
116 g_icon_equal (GIcon *icon1,
117 GIcon *icon2)
118 {
119 GIconIface *iface;
120
121 if (icon1 == NULL && icon2 == NULL)
122 return TRUE;
123
124 if (icon1 == NULL || icon2 == NULL)
125 return FALSE;
126
127 if (G_TYPE_FROM_INSTANCE (icon1) != G_TYPE_FROM_INSTANCE (icon2))
128 return FALSE;
129
130 iface = G_ICON_GET_IFACE (icon1);
131
132 return (* iface->equal) (icon1, icon2);
133 }
134
135 static gboolean
136 g_icon_to_string_tokenized (GIcon *icon, GString *s)
137 {
138 GPtrArray *tokens;
139 gint version;
140 GIconIface *icon_iface;
141 guint i;
142
143 g_return_val_if_fail (icon != NULL, FALSE);
144 g_return_val_if_fail (G_IS_ICON (icon), FALSE);
145
146 icon_iface = G_ICON_GET_IFACE (icon);
147 if (icon_iface->to_tokens == NULL)
148 return FALSE;
149
150 tokens = g_ptr_array_new ();
151 if (!icon_iface->to_tokens (icon, tokens, &version))
152 {
153 g_ptr_array_free (tokens, TRUE);
154 return FALSE;
155 }
156
157 /* format: TypeName[.Version] <token_0> .. <token_N-1>
158 version 0 is implicit and can be omitted
159 all the tokens are url escaped to ensure they have no spaces in them */
160
161 g_string_append (s, g_type_name_from_instance ((GTypeInstance *)icon));
162 if (version != 0)
163 g_string_append_printf (s, ".%d", version);
164
165 for (i = 0; i < tokens->len; i++)
166 {
167 char *token;
168
169 token = g_ptr_array_index (tokens, i);
170
171 g_string_append_c (s, ' ');
172 /* We really only need to escape spaces here, so allow lots of otherwise reserved chars */
173 g_string_append_uri_escaped (s, token,
174 G_URI_RESERVED_CHARS_ALLOWED_IN_PATH, TRUE);
175
176 g_free (token);
177 }
178
179 g_ptr_array_free (tokens, TRUE);
180
181 return TRUE;
182 }
183
184 /**
185 * g_icon_to_string:
186 * @icon: a #GIcon.
187 *
188 * Generates a textual representation of @icon that can be used for
189 * serialization such as when passing @icon to a different process or
190 * saving it to persistent storage. Use g_icon_new_for_string() to
191 * get @icon back from the returned string.
192 *
193 * The encoding of the returned string is proprietary to #GIcon except
194 * in the following two cases
195 *
196 * - If @icon is a #GFileIcon, the returned string is a native path
197 * (such as `/path/to/my icon.png`) without escaping
198 * if the #GFile for @icon is a native file. If the file is not
199 * native, the returned string is the result of g_file_get_uri()
200 * (such as `sftp://path/to/my%20icon.png`).
201 *
202 * - If @icon is a #GThemedIcon with exactly one name and no fallbacks,
203 * the encoding is simply the name (such as `network-server`).
204 *
205 * Returns: (nullable): An allocated NUL-terminated UTF8 string or
206 * %NULL if @icon can't be serialized. Use g_free() to free.
207 *
208 * Since: 2.20
209 */
210 gchar *
211 g_icon_to_string (GIcon *icon)
212 {
213 gchar *ret;
214
215 g_return_val_if_fail (icon != NULL, NULL);
216 g_return_val_if_fail (G_IS_ICON (icon), NULL);
217
218 ret = NULL;
219
220 if (G_IS_FILE_ICON (icon))
221 {
222 GFile *file;
223
224 file = g_file_icon_get_file (G_FILE_ICON (icon));
225 if (g_file_is_native (file))
226 {
227 ret = g_file_get_path (file);
228 if (!g_utf8_validate (ret, -1, NULL))
229 {
230 g_free (ret);
231 ret = NULL;
232 }
233 }
234 else
235 ret = g_file_get_uri (file);
236 }
237 else if (G_IS_THEMED_ICON (icon))
238 {
239 char **names = NULL;
240 gboolean use_default_fallbacks = FALSE;
241
242 g_object_get (G_OBJECT (icon),
243 "names", &names,
244 "use-default-fallbacks", &use_default_fallbacks,
245 NULL);
246 /* Themed icon initialized with a single name and no fallbacks. */
247 if (names != NULL &&
248 names[0] != NULL &&
249 names[0][0] != '.' && /* Allowing icons starting with dot would break G_ICON_SERIALIZATION_MAGIC0 */
250 g_utf8_validate (names[0], -1, NULL) && /* Only return utf8 strings */
251 names[1] == NULL &&
252 ! use_default_fallbacks)
253 ret = g_strdup (names[0]);
254
255 g_strfreev (names);
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: (transfer none): a #GVariant created with g_icon_serialize()
561 *
562 * Deserializes a #GIcon previously serialized using g_icon_serialize().
563 *
564 * Returns: (nullable) (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: (virtual 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: (nullable) (transfer full): a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating.
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 }