#842: Documents args() color values and how they apply

src/Fl_arg.cxx

@@ -106,10 +106,27 @@ extern const char *fl_bg2;
   <br>
   Enables or disables tooltips using Fl_Tooltip::enable().
 
+  Color values are commonly given as three digit or six digit hex numbers.
+
+  * the order of fg, bg, and bg2 in the command line does not matter
+  * there is no way at the moment to set the selection color
+  * setting the bg2 color also changes the fg color to have sufficient contrast
+  * explicitly setting fg color overrides the bg2/contrast constraint
+  * setting the bg color will update the color lookup table for the gray ramp,
+    so color index values  can stay the same for all apps, it's just mapped to
+    different RGB values
+  * the calculation of the gray ramp is only based on the bg color, so there is
+    no way at the moment to create an inverted (dark mode) ramp
+  * consequently, setting bg to black creates a an all-black ramp, setting a
+    somewhat dark bg color creates a extremely dark ramp
+  * setting the bg has no influence on bg2 or fg
 
   If your program requires other switches in addition to the standard
   FLTK options, you will need to pass your own argument handler to
   Fl::args(int,char**,int&,Fl_Args_Handler) explicitly.
+
+  \see fl_parse_color(const char* p, uchar& r, uchar& g, uchar& b) to see how
+  color values can be defined
 */
 int Fl::arg(int argc, char **argv, int &i) {
   arg_called = 1;

src/Fl_get_system_colors.cxx

@@ -83,7 +83,30 @@ const char *fl_fg = NULL;
 const char *fl_bg = NULL;
 const char *fl_bg2 = NULL;
 
+/**
+ Parse a string containing a description of a color and write r, g, and b.
 
+ This call is used by the Pixmap file format interpreter and by the command
+ line arguments parser to set UI colors.
+
+ RGB color triplets usually start with a '#' character, but it can be omitted
+ if it does not conflict with the later rules. Color components are defined
+ in hexadecimal notation with 1, 2, 3, or four hex digits per component, making
+ color triplets 3, 6, 9, or 12 characters long. The interpreter is case
+ insensitive. Valid codes examples include "FF0000" for red, "#0F0" for green,
+ and "000000004444" for a dark blue.
+
+ On X11 platforms, color values can also be given a color name like "red".
+ the list of available colors names is provided of the X11 server.
+
+ If non of the color interpretations work, `fl_parse_color` color returns 0.
+ The Pixmap reader interprets those a transparent, and are usually written as
+ "None", "#transparent", or "bg".
+
+ \param[in] p a C-string describing the color
+ \param[out] r, g, b the color components in a range from 0...255
+ \return 0 if the color can not be interpreted, 1 otherwise
+ */
 int fl_parse_color(const char* p, uchar& r, uchar& g, uchar& b) {
   return Fl::screen_driver()->parse_color(p, r, g, b);
 }