Add Fl_Scheme::plastic_color_average() method [#464]

This method can be used to set a more appropriate color average to
prevent "graying out" the box colors of the 'plastic' scheme.
Alternatively environment variable 'FLTK_PLASTIC_AVERAGE' can be used
to set the color average value. See docs for details.

Set color average to 45% in test/unittests demo program.

1 files changed, 87 insertions, 3 deletions

diff --git a/src/fl_plastic.cxx b/src/fl_plastic.cxx
index 0830f0451..5030ac389 100644
--- a/src/fl_plastic.cxx
+++ b/src/fl_plastic.cxx
@@ -18,18 +18,102 @@
 //     https://www.fltk.org/bugs.php
 //
 
+/**
+  \file src/fl_plastic.cxx
+  \brief Implementation of the \c 'plastic' scheme.
+*/
+
 // Box drawing code for an obscure box type.
 // These box types are in separate files so they are not linked
 // in if not used.
 
 #include <FL/Fl.H>
+#include <FL/Fl_Scheme.H>
 #include <FL/fl_draw.H>
-#include "flstring.h"
 
-extern const uchar *fl_gray_ramp();
+#include <cassert>
+
+// Globals
+
+extern const uchar *fl_gray_ramp();     // in src/fl_boxtype.cxx
+
+// Module globals (static)
+
+static float plastic_average = -1.00f;  // plastic color average: not yet set
+static int av_min =  10;                // min. supported average
+static int av_def =  75;                // default average (up to FLTK 1.4)
+static int av_max = 100;                // max. supported average
+
+
+// clamp and set color average value
+
+static void set_color_average(int av) {
+  if (av < av_min)
+    plastic_average = av_min / 100.f;
+  else if (av > av_max)
+    plastic_average = av_max / 100.f;
+  else
+    plastic_average = av / 100.f;
+}
+
+/**
+  Set the color average value of the 'plastic' scheme in percent.
+
+  Legal values are in the range [ 10 ... 100 ], other values are clamped. The
+  default value is 75 which is backwards compatible with FLTK 1.4 and earlier.
+
+  Higher values make the colors in boxes etc. appear "more gray" whereas lower
+  values make colors appear more like the original color. The recommended value
+  is about 40 to 60 but this is left to the user.
+
+  If this method is not called then the environment variable \c FLTK_PLASTIC_AVERAGE
+  can be used to set the color average. The environment variable must be a pure
+  numeric (integer) value in the given range, otherwise the behavior is undefined.
+
+  However, calling \b this method takes precedence over the environment variable.
+  This method can be called at any time (e.g. to view dynamic changes). This will
+  permanently change the appearance for all later box / background drawings.
+
+  For details see GitHub Issue 464: "RFE: plastic scheme with faithful colors".
+
+  \note Program developers are supposed to use this method to apply "better"
+    values than the default (1.4) look and feel. End users are supposed to use
+    the environment variable for programs that \b don't use
+    Fl_Scheme::plastic_color_average().
+
+  Include the following header:
+  \code
+    #include <FL/Fl_Scheme.H>
+  \endcode
+
+  \param[in]  av  color average value in the documented range.
+
+  \since 1.5.0
+*/
+void Fl_Scheme::plastic_color_average(int av) {
+  set_color_average(av);
+}
+
+// Get 'plastic' color average from environment variable 'FLTK_PLASTIC_AVERAGE'
+// unless it has already been set.
+// See GitHub Issue # 464: "RFE: plastic scheme with faithful colors"
+
+static float plastic_color_average() {
+  if (plastic_average < 0.0f) {               // only once
+    char *envvar = fl_getenv("FLTK_PLASTIC_AVERAGE");
+    if (envvar) {                             // convert and store env. var.
+      int temp = atoi(envvar);                // may be 0, but will be clamped
+      set_color_average(temp);                // clamp and set value
+    } else {
+      plastic_average = av_def / 100.0f;      // set default value
+    }
+  }
+  assert(plastic_average >= 0);
+  return plastic_average;
+}
 
 inline Fl_Color shade_color(uchar gc, Fl_Color bc) {
-  return fl_color_average((Fl_Color)gc, bc, 0.75f);
+  return fl_color_average((Fl_Color)gc, bc, plastic_color_average());
 }
 
 static void frame_rect(int x, int y, int w, int h, const char *c, Fl_Color bc) {