Improve fl_contrast() functionality and documentation

- swap 3rd and 4th parameter of fl_contrast()
- change 'Fl_Fontsize fs' to a neutral 'int size' parameter
- clarify documentation of fl_contrast_level() and that different
  contrast algorithms use different level values
- clarify that level 39 for the CIELAB mode results in "sufficient"
  contrast, i.e. /readable/ text which is the only intention of
  fl_contrast().

Reasoning: swapping the arguments looks more natural, i.e. the context
before another argument (size) is what one would usually expect. Since
the 'size' argument doesn't have be a font size, making it a simple
'int size' is more flexible and correct for future extensions.
This commit is contained in:
Albrecht Schlosser 2024-05-17 14:20:01 +02:00
parent 7410498a7f
commit d0922792ae
2 changed files with 71 additions and 45 deletions

View File

@ -1161,19 +1161,22 @@ FL_EXPORT Fl_Color fl_inactive(Fl_Color c);
with fl_contrast_mode(FL_CONTRAST_CUSTOM).
Example:
\code
Fl_Color my_contrast(Fl_Color fg, Fl_Color bg, Fl_Fontsize fs, int context) {
Fl_Color my_contrast(Fl_Color fg, Fl_Color bg, int context, int size) {
// calculate contrast and ...
return color;
}
// call this early in your main() program:
fl_contrast_function(my_contrast);
fl_contrast_mode(FL_CONTRAST_CUSTOM);
fl_contrast_level(50); // optional, must be called after fl_contrast_mode()
\endcode
\see fl_contrast(Fl_Color, Fl_Color, Fl_Fontsize, int)
For parameters and types see fl_contrast(Fl_Color, Fl_Color, int, int).
\see fl_contrast(Fl_Color, Fl_Color, int, int)
\see fl_contrast_mode(int)
*/
typedef Fl_Color (Fl_Contrast_Function)(Fl_Color, Fl_Color, Fl_Fontsize, int);
typedef Fl_Color (Fl_Contrast_Function)(Fl_Color, Fl_Color, int, int);
FL_EXPORT void fl_contrast_function(Fl_Contrast_Function *f);
@ -1195,7 +1198,7 @@ FL_EXPORT int fl_contrast_level();
FL_EXPORT void fl_contrast_mode(int mode);
FL_EXPORT int fl_contrast_mode();
FL_EXPORT Fl_Color fl_contrast(Fl_Color fg, Fl_Color bg, Fl_Fontsize fs = 0, int context = 0);
FL_EXPORT Fl_Color fl_contrast(Fl_Color fg, Fl_Color bg, int context = 0, int size = 0);
FL_EXPORT double fl_lightness(Fl_Color color);
FL_EXPORT double fl_luminance(Fl_Color color);

View File

@ -1,7 +1,7 @@
//
// Color contrast functions for the Fast Light Tool Kit (FLTK).
//
// Copyright 1998-2022 by Bill Spitzak and others.
// Copyright 1998-2024 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
@ -46,8 +46,8 @@ static int fl_contrast_level_[10] = {
static Fl_Contrast_Function *fl_contrast_function_ = 0;
// The following function is (and must be!) the same as Fl::get_color()
// but can be inlined. We need this additional implementation because all contrast
// The following function is (and must be!) the same as Fl::get_color() but
// can be inlined. We need this additional implementation because all contrast
// related functions have been moved from fl_color.cxx to fl_contrast.cxx
// or have been directly implemented in fl_contrast.cxx (new functions).
// Inlining will hopefully prevent an extra function call.
@ -139,12 +139,13 @@ double fl_lightness(Fl_Color color) {
This can be used to tune the legacy fl_contrast() function to achieve
slightly better results. The default value is defined per contrast mode
(see below). Values between 50 and 70 are recommended but you can raise
it up to 100. Lower values than 50 are probably not useful.
(see below). Values between 50 and 70 may be useful for the legacy contrast
mode but you can raise it up to 100. Lower values than 50 are probably not
useful.
The contrast \p level affects not only the legacy (1.3.x) fl_contrast()
function but also the new CIELAB contrast mode which is the default since
FLTK 1.4.0.
FLTK 1.4.0. See default value below.
Other contrast modes are currently not affected by the contrast level.
@ -157,7 +158,7 @@ double fl_lightness(Fl_Color color) {
The default contrast level is
- 50 in mode FL_CONTRAST_LEGACY (compatible with FLTK 1.3.x)
- 55 in mode FL_CONTRAST_CIELAB
- 39 in mode FL_CONTRAST_CIELAB (similar threshold as in FLTK 1.3.x)
- 0 (undefined) for all other modes
See the description of fl_contrast_mode(int mode) for more information about
@ -166,7 +167,7 @@ double fl_lightness(Fl_Color color) {
Example:
\code
fl_contrast_mode(FL_CONTRAST_LEGACY);
fl_contrast_level(65);
fl_contrast_level(60);
\endcode
A \p level greater than 50 (probably best in the range 50 to 70) may achieve
@ -208,7 +209,7 @@ int fl_contrast_level() {
- FL_CONTRAST_NONE (not recommended: returns the foreground color)
- FL_CONTRAST_LEGACY (same as in FLTK 1.3.x)
- FL_CONTRAST_CIELAB (default since FLTK 1.4.0)
- FL_CONTRAST_CIELAB (better, this is the default since FLTK 1.4.0)
- FL_CONTRAST_CUSTOM (you must define your own contrast algorithm)
If you set FL_CONTRAST_CUSTOM you must also register your custom
@ -227,12 +228,24 @@ int fl_contrast_level() {
in higher contrast, i.e. the algorithm switches "earlier" to
black or white mode.
- FL_CONTRAST_CIELAB: defaut level is 55 which appears to be a good
- FL_CONTRAST_CIELAB: defaut level is 39 which appears to be a good
value. The higher the level is, the more contrast is to be expected.
Values in the range below 55 accept lower contrast and values above
55 switch "earlier" to black or white. Values between 45 and 65 may
Values in the range below 39 accept lower contrast and values above
39 switch "earlier" to black or white. Values between 36 and 46 may
yield usable contrast experience.
\note The goal of fl_contrast() is to achieve a "sufficient" contrast
between text and background. Level 39 in CIELAB mode means that the
accepted contrast is about 39% of the lightness difference between
both colors. This can be perceived as very low contrast in some cases,
but the text should at least be readable. Note that the highest possible
contrast value on a medium gray background is 50% (either black or white).
Bill Spitzak wrote on May 16, 2024 in fltk.general in thread "FLTK 1.4
Menu Bar Style": <i>"I would certainly aim for a function that does not
alter color combinations where it is physically possible to read the
text, even if squinting is needed."</i>\n
See https://groups.google.com/g/fltkgeneral/c/EkWI4HTHSLA/m/rsZunZ1vAwAJ
\param[in] mode if invalid, FL_CONTRAST_CIELAB will be selected
\since 1.4.0
@ -269,15 +282,16 @@ int fl_contrast_mode() {
Your custom contrast function must provide the signature
\code
Fl_Color my_contrast_function(Fl_Color fg, Fl_Color bg, Fl_Fontsize fs, int context)
Fl_Color my_contrast_function(Fl_Color fg, Fl_Color bg, int context, int size)
\endcode
The arguments are the same as for the full fl_contrast() function since FLTK 1.4.
You can use the supplied fontsize \p fs to modify the result. Depending on the
caller the \p fs parameter can be 0 (default) or a valid fontsize.
You can use the supplied \p size to modify the result. Depending on the
caller the \p size parameter can be 0 (default) or a valid size. In the context
of text, i.e. \p context == 0, the \p size parameter is the fontsize.
The \p context parameter is not yet used and will always be 0 unless included in
a call to fl_contrast(). The value 0 should be interpreted as text.
a call to fl_contrast(). The value 0 must be interpreted as text.
In the future the \p context argument will be used to supply a different context
than text (small icons, large icons, etc.). The exact usage is not yet specified.
@ -309,10 +323,10 @@ void fl_contrast_function(Fl_Contrast_Function *f) {
\param[in] fs,context fontsize and context (unused)
\return contrasting color
*/
static Fl_Color fl_contrast_legacy(Fl_Color fg, Fl_Color bg, Fl_Fontsize fs, int context) {
static Fl_Color fl_contrast_legacy(Fl_Color fg, Fl_Color bg, int context, int size) {
(void) fs; // currently ignored
(void) context; // currently ignored
(void) size; // currently ignored
// internal static variables, recalculated only if fl_contrast_level() is changed
@ -378,10 +392,10 @@ static Fl_Color fl_contrast_legacy(Fl_Color fg, Fl_Color bg, Fl_Fontsize fs, int
\param[in] fs,context unused: fontsize and context
\return contrasting color
*/
static Fl_Color fl_contrast_cielab(Fl_Color fg, Fl_Color bg, Fl_Fontsize fs, int context) {
static Fl_Color fl_contrast_cielab(Fl_Color fg, Fl_Color bg, int context, int size) {
(void) fs; // currently ignored
(void) context; // currently ignored
(void) size; // currently ignored
double tc = (double)fl_contrast_level(); // sufficient contrast threshold
double tbw = 50.; // black/white threshold
@ -421,15 +435,16 @@ static Fl_Color fl_contrast_cielab(Fl_Color fg, Fl_Color bg, Fl_Fontsize fs, int
You can change the behavior of fl_contrast() in several ways:
- Change the "level" (sensitivity) for contrast calculation, see fl_contrast_level().
Valid levels are 0 - 100, the default "medium" value is 50. If you raise the level
above 50 the overall contrast will generally be higher, i.e. the required contrast
to return the foreground color is raised and therefore the calculated color will
switch "earlier" to either black or white.
Valid levels are 0 - 100, the default "medium" value depends on the contrast mode.
If you raise the level above the default value the overall contrast will generally
be higher, i.e. the required contrast to return the foreground color is raised and
therefore the calculated color switches "earlier" to either black or white.
In other words, using the following values:
- 0 will always use the foreground color
- 50 will use the default, unmodified algorithm
- 0 always uses the foreground color
- the default, unmodified algorithm allows a sufficient contrast such that the text
is readable
- 100 will always use black or white
- values larger than 50 may yield slightly better results.
Changing the \p level is particularly useful and intended for the "legacy mode"
to improve the results partially. Values slightly above 50 (50 - 70) will likely
return the best results (50 is the default, as used in FLTK 1.3.x).
@ -454,25 +469,33 @@ static Fl_Color fl_contrast_cielab(Fl_Color fg, Fl_Color bg, Fl_Fontsize fs, int
to use the new default function:
- FL_CONTRAST_CIELAB, based on the CIELAB (L*a*b*) color model. This function
is superior regarding the visual contrast perception but may be slower.
is superior regarding the human contrast perception but may be slightly
slower - which should not matter on a modern CPU. The default contrast
level in this mode is 39 which results in a very similar experience as the
old contrast function but avoids unreadable border cases.
<b>This is the default since FLTK 1.4.0.</b>
- FL_CONTRAST_CUSTOM, your own contrast calculation function.
In the future we \b may provide even more (and superior) contrast algorithms.
The new parameters \p fs and \p context (since 1.4.0) are defined for future
extensions and are currently not used. Default values are 0.
The new parameters \p context and \p size (since 1.4.0) are defined for
future extensions and are currently not used. Default values are 0.
- The \p context is intended to differentiate text and other kinds
of objects, e.g. radio buttons, check marks, or icon types.
- The \p size parameter is an unspecified (object) size that may be used to
calculate the required contrast. In text mode this must be the font size.
Rule: the larger the object (font), the lower the required contrast.
\note These new optional parameters must be provided in the custom contrast
function which is the reason why they are added now. In the future we may use
the fontsize to adjust the calculated contrast, and users defining their own
contrast functions may use them in their functions.
the (font) size to adjust the calculated contrast, and users defining their
own contrast functions may use them in their functions.
\param[in] fg foreground (text) color
\param[in] bg background color
\param[in] fs font size (optional, default = 0 == undefined)
\param[in] context graphical context (optional, default = 0 == text)
\param[in] size unspecified size (optional, default = 0 == undefined)
\return contrasting color: \p fg, \p FL_BLACK, or \p FL_WHITE
@ -480,21 +503,21 @@ static Fl_Color fl_contrast_cielab(Fl_Color fg, Fl_Color bg, Fl_Fontsize fs, int
\see fl_contrast_mode(int)
\see fl_contrast_function()
*/
Fl_Color fl_contrast(Fl_Color fg, Fl_Color bg, Fl_Fontsize fs, int context) {
Fl_Color fl_contrast(Fl_Color fg, Fl_Color bg, int context, int size) {
switch (fl_contrast_mode_) {
case FL_CONTRAST_LEGACY:
return fl_contrast_legacy(fg, bg, fs, context);
return fl_contrast_legacy(fg, bg, context, size);
case FL_CONTRAST_CUSTOM:
if (fl_contrast_function_)
return (fl_contrast_function_)(fg, bg, fs, context);
return (fl_contrast_function_)(fg, bg, context, size);
// FALLTHROUGH
case FL_CONTRAST_CIELAB:
return fl_contrast_cielab(fg, bg, fs, context);
return fl_contrast_cielab(fg, bg, context, size);
default: // unknown (none): return fg
break;