[glib] GMenu: add g_menu_item_set_icon() convenience

[Ryan Lortie <ryanl src gnome org>]

commit c1c1b33f883d6afd2e27bb2506ab6490ed916052
Author: Ryan Lortie <desrt desrt ca>
Date:   Sat Apr 20 18:55:03 2013 -0400

    GMenu: add g_menu_item_set_icon() convenience
    
    This function takes a GIcon, serialises it and sets the resulting
    GVariant as the "icon" attribute on the menu item.  We will need to add
    a patch to Gtk to actually consume this icon.
    
    Also add G_MENU_ATTRIBUTE_ICON.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=688820

 docs/reference/gio/gio-sections.txt |  4 +++-
 gio/gmenu.c                         | 41 +++++++++++++++++++++++++++++++++++++
 gio/gmenu.h                         |  4 ++++
 gio/gmenumodel.h                    | 15 ++++++++++++++
 4 files changed, 63 insertions(+), 1 deletion(-)
---
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index bac8f82..4cf6d23 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -3800,6 +3800,7 @@ g_menu_item_new_from_model
 
 <SUBSECTION>
 g_menu_item_set_label
+g_menu_item_set_icon
 g_menu_item_set_action_and_target_value
 g_menu_item_set_action_and_target
 g_menu_item_set_detailed_action
@@ -3836,8 +3837,9 @@ g_menu_model_get_n_items
 
 <SUBSECTION>
 G_MENU_ATTRIBUTE_ACTION
-G_MENU_ATTRIBUTE_LABEL
 G_MENU_ATTRIBUTE_TARGET
+G_MENU_ATTRIBUTE_LABEL
+G_MENU_ATTRIBUTE_ICON
 G_MENU_LINK_SECTION
 G_MENU_LINK_SUBMENU
 
diff --git a/gio/gmenu.c b/gio/gmenu.c
index 940ba66..39c267a 100644
--- a/gio/gmenu.c
+++ b/gio/gmenu.c
@@ -26,6 +26,8 @@
 #include "gaction.h"
 #include <string.h>
 
+#include "gicon.h"
+
 /**
  * SECTION:gmenu
  * @title: GMenu
@@ -1348,3 +1350,42 @@ g_menu_item_new_from_model (GMenuModel *model,
 
   return menu_item;
 }
+
+/**
+ * g_menu_item_set_icon:
+ * @menu_item: a #GMenuItem
+ * @icon: a #GIcon, or %NULL
+ *
+ * Sets (or unsets) the icon on @menu_item.
+ *
+ * This call is the same as calling g_icon_serialize() and using the
+ * result as the value to g_menu_item_set_attribute_value() for
+ * %G_MENU_ATTRIBUTE_ICON.
+ *
+ * This API is only intended for use with "noun" menu items; things like
+ * bookmarks or applications in an "Open With" menu.  Don't use it on
+ * menu items corresponding to verbs (eg: stock icons for 'Save' or
+ * 'Quit').
+ *
+ * If @icon is %NULL then the icon is unset.
+ *
+ * Since: 2.38
+ **/
+void
+g_menu_item_set_icon (GMenuItem *menu_item,
+                      GIcon     *icon)
+{
+  GVariant *value;
+
+  g_return_if_fail (G_IS_MENU_ITEM (menu_item));
+  g_return_if_fail (G_IS_ICON (icon));
+
+  if (icon != NULL)
+    value = g_icon_serialize (icon);
+  else
+    value = NULL;
+
+  g_menu_item_set_attribute_value (menu_item, G_MENU_ATTRIBUTE_ICON, value);
+  if (value)
+    g_variant_unref (value);
+}
diff --git a/gio/gmenu.h b/gio/gmenu.h
index e68cf83..68a974f 100644
--- a/gio/gmenu.h
+++ b/gio/gmenu.h
@@ -175,6 +175,10 @@ GLIB_AVAILABLE_IN_2_32
 void        g_menu_item_set_detailed_action         (GMenuItem   *menu_item,
                                                      const gchar *detailed_action);
 
+GLIB_AVAILABLE_IN_2_38
+void        g_menu_item_set_icon                    (GMenuItem   *menu_item,
+                                                     GIcon       *icon);
+
 G_END_DECLS
 
 #endif /* __G_MENU_H__ */
diff --git a/gio/gmenumodel.h b/gio/gmenumodel.h
index 01ab337..46c4bad 100644
--- a/gio/gmenumodel.h
+++ b/gio/gmenumodel.h
@@ -74,6 +74,21 @@ G_BEGIN_DECLS
 #define G_MENU_ATTRIBUTE_LABEL "label"
 
 /**
+ * G_MENU_ATTRIBUTE_ICON:
+ *
+ * The menu item attribute which holds the icon of the item.
+ *
+ * The icon is stored in the format returned by g_icon_serialize().
+ *
+ * This attribute is intended only to represent 'noun' icons such as
+ * favicons for a webpage, or application icons.  It should not be used
+ * for 'verbs' (ie: stock icons).
+ *
+ * Since: 2.38
+ **/
+#define G_MENU_ATTRIBUTE_ICON "icon"
+
+/**
  * G_MENU_LINK_SUBMENU:
  *
  * The name of the link that associates a menu item with a submenu.