[gimp] libgimpbase: add gimp_{enum,flags}_value_get_abbrev()

[N/A <ell src gnome org>]

commit 7df427583f0460411c6aac4bdcb5693994e10ba9
Author: Ell <ell_se yahoo com>
Date:   Wed Nov 29 15:33:32 2017 -0500

    libgimpbase: add gimp_{enum,flags}_value_get_abbrev()
    
    Add support for specifying an abbreviated description for enum/
    flags values, which can be used in contexts where the full
    description is too long.
    
    Since the exact layout and size of Gimp{Enum,Flags}Desc is part of
    the ABI, we can't simply add a field to these structs to hold the
    abbreviated description.  Instead, we use the fact that entries
    with a repeated value in the value descriptions array are ignored,
    and that the array is NULL terminated (in particular, that all non-
    NULL entries are followed by at least one additional entry), and
    specify the abbreviation in the "value_desc" field of the entry
    that immediately follows the initial entry for a given value,
    setting the "value" field of both entries to the same value.
    
    Right now this behavior is undocumented, so there is no proper way
    to specify abbreviated descriptions in the API, and is only meant
    to be used in generated enum files.

 libgimpbase/gimputils.c |   62 +++++++++++++++++++++++++++++++++++++++++++++++
 libgimpbase/gimputils.h |    4 +++
 2 files changed, 66 insertions(+), 0 deletions(-)
---
diff --git a/libgimpbase/gimputils.c b/libgimpbase/gimputils.c
index 886991e..8c3f4b2 100644
--- a/libgimpbase/gimputils.c
+++ b/libgimpbase/gimputils.c
@@ -835,6 +835,37 @@ gimp_enum_value_get_help (GEnumClass *enum_class,
 }
 
 /**
+ * gimp_enum_value_get_abbrev:
+ * @enum_class: a #GEnumClass
+ * @enum_value: a #GEnumValue from @enum_class
+ *
+ * Retrieves the translated abbreviation for a given @enum_value.
+ *
+ * Return value: the translated abbreviation of the enum value
+ *
+ * Since: 2.10
+ **/
+const gchar *
+gimp_enum_value_get_abbrev (GEnumClass *enum_class,
+                            GEnumValue *enum_value)
+{
+  GType         type = G_TYPE_FROM_CLASS (enum_class);
+  GimpEnumDesc *enum_desc;
+
+  enum_desc = gimp_enum_get_desc (enum_class, enum_value->value);
+
+  if (enum_desc                              &&
+      enum_desc[1].value == enum_desc->value &&
+      enum_desc[1].value_desc)
+    {
+      return dgettext (gimp_type_get_translation_domain (type),
+                       enum_desc[1].value_desc);
+    }
+
+  return NULL;
+}
+
+/**
  * gimp_flags_get_first_desc:
  * @flags_class: a #GFlagsClass
  * @value:       a value from @flags_class
@@ -991,3 +1022,34 @@ gimp_flags_value_get_help (GFlagsClass *flags_class,
 
   return NULL;
 }
+
+/**
+ * gimp_flags_value_get_abbrev:
+ * @flags_class: a #GFlagsClass
+ * @flags_value: a #GFlagsValue from @flags_class
+ *
+ * Retrieves the translated abbreviation for a given @flags_value.
+ *
+ * Return value: the translated abbreviation of the flags value
+ *
+ * Since: 2.10
+ **/
+const gchar *
+gimp_flags_value_get_abbrev (GFlagsClass *flags_class,
+                             GFlagsValue *flags_value)
+{
+  GType          type = G_TYPE_FROM_CLASS (flags_class);
+  GimpFlagsDesc *flags_desc;
+
+  flags_desc = gimp_flags_get_first_desc (flags_class, flags_value->value);
+
+  if (flags_desc                               &&
+      flags_desc[1].value == flags_desc->value &&
+      flags_desc[1].value_desc)
+    {
+      return dgettext (gimp_type_get_translation_domain (type),
+                       flags_desc[1].value_desc);
+    }
+
+  return NULL;
+}
diff --git a/libgimpbase/gimputils.h b/libgimpbase/gimputils.h
index c7cea29..c159766 100644
--- a/libgimpbase/gimputils.h
+++ b/libgimpbase/gimputils.h
@@ -57,6 +57,8 @@ const gchar   * gimp_enum_value_get_desc       (GEnumClass   *enum_class,
                                                 GEnumValue   *enum_value);
 const gchar   * gimp_enum_value_get_help       (GEnumClass   *enum_class,
                                                 GEnumValue   *enum_value);
+const gchar   * gimp_enum_value_get_abbrev     (GEnumClass   *enum_class,
+                                                GEnumValue   *enum_value);
 
 GimpFlagsDesc * gimp_flags_get_first_desc      (GFlagsClass  *flags_class,
                                                 guint         value);
@@ -70,6 +72,8 @@ const gchar   * gimp_flags_value_get_desc      (GFlagsClass  *flags_class,
                                                 GFlagsValue  *flags_value);
 const gchar   * gimp_flags_value_get_help      (GFlagsClass  *flags_class,
                                                 GFlagsValue  *flags_value);
+const gchar   * gimp_flags_value_get_abbrev    (GFlagsClass  *flags_class,
+                                                GFlagsValue  *flags_value);
 
 
 G_END_DECLS