[gimp] app, libgimp, libgimpbase, libgimpwidgets: better checkboard colors API.

[Jehan <jehanp src gnome org>]

commit 87f7a92786a5edcb17dfedec949124f7c0a68e30
Author: Jehan <jehan girinstud io>
Date:   Fri May 13 19:00:07 2022 +0200

    app, libgimp, libgimpbase, libgimpwidgets: better checkboard colors API.
    
    - Some coding style fixes (alignment, etc.).
    - Adding missing "Since: 3.0" annotations. We are still wondering
      whether this should go in 2.10, in which case, it would become
      "Since: 2.10.32" annotations. See discussion in !274.
    - Changing gimp_checks_get_colors() signature: merge the 4 color
      arguments into 2 (inout) arguments which seems a bit nicer in C,
      whereas binding handles such arguments correctly. The other
      alternative would have been to at least change the order to have out
      arguments in the end.
    
      I also hesitated to get another API in libgimp, which would have been
      config-aware (just returning the 2 check colors, depending on user-set
      Preferences), then having GimpPreviewArea handling 2 colors (without a
      GimpCheckType input). But actually, doing this, we'd remove the nice
      menu popup where one could choose a generic check type (not everyone
      wants to play with specific non-gray colors) in Gimp*Preview widgets.
      So in the end, I left this whole thing as-is.
      Instead I document the function with code sample to initialize
      properly the GimpPreviewArea (since libgimpwidgets/ are independent
      with no knowledge of the core config) in order to respect user
      preferences.
    - Hide the color properties in gimp_preview_area_menu_new() because
      anyway gimp_preview_area_menu_new() does not support GimpRGB
      properties right now (so all we get are warnings). It's still possible
      to select custom colors on GimpPreviewArea, simply we are stuck at the
      ones set in Preferences globally for now (unless a plug-in creates
      custom GUI to set these).
    
    Fixed Conflicts from !274:
            libgimp/gimp.h
            libgimpwidgets/gimppreviewarea.c

 app/widgets/gimprender.c         |  9 +++----
 libgimp/gimp.c                   |  4 ++++
 libgimpbase/gimpchecks.c         | 35 +++++++++++++++++----------
 libgimpbase/gimpchecks.h         |  4 +---
 libgimpwidgets/gimppreviewarea.c | 51 +++++++++++++++++++++++++---------------
 5 files changed, 65 insertions(+), 38 deletions(-)
---
diff --git a/app/widgets/gimprender.c b/app/widgets/gimprender.c
index f332702d2d..ccdd6efabb 100644
--- a/app/widgets/gimprender.c
+++ b/app/widgets/gimprender.c
@@ -88,18 +88,19 @@ gimp_render_setup_notify (gpointer    config,
                           GParamSpec *param_spec,
                           Gimp       *gimp)
 {
-  GimpCheckType check_type;
   GimpRGB       *color1_custom;
   GimpRGB       *color2_custom;
+  GimpCheckType  check_type;
 
   g_object_get (config,
-                "transparency-type", &check_type,
+                "transparency-type",          &check_type,
                 "transparency-custom-color1", &color1_custom,
                 "transparency-custom-color2", &color2_custom,
                 NULL);
 
-  gimp_checks_get_colors (check_type, &color1, &color2, *color1_custom, *color2_custom);
-
+  color1 = *color1_custom;
+  color2 = *color2_custom;
+  gimp_checks_get_colors (check_type, &color1, &color2);
   g_free (color1_custom);
   g_free (color2_custom);
 }
diff --git a/libgimp/gimp.c b/libgimp/gimp.c
index 71df47b478..136740d5a0 100644
--- a/libgimp/gimp.c
+++ b/libgimp/gimp.c
@@ -806,6 +806,8 @@ gimp_check_type (void)
  * This is a constant value given at plug-in configuration time.
  *
  * Return value: the _check_custom_color1 value
+ *
+ * Since: 3.0
  **/
 const GimpRGB *
 gimp_check_custom_color1 (void)
@@ -822,6 +824,8 @@ gimp_check_custom_color1 (void)
  * This is a constant value given at plug-in configuration time.
  *
  * Return value: the _check_custom_color2 value
+ *
+ * Since: 3.0
  **/
 const GimpRGB *
 gimp_check_custom_color2 (void)
diff --git a/libgimpbase/gimpchecks.c b/libgimpbase/gimpchecks.c
index faf13f28d8..988333b468 100644
--- a/libgimpbase/gimpchecks.c
+++ b/libgimpbase/gimpchecks.c
@@ -76,21 +76,32 @@ gimp_checks_get_shades (GimpCheckType  type,
 
 /**
  * gimp_checks_get_colors:
- * @type:          the checkerboard type
- * @color1:        return location for the first color,
- *                 usually the light color
- * @color2:        return location for the second color,
- *                 usually the dark color
- * @color1_custom: the first color to return if type is custom
- * @color2_custom: the second color to return if type is custom
+ * @type:            the checkerboard type
+ * @color1: (inout): current custom color and return location for the first color.
+ * @color2: (inout): current custom color and return location for the second color.
+ *
+ * Retrieves the colors to use when drawing a checkerboard for a certain
+ * #GimpCheckType and custom colors.
+ * If @type is %GIMP_CHECK_TYPE_CUSTOM_CHECKS, then @color1 and @color2
+ * will remain untouched, which means you must initialize them to the
+ * values expected for custom checks.
+ *
+ * To obtain the user-set colors in Preferences, just call:
+ * |[<!-- language="C" -->
+ * GimpRGB color1 = *(gimp_check_custom_color1 ());
+ * GimpRGB color2 = *(gimp_check_custom_color2 ());
+ * gimp_checks_get_colors (gimp_check_type (), &color1, &color2);
+ * ]|
+ *
+ * Since: 3.0
  **/
 void
 gimp_checks_get_colors (GimpCheckType  type,
                         GimpRGB       *color1,
-                        GimpRGB       *color2,
-                        GimpRGB        color1_custom,
-                        GimpRGB        color2_custom)
+                        GimpRGB       *color2)
 {
+  g_return_if_fail (color1 != NULL || color2 != NULL);
+
   if (color1)
     {
       switch (type)
@@ -111,7 +122,7 @@ gimp_checks_get_colors (GimpCheckType  type,
           *color1 = GIMP_CHECKS_BLACK_COLOR;
           break;
         case GIMP_CHECK_TYPE_CUSTOM_CHECKS:
-          *color1 = color1_custom;
+          /* Keep the current value. */
           break;
         default:
           *color1 = GIMP_CHECKS_GRAY_COLOR_LIGHT;
@@ -139,7 +150,7 @@ gimp_checks_get_colors (GimpCheckType  type,
           *color2 = GIMP_CHECKS_BLACK_COLOR;
           break;
         case GIMP_CHECK_TYPE_CUSTOM_CHECKS:
-          *color2 = color2_custom;
+          /* Keep the current value. */
           break;
         default:
           *color2 = GIMP_CHECKS_GRAY_COLOR_DARK;
diff --git a/libgimpbase/gimpchecks.h b/libgimpbase/gimpchecks.h
index 672786f22e..f188aa2119 100644
--- a/libgimpbase/gimpchecks.h
+++ b/libgimpbase/gimpchecks.h
@@ -141,9 +141,7 @@ void  gimp_checks_get_shades (GimpCheckType  type,
 
 void  gimp_checks_get_colors (GimpCheckType  type,
                               GimpRGB       *color1,
-                              GimpRGB       *color2,
-                              GimpRGB        color1_custom,
-                              GimpRGB        color2_custom);
+                              GimpRGB       *color2);
 
 
 G_END_DECLS
diff --git a/libgimpwidgets/gimppreviewarea.c b/libgimpwidgets/gimppreviewarea.c
index 8e2875b7f3..7bc7bc393b 100644
--- a/libgimpwidgets/gimppreviewarea.c
+++ b/libgimpwidgets/gimppreviewarea.c
@@ -181,12 +181,12 @@ gimp_preview_area_init (GimpPreviewArea *area)
 
   priv = area->priv;
 
-  priv->check_size = DEFAULT_CHECK_SIZE;
-  priv->check_type = DEFAULT_CHECK_TYPE;
+  priv->check_size          = DEFAULT_CHECK_SIZE;
+  priv->check_type          = DEFAULT_CHECK_TYPE;
   priv->check_custom_color1 = GIMP_CHECKS_CUSTOM_COLOR1;
   priv->check_custom_color2 = GIMP_CHECKS_CUSTOM_COLOR2;
-  priv->max_width  = -1;
-  priv->max_height = -1;
+  priv->max_width           = -1;
+  priv->max_height          = -1;
 
   gimp_widget_track_monitor (GTK_WIDGET (area),
                              G_CALLBACK (gimp_preview_area_destroy_transform),
@@ -461,6 +461,20 @@ gimp_preview_area_destroy_transform (GimpPreviewArea *area)
  *
  * Creates a new #GimpPreviewArea widget.
  *
+ * If the preview area is used to draw an image with transparency, you
+ * might want to default the checkboard size and colors to user-set
+ * Preferences. To do this, you may set the following properties on the
+ * newly created #GimpPreviewArea:
+ *
+ * |[<!-- language="C" -->
+ * g_object_set (area,
+ *               "check-size",          gimp_check_size (),
+ *               "check-type",          gimp_check_type (),
+ *               "check-custom-color1", gimp_check_custom_color1 (),
+ *               "check-custom-color2", gimp_check_custom_color2 (),
+ *               NULL);
+ * ]|
+ *
  * Returns: a new #GimpPreviewArea widget.
  *
  * Since GIMP 2.2
@@ -559,11 +573,9 @@ gimp_preview_area_draw (GimpPreviewArea *area,
     }
 
   size = 1 << (2 + priv->check_size);
-  gimp_checks_get_colors (priv->check_type,
-                          &color1,
-                          &color2,
-                          priv->check_custom_color1,
-                          priv->check_custom_color2);
+  color1 = priv->check_custom_color1;
+  color2 = priv->check_custom_color2;
+  gimp_checks_get_colors (priv->check_type, &color1, &color2);
   gimp_rgb_get_uchar (&color1, &r1, &g1, &b1);
   gimp_rgb_get_uchar (&color2, &r2, &g2, &b2);
 
@@ -869,11 +881,9 @@ gimp_preview_area_blend (GimpPreviewArea *area,
     }
 
   size = 1 << (2 + priv->check_size);
-  gimp_checks_get_colors (priv->check_type,
-                          &color1,
-                          &color2,
-                          priv->check_custom_color1,
-                          priv->check_custom_color2);
+  color1 = priv->check_custom_color1;
+  color2 = priv->check_custom_color2;
+  gimp_checks_get_colors (priv->check_type, &color1, &color2);
   gimp_rgb_get_uchar (&color1, &r1, &g1, &b1);
   gimp_rgb_get_uchar (&color2, &r2, &g2, &b2);
 
@@ -1270,11 +1280,9 @@ gimp_preview_area_mask (GimpPreviewArea *area,
     }
 
   size = 1 << (2 + priv->check_size);
-  gimp_checks_get_colors (priv->check_type,
-                          &color1,
-                          &color2,
-                          priv->check_custom_color1,
-                          priv->check_custom_color2);
+  color1 = priv->check_custom_color1;
+  color2 = priv->check_custom_color2;
+  gimp_checks_get_colors (priv->check_type, &color1, &color2);
   gimp_rgb_get_uchar (&color1, &r1, &g1, &b1);
   gimp_rgb_get_uchar (&color2, &r2, &g2, &b2);
 
@@ -2136,10 +2144,15 @@ gimp_preview_area_menu_popup (GimpPreviewArea *area,
                          gimp_preview_area_menu_new (area, "check-type"));
   gtk_menu_shell_append (GTK_MENU_SHELL (menu),
                          gimp_preview_area_menu_new (area, "check-size"));
+#if 0
+  /* gimp_preview_area_menu_new() currently only handles enum types, and
+   * in particular not color properties.
+   */
   gtk_menu_shell_append (GTK_MENU_SHELL (menu),
                          gimp_preview_area_menu_new (area, "check-custom-color1"));
   gtk_menu_shell_append (GTK_MENU_SHELL (menu),
                          gimp_preview_area_menu_new (area, "check-custom-color2"));
+#endif
 
   gtk_menu_popup_at_pointer (GTK_MENU (menu), (GdkEvent *) event);
 }