Gio::Icon: Add serialize(), deserialize() and documentation of create()

1 files changed, 25 insertions, 5 deletions

diff --git a/gio/src/icon.hg b/gio/src/icon.hg
index 97ef3479..36888f7e 100644
--- a/gio/src/icon.hg
+++ b/gio/src/icon.hg
@@ -1,5 +1,3 @@
-// -*- Mode: C++; indent-tabs-mode: nil; c-basic-offset: 2 -*-
-
 /* Copyright (C) 2007 The giomm Development Team
  *
  * This library is free software; you can redistribute it and/or
@@ -18,6 +16,7 @@
  */
 
 #include <glibmm/interface.h>
+#include <glibmm/variant.h>
 
 _DEFS(giomm,gio)
 _PINCLUDE(glibmm/private/interface_p.h)
@@ -29,14 +28,20 @@ typedef struct _GIconIface GIconIface;
 namespace Gio
 {
 
-/** This is a very minimal interface for icons. It provides functions for checking the equality of two icons and hashing of icons.
- * Glib::Icon does not provide the actual pixmap for the icon as this is out of GIO's scope. However implementations of Icon may contain the name of an
+/** This is a very minimal interface for icons.
+ * It provides functions for checking the equality of two icons,
+ * hashing of icons and serializing an icon to and from strings and Variants.
+ *
+ * Gio::Icon does not provide the actual pixmap for the icon as this is out
+ * of GIO's scope. However implementations of Icon may contain the name of an
  * icon (see ThemedIcon), or the path to an icon (see LoadableIcon).
  *
  * To obtain a hash of an Icon instance, see hash().
  *
  * To check if two Icon instances are equal, see equal().
  *
+ * For serializing an Icon, use serialize() and deserialize().
+ *
  * @newin{2,16}
  */
 class Icon : public Glib::Interface
@@ -46,6 +51,20 @@ class Icon : public Glib::Interface
 public:
   // We can't just use a _WRAP_CREATE macro here since this is an abstract
   // interface class, so implement it by hand
+  /** Generate an Icon instance from @a str.
+   *
+   * This function can fail if @a str is not valid. See to_string() for discussion.
+   *
+   * If your application or library provides one or more Icon
+   * implementations, you need to ensure that each GType is registered
+   * with the type system prior to calling create().
+   *
+   * @newin{2,20}
+   *
+   * @param str A string obtained via to_string().
+   * @return An object implementing the Icon interface, or throws an exception.
+   * @throw Gio::Error
+   */
   static Glib::RefPtr<Icon> create(const std::string& str);
   _IGNORE(g_icon_new_for_string)
   _WRAP_METHOD(guint hash() const, g_icon_hash)
@@ -56,6 +75,8 @@ public:
   // be available to derived classes?
   bool equal(const Glib::RefPtr<Icon>& other) const;
 
+  _WRAP_METHOD(Glib::VariantBase serialize() const, g_icon_serialize, newin "2,48")
+  _WRAP_METHOD(static Glib::RefPtr<Icon> deserialize(const Glib::VariantBase& value), g_icon_deserialize, newin "2,48")
 
   //_WRAP_VFUNC(guint hash() const, "hash")
 
@@ -65,4 +86,3 @@ public:
 };
 
 } // namespace Gio
-