[gimp] libgimp: improve GimpProcedure icon functions.

[Jehan <jehanp src gnome org>]

commit f49f1b587a78a13145660e8bd1a0f8c1420ccc1e
Author: Jehan <jehan girinstud io>
Date:   Thu Aug 8 17:35:20 2019 +0200

    libgimp: improve GimpProcedure icon functions.
    
    gimp_procedure_set_icon() and gimp_procedure_get_icon() are not very
    nice functions for bindings. They are still usable, but in most
    bindings, the data parameter/returned value would end up like a uint
    list which you'd want to convert to a string in the icon name or file
    path case. It's still possible but very cumbersome.
    
    Instead, I skip both functions for bindings and create specific
    gimp_procedure_set_icon_*() and gimp_procedure_get_icon_*() functions,
    which are much more binding-friendly.

 libgimp/gimpprocedure.c | 177 ++++++++++++++++++++++++++++++++++++++++++++++++
 libgimp/gimpprocedure.h |  12 ++++
 2 files changed, 189 insertions(+)
---
diff --git a/libgimp/gimpprocedure.c b/libgimp/gimpprocedure.c
index 771e599430..44abb69d3c 100644
--- a/libgimp/gimpprocedure.c
+++ b/libgimp/gimpprocedure.c
@@ -704,6 +704,19 @@ gimp_procedure_get_date (GimpProcedure *procedure)
   return procedure->priv->date;
 }
 
+/**
+ * gimp_procedure_set_icon: (skip)
+ * @procedure: a #GimpProcedure.
+ * @icon_type: the #GimpIconType of @icon_data.
+ * @icon_data: icon representation.
+ *
+ * Sets the icon for @procedure. @icon_data contents type depends on
+ * @icon_type.
+ *
+ * This procedure is skipped from bindings, where you should use
+ * specific gimp_procedure_set_icon_*() instead, such as
+ * gimp_procedure_set_icon_name().
+ */
 void
 gimp_procedure_set_icon (GimpProcedure *procedure,
                          GimpIconType   icon_type,
@@ -744,6 +757,83 @@ gimp_procedure_set_icon (GimpProcedure *procedure,
     }
 }
 
+/**
+ * gimp_procedure_set_icon_name:
+ * @procedure: a #GimpProcedure.
+ * @icon_name: an icon name.
+ *
+ * Sets the icon for @procedure by its name.
+ */
+void
+gimp_procedure_set_icon_name (GimpProcedure *procedure,
+                              const gchar   *icon_name)
+{
+  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));
+  g_return_if_fail (icon_name != NULL);
+
+  gimp_procedure_set_icon (procedure,
+                           GIMP_ICON_TYPE_ICON_NAME,
+                           (const guint8*) icon_name);
+}
+
+/**
+ * gimp_procedure_set_icon_file:
+ * @procedure: a #GimpProcedure.
+ * @icon_path: a file path for an image.
+ *
+ * Sets the icon for @procedure by specifying an image file path in a
+ * format supported by GdkPixbuf. @icon_path must be in in the GLib file
+ * name encoding.
+ */
+void
+gimp_procedure_set_icon_file (GimpProcedure *procedure,
+                              const gchar   *icon_path)
+{
+  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));
+  g_return_if_fail (icon_path != NULL);
+
+  gimp_procedure_set_icon (procedure,
+                           GIMP_ICON_TYPE_IMAGE_FILE,
+                           (const guint8*) icon_path);
+}
+
+/**
+ * gimp_procedure_set_icon_inline:
+ * @procedure: a #GimpProcedure.
+ * @icon_data: inline pixel data for the icon image.
+ *
+ * Sets the icon for @procedure by specifying inline pixel data. The
+ * data must be serialized in the format supported by
+ * gdk_pixbuf_new_from_inline(), e.g. as generated by the tool
+ * [gdk-pixbuf-csource](https://developer.gnome.org/gdk-pixbuf/stable/gdk-pixbuf-csource.html).
+ */
+void
+gimp_procedure_set_icon_inline (GimpProcedure *procedure,
+                                const guint8  *icon_data)
+{
+  g_return_if_fail (GIMP_IS_PROCEDURE (procedure));
+  g_return_if_fail (icon_data != NULL);
+
+  gimp_procedure_set_icon (procedure,
+                           GIMP_ICON_TYPE_INLINE_PIXBUF,
+                           icon_data);
+}
+
+/**
+ * gimp_procedure_get_icon: (skip)
+ * @procedure:        a #GimpProcedure.
+ * @icon_data:        icon representation.
+ * @icon_data_length: length of @icon_data.
+ *
+ * Gets the icon for @procedure. @icon_data contents type depends on
+ * the returned type.
+ *
+ * This procedure is skipped from bindings, where you should use
+ * specific gimp_procedure_get_icon_type() instead, followed by the
+ * relevant specific function, such as gimp_procedure_get_icon_name().
+ *
+ * Returns: the #GimpIconType of @icon_data.
+ */
 GimpIconType
 gimp_procedure_get_icon (GimpProcedure  *procedure,
                          const guint8  **icon_data,
@@ -759,6 +849,93 @@ gimp_procedure_get_icon (GimpProcedure  *procedure,
   return procedure->priv->icon_type;
 }
 
+/**
+ * gimp_procedure_get_icon_type:
+ * @procedure: a #GimpProcedure.
+ *
+ * Gets the type of data set as @procedure's icon.
+ * Depending on the result, you can call the relevant specific function,
+ * such as gimp_procedure_get_icon_name().
+ *
+ * Returns: the #GimpIconType of @icon_data.
+ */
+GimpIconType
+gimp_procedure_get_icon_type (GimpProcedure *procedure)
+{
+  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), -1);
+
+  return procedure->priv->icon_type;
+}
+
+/**
+ * gimp_procedure_get_icon_name:
+ * @procedure: a #GimpProcedure.
+ *
+ * Gets the name of the icon if one was set for @procedure.
+ *
+ * Returns: (nullable): the icon name or %NULL if no icon name was set.
+ */
+const gchar *
+gimp_procedure_get_icon_name (GimpProcedure *procedure)
+{
+  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
+
+  if (procedure->priv->icon_type == GIMP_ICON_TYPE_ICON_NAME)
+    return (const gchar *) procedure->priv->icon_data;
+  else
+    return NULL;
+}
+
+/**
+ * gimp_procedure_get_icon_file:
+ * @procedure: a #GimpProcedure.
+ *
+ * Gets the file path of the icon if one was set for @procedure.
+ *
+ * Returns: (nullable): the icon file path or %NULL if no file was set.
+ */
+const gchar *
+gimp_procedure_get_icon_file (GimpProcedure *procedure)
+{
+  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
+
+  if (procedure->priv->icon_type == GIMP_ICON_TYPE_IMAGE_FILE)
+  return (const gchar *) procedure->priv->icon_data;
+  else
+    return NULL;
+}
+
+/**
+ * gimp_procedure_get_icon_inline:
+ * @procedure: a #GimpProcedure.
+ * @icon_data_length: length of @icon_data.
+ *
+ * Gets the pixel data of the icon if an icon was set this way for
+ * @procedure. See gimp_procedure_set_icon_file() for information on the
+ * format of returned data.
+ *
+ * Returns: (nullable) (array length=icon_data_length):
+            the icon byte data or %NULL if no icon name was set.
+ */
+const guint8 *
+gimp_procedure_get_icon_inline (GimpProcedure *procedure,
+                                gint           *icon_data_length)
+{
+  g_return_val_if_fail (GIMP_IS_PROCEDURE (procedure), NULL);
+  g_return_val_if_fail (icon_data_length != NULL, NULL);
+
+  if (procedure->priv->icon_type == GIMP_ICON_TYPE_INLINE_PIXBUF)
+    {
+      *icon_data_length = procedure->priv->icon_data_length;
+
+      return (const guint8 *) procedure->priv->icon_data;
+    }
+  else
+    {
+      return NULL;
+    }
+}
+
 /**
  * gimp_procedure_add_argument:
  * @procedure: the #GimpProcedure.
diff --git a/libgimp/gimpprocedure.h b/libgimp/gimpprocedure.h
index 5f63ecdd54..b991e0012a 100644
--- a/libgimp/gimpprocedure.h
+++ b/libgimp/gimpprocedure.h
@@ -130,9 +130,21 @@ const gchar    * gimp_procedure_get_date           (GimpProcedure        *proced
 void             gimp_procedure_set_icon           (GimpProcedure        *procedure,
                                                     GimpIconType          icon_type,
                                                     const guint8         *icon_data);
+void             gimp_procedure_set_icon_name      (GimpProcedure        *procedure,
+                                                    const gchar          *icon_name);
+void             gimp_procedure_set_icon_file      (GimpProcedure        *procedure,
+                                                    const gchar          *icon_path);
+void             gimp_procedure_set_icon_inline    (GimpProcedure        *procedure,
+                                                    const guint8         *icon_data);
+
 GimpIconType     gimp_procedure_get_icon           (GimpProcedure        *procedure,
                                                     const guint8        **icon_data,
                                                     gint                 *icon_data_length);
+GimpIconType     gimp_procedure_get_icon_type      (GimpProcedure        *procedure);
+const gchar    * gimp_procedure_get_icon_name      (GimpProcedure        *procedure);
+const gchar    * gimp_procedure_get_icon_file      (GimpProcedure        *procedure);
+const guint8   * gimp_procedure_get_icon_inline    (GimpProcedure        *procedure,
+                                                    gint                 *icon_data_length);
 
 void             gimp_procedure_add_argument       (GimpProcedure        *procedure,
                                                     GParamSpec           *pspec);