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.

FL/Fl_Scheme.H

@@ -1,7 +1,7 @@
 //
-// Scheme header for the Fast Light Tool Kit (FLTK).
+// Fl_Scheme header for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 2022-2023 by Bill Spitzak and others.
+// Copyright 2022-2025 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -14,12 +14,22 @@
 //     https://www.fltk.org/bugs.php
 //
 
-#ifndef FL_Fl_Scheme_H_
+#ifndef _FL_Fl_Scheme_H_
-#define FL_Fl_Scheme_H_
+#define _FL_Fl_Scheme_H_
 
 #include <FL/Fl.H>
 
-class Fl_Scheme {
+/**
+  \brief Base class with static methods for future Fl_Scheme classes.
+
+  This class is intentionally not fully documented and is subject to change
+  in future FLTK versions.
+
+  \note Do not rely on details of this class.
+
+  \since 1.4.0
+*/
+class FL_EXPORT Fl_Scheme {
 
 private:
 
@@ -54,11 +64,17 @@ public:
     return num_schemes_;
   }
 
-  // Adding a scheme name must be a public static method in FLTK 1.4.0.
+  // Adding a scheme name must be a public static method in (since) FLTK 1.4.0.
   // This will later be protected or replaced by another method name.
 
   static int add_scheme_name(const char *name);
 
+  // Set color average parameter of the 'plastic' scheme.
+  // See GitHub Issue 464: "RFE: plastic scheme with faithful colors".
+  // See also documentation and implementation in src/fl_plastic.cxx.
+
+  static void plastic_color_average(int av);
+
 }; // class Fl_Scheme
 
-#endif // FL_Fl_Scheme_H_
+#endif // _FL_Fl_Scheme_H_

src/Fl_Scheme.cxx

@@ -1,7 +1,7 @@
 //
-// Scheme implementation for the Fast Light Tool Kit (FLTK).
+// Fl_Scheme class implementation for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 2022-2023 by Bill Spitzak and others.
+// Copyright 2022-2025 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -14,6 +14,18 @@
 //     https://www.fltk.org/bugs.php
 //
 
+/**
+  \file src/Fl_Scheme.cxx
+  \brief Implementation of the Fl_Scheme class.
+
+  This class is intentionally not fully documented and is subject to change
+  in future FLTK versions.
+
+  \note Do not rely on details of this class.
+
+  \since 1.4.0
+*/
+
 #include <FL/Fl.H>
 #include <FL/Fl_Window.H>
 #include <FL/Fl_Scheme.H>
@@ -41,8 +53,8 @@ int Fl_Scheme::alloc_size_     = 0;
   The list of scheme names is nul-terminated.
 
   \note
-    Currently (in FLTK 1.4.0) schemes can only be added to the list and
+    Currently (since FLTK 1.4.0) schemes can only be added and can't be
-    not removed from the list. This may change in a later version.
+    removed from the list. This may change in a later version.
 
   \return  List of currently known scheme names.
 */
@@ -68,7 +80,7 @@ const char **Fl_Scheme::names() {
 /**
   Add a scheme name to the list of known schemes.
 
-  This method is public in FLTK 1.4.0 because derived classes of Fl_Scheme
+  This method is public since FLTK 1.4.0 because derived classes of Fl_Scheme
   are not yet implemented. Thus, users implementing their own schemes can
   use this method to add the scheme name to the list of known schemes
   which is for instance used in Fl_Scheme::names().
@@ -76,7 +88,7 @@ const char **Fl_Scheme::names() {
   \note \b Attention!
     In a future version, when subclasses of Fl_Scheme will be implemented,
     this method will either be replaced by another \p protected method or
-    it will no longer do anything (kept only for ABI reasons).
+    it will no longer do anything (kept only for backwards compatibility).
 
   The new scheme name must consist of valid ASCII characters as described
   below:

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) {

test/unittests.cxx

@@ -1,7 +1,7 @@
 //
 // Unit tests for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2022 by Bill Spitzak and others.
+// Copyright 1998-2025 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -32,6 +32,7 @@
 #include <FL/Fl_Terminal.H>
 #include <FL/Fl_Group.H>
 #include <FL/Fl_Box.H>
+#include <FL/Fl_Scheme.H>
 #include <FL/fl_draw.H>               // fl_text_extents()
 #include <FL/fl_string_functions.h>   // fl_strdup()
 #include <FL/fl_ask.H>                // fl_message()
@@ -469,6 +470,9 @@ int main(int argc, char** argv) {
     }
   }
 
+  // Set a more appropriate color average for the "plastic" scheme (since FLTK 1.5)
+  Fl_Scheme::plastic_color_average(45);
+
   mainwin->resizable(mainwin);
   mainwin->show(argc, argv);
   // Select first test in browser, and show that test.