1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2006-2007 Red Hat, Inc.
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.
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.
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.
20 * Author: Alexander Larsson <alexl@redhat.com>
28 #include "gthemedicon.h"
29 #include "gfileicon.h"
30 #include "gemblemedicon.h"
37 /* There versioning of this is implicit, version 1 would be ".1 " */
38 #define G_ICON_SERIALIZATION_MAGIC0 ". "
42 * @short_description: Interface for icons
45 * #GIcon is a very minimal interface for icons. It provides functions
46 * for checking the equality of two icons, hashing of icons and
47 * serializing an icon to and from strings.
49 * #GIcon does not provide the actual pixmap for the icon as this is out
50 * of GIO's scope, however implementations of #GIcon may contain the name
51 * of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon).
53 * To obtain a hash of a #GIcon, see g_icon_hash().
55 * To check if two #GIcons are equal, see g_icon_equal().
57 * For serializing a #GIcon, use g_icon_to_string() and
58 * g_icon_new_for_string().
60 * If your application or library provides one or more #GIcon
61 * implementations you need to ensure that each #GType is registered
62 * with the type system prior to calling g_icon_new_for_string().
65 typedef GIconIface GIconInterface
;
66 G_DEFINE_INTERFACE(GIcon
, g_icon
, G_TYPE_OBJECT
)
69 g_icon_default_init (GIconInterface
*iface
)
75 * @icon: #gconstpointer to an icon object.
77 * Gets a hash for an icon.
80 * Returns: a #guint containing a hash for the @icon, suitable for
81 * use in a #GHashTable or similar data structure.
84 g_icon_hash (gconstpointer icon
)
88 g_return_val_if_fail (G_IS_ICON (icon
), 0);
90 iface
= G_ICON_GET_IFACE (icon
);
92 return (* iface
->hash
) ((GIcon
*)icon
);
97 * @icon1: (allow-none): pointer to the first #GIcon.
98 * @icon2: (allow-none): pointer to the second #GIcon.
100 * Checks if two icons are equal.
102 * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise.
105 g_icon_equal (GIcon
*icon1
,
110 if (icon1
== NULL
&& icon2
== NULL
)
113 if (icon1
== NULL
|| icon2
== NULL
)
116 if (G_TYPE_FROM_INSTANCE (icon1
) != G_TYPE_FROM_INSTANCE (icon2
))
119 iface
= G_ICON_GET_IFACE (icon1
);
121 return (* iface
->equal
) (icon1
, icon2
);
125 g_icon_to_string_tokenized (GIcon
*icon
, GString
*s
)
129 GIconIface
*icon_iface
;
132 g_return_val_if_fail (icon
!= NULL
, FALSE
);
133 g_return_val_if_fail (G_IS_ICON (icon
), FALSE
);
135 icon_iface
= G_ICON_GET_IFACE (icon
);
136 if (icon_iface
->to_tokens
== NULL
)
139 tokens
= g_ptr_array_new ();
140 if (!icon_iface
->to_tokens (icon
, tokens
, &version
))
142 g_ptr_array_free (tokens
, TRUE
);
146 /* format: TypeName[.Version] <token_0> .. <token_N-1>
147 version 0 is implicit and can be omitted
148 all the tokens are url escaped to ensure they have no spaces in them */
150 g_string_append (s
, g_type_name_from_instance ((GTypeInstance
*)icon
));
152 g_string_append_printf (s
, ".%d", version
);
154 for (i
= 0; i
< tokens
->len
; i
++)
158 token
= g_ptr_array_index (tokens
, i
);
160 g_string_append_c (s
, ' ');
161 /* We really only need to escape spaces here, so allow lots of otherwise reserved chars */
162 g_string_append_uri_escaped (s
, token
,
163 G_URI_RESERVED_CHARS_ALLOWED_IN_PATH
, TRUE
);
168 g_ptr_array_free (tokens
, TRUE
);
177 * Generates a textual representation of @icon that can be used for
178 * serialization such as when passing @icon to a different process or
179 * saving it to persistent storage. Use g_icon_new_for_string() to
180 * get @icon back from the returned string.
182 * The encoding of the returned string is proprietary to #GIcon except
183 * in the following two cases
187 * If @icon is a #GFileIcon, the returned string is a native path
188 * (such as <literal>/path/to/my icon.png</literal>) without escaping
189 * if the #GFile for @icon is a native file. If the file is not
190 * native, the returned string is the result of g_file_get_uri()
191 * (such as <literal>sftp://path/to/my%20icon.png</literal>).
194 * If @icon is a #GThemedIcon with exactly one name, the encoding is
195 * simply the name (such as <literal>network-server</literal>).
200 * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't
201 * be serialized. Use g_free() to free.
206 g_icon_to_string (GIcon
*icon
)
210 g_return_val_if_fail (icon
!= NULL
, NULL
);
211 g_return_val_if_fail (G_IS_ICON (icon
), NULL
);
215 if (G_IS_FILE_ICON (icon
))
219 file
= g_file_icon_get_file (G_FILE_ICON (icon
));
220 if (g_file_is_native (file
))
222 ret
= g_file_get_path (file
);
223 if (!g_utf8_validate (ret
, -1, NULL
))
230 ret
= g_file_get_uri (file
);
232 else if (G_IS_THEMED_ICON (icon
))
234 const char * const *names
;
236 names
= g_themed_icon_get_names (G_THEMED_ICON (icon
));
239 names
[0][0] != '.' && /* Allowing icons starting with dot would break G_ICON_SERIALIZATION_MAGIC0 */
240 g_utf8_validate (names
[0], -1, NULL
) && /* Only return utf8 strings */
242 ret
= g_strdup (names
[0]);
249 s
= g_string_new (G_ICON_SERIALIZATION_MAGIC0
);
251 if (g_icon_to_string_tokenized (icon
, s
))
252 ret
= g_string_free (s
, FALSE
);
254 g_string_free (s
, TRUE
);
261 g_icon_new_from_tokens (char **tokens
,
265 char *typename
, *version_str
;
268 GIconIface
*icon_iface
;
277 num_tokens
= g_strv_length (tokens
);
283 G_IO_ERROR_INVALID_ARGUMENT
,
284 _("Wrong number of tokens (%d)"),
289 typename
= tokens
[0];
290 version_str
= strchr (typename
, '.');
298 type
= g_type_from_name (tokens
[0]);
303 G_IO_ERROR_INVALID_ARGUMENT
,
304 _("No type for class name %s"),
309 if (!g_type_is_a (type
, G_TYPE_ICON
))
313 G_IO_ERROR_INVALID_ARGUMENT
,
314 _("Type %s does not implement the GIcon interface"),
319 klass
= g_type_class_ref (type
);
324 G_IO_ERROR_INVALID_ARGUMENT
,
325 _("Type %s is not classed"),
333 version
= strtol (version_str
, &endp
, 10);
334 if (endp
== NULL
|| *endp
!= '\0')
338 G_IO_ERROR_INVALID_ARGUMENT
,
339 _("Malformed version number: %s"),
345 icon_iface
= g_type_interface_peek (klass
, G_TYPE_ICON
);
346 g_assert (icon_iface
!= NULL
);
348 if (icon_iface
->from_tokens
== NULL
)
352 G_IO_ERROR_INVALID_ARGUMENT
,
353 _("Type %s does not implement from_tokens() on the GIcon interface"),
358 for (i
= 1; i
< num_tokens
; i
++)
363 tokens
[i
] = g_uri_unescape_string (escaped
, NULL
);
367 icon
= icon_iface
->from_tokens (tokens
+ 1, num_tokens
- 1, version
, error
);
371 g_type_class_unref (klass
);
376 ensure_builtin_icon_types (void)
378 g_type_ensure (G_TYPE_THEMED_ICON
);
379 g_type_ensure (G_TYPE_FILE_ICON
);
380 g_type_ensure (G_TYPE_EMBLEMED_ICON
);
381 g_type_ensure (G_TYPE_EMBLEM
);
385 * g_icon_new_for_string:
386 * @str: A string obtained via g_icon_to_string().
387 * @error: Return location for error.
389 * Generate a #GIcon instance from @str. This function can fail if
390 * @str is not valid - see g_icon_to_string() for discussion.
392 * If your application or library provides one or more #GIcon
393 * implementations you need to ensure that each #GType is registered
394 * with the type system prior to calling g_icon_new_for_string().
396 * Returns: (transfer full): An object implementing the #GIcon
397 * interface or %NULL if @error is set.
402 g_icon_new_for_string (const gchar
*str
,
407 g_return_val_if_fail (str
!= NULL
, NULL
);
409 ensure_builtin_icon_types ();
415 if (g_str_has_prefix (str
, G_ICON_SERIALIZATION_MAGIC0
))
419 /* handle tokenized encoding */
420 tokens
= g_strsplit (str
+ sizeof (G_ICON_SERIALIZATION_MAGIC0
) - 1, " ", 0);
421 icon
= g_icon_new_from_tokens (tokens
, error
);
425 g_set_error_literal (error
,
427 G_IO_ERROR_INVALID_ARGUMENT
,
428 _("Can't handle the supplied version of the icon encoding"));
434 /* handle special GFileIcon and GThemedIcon cases */
435 scheme
= g_uri_parse_scheme (str
);
436 if (scheme
!= NULL
|| str
[0] == '/' || str
[0] == G_DIR_SEPARATOR
)
439 location
= g_file_new_for_commandline_arg (str
);
440 icon
= g_file_icon_new (location
);
441 g_object_unref (location
);
444 icon
= g_themed_icon_new (str
);