reworked color documentation as suggested in STR #2373

part of the confusion was the main page link to
Common Widgets and Attributes/Colors actually went to
Drawing Things in FLTK/Colors therefore making it harder
to find information.

Common Widgets and Attribute/Colors now simplified

Drawing Things in FLTK/Colors now expanded

FLTK Enumerations/Colors now simplified



git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@7762 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

FL/Fl.H

@@ -718,15 +718,15 @@ public:
     Sets an entry in the fl_color index table. You can set it to any
     8-bit RGB color. The color is not allocated until fl_color(i) is used.
   */
-  static void	set_color(Fl_Color, unsigned); // platform dependent
-  static Fl_Color get_color(Fl_Color);
-  static void	get_color(Fl_Color, uchar&, uchar&, uchar&);
+  static void	set_color(Fl_Color i, unsigned c); // platform dependent
+  static unsigned get_color(Fl_Color i);
+  static void	get_color(Fl_Color i, uchar &red, uchar &green, uchar &blue);
   /**
     Frees the specified color from the colormap, if applicable.
     If overlay is non-zero then the color is freed from the
     overlay colormap.
   */
-  static void	free_color(Fl_Color, int overlay = 0); // platform dependent
+  static void	free_color(Fl_Color i, int overlay = 0); // platform dependent
 
   // fonts:
   static const char* get_font(Fl_Font);

documentation/src/common.dox

@@ -174,6 +174,12 @@ colors or a 24-bit RGB color. The color palette is \e not
 the X or WIN32 colormap, but instead is an internal table with
 fixed contents.
 
+See the
+\ref drawing_colors
+section of
+\ref drawing
+for implementation details.
+
 There are symbols for naming some of the more common colors:
 
 \li \p FL_BLACK
@@ -186,20 +192,23 @@ There are symbols for naming some of the more common colors:
 \li \p FL_WHITE
 \li \p FL_WHITE
 
-These symbols are the default colors for all FLTK widgets. They are
-explained in more detail under
-\ref enumerations_colors in
-\ref enumerations.
+Other symbols are used as the default colors for all FLTK widgets.
 
 \li \p FL_FOREGROUND_COLOR
 \li \p FL_BACKGROUND_COLOR
 \li \p FL_INACTIVE_COLOR
 \li \p FL_SELECTION_COLOR
 
-RGB colors can be set using the \p fl_rgb_color() function:
+The full list of named color values can be found in
+\ref enumerations_colors "FLTK Enumerations".
+
+A color value can be created from its RGB components by using the
+\p %fl_rgb_color() function, and decomposed again with
+\p Fl::get_color():
 
 \code
-Fl_Color c = fl_rgb_color(85, 170, 255);
+Fl_Color c = fl_rgb_color(85, 170, 255);    // RGB to Fl_Color
+Fl::get_color(c, r, g, b);                  // Fl_Color to RGB
 \endcode
 
 The widget color is set using the \p color() method:

documentation/src/drawing.dox

@@ -153,8 +153,13 @@ the current clipping region.
 
 \section drawing_colors Colors
 
-FLTK manages colors as 32-bit unsigned integers. Values from
-0 to 255 represent colors from the FLTK 1.0.x standard colormap
+FLTK manages colors as 32-bit unsigned integers, encoded as RGBI.
+When the RGB bytes are non-zero, the value is treated as RGB.
+If these bytes are zero, the I byte will be used as an index
+into the colormap.
+
+Values from 0 to 255, i.e. the I index value, represent
+colors from the FLTK 1.3.x standard colormap
 and are allocated as needed on screens without TrueColor support.
 The \b Fl_Color enumeration type defines the
 standard colors and color cube for the first 256 colors. All of
@@ -164,11 +169,14 @@ these are named with symbols in
 Color values greater than 255 are treated as 24-bit RGB
 values. These are mapped to the closest color supported by the
 screen, either from one of the 256 colors in the FLTK 1.3.x
-colormap or a direct RGB value on TrueColor screens. You can
-generate 24-bit RGB color values using the
-fl_rgb_color(uchar r, uchar b, uchar c) and
-fl_rgb_color(uchar grayscale)
-functions.
+colormap or a direct RGB value on TrueColor screens.
+
+Fl_Color fl_rgb_color(uchar r, uchar g, uchar b) <br>
+Fl_Color fl_rgb_color(uchar grayscale)
+
+\par
+Generate Fl_Color out of specified
+8-bit RGB values or one 8-bit grayscale value.
 
 void fl_color(Fl_Color c) <br>
 void fl_color(int c)
@@ -198,6 +206,40 @@ closest possible match to the RGB color is used. The RGB color
 is used directly on TrueColor displays. For colormap visuals the
 nearest index in the gray ramp or color cube is used.
 
+unsigned Fl::get_color(Fl_Color i) <br>
+void Fl::get_color(Fl_Color i, uchar &red, uchar &green, uchar &blue)
+
+\par
+Generate RGB values from a colormap index value \p i.
+The first returns the RGB as a 32-bit unsigned integer,
+and the second decomposes the RGB into three 8-bit values.
+\todo work out why Fl::get_color() does not give links!
+
+Fl::get_system_colors() <br>
+Fl::foreground() <br>
+Fl::background() <br>
+Fl::background2()
+
+\par
+The first gets color values from the user preferences or the system,
+and the other routines are used to apply those values.
+
+Fl::own_colormap() <br>
+Fl::free_color(Fl_Color i, int overlay) <br>
+Fl::set_color(Fl_Color i, unsigned c)
+
+\par
+\p Fl::own_colormap() is used to install a local colormap [X11 only].
+\par
+\p Fl::free_color() and \p Fl::set_color() are used to remove and replace
+entries from the colormap.
+\todo work out why these do not give links!
+
+There are two predefined graphical interfaces for choosing colors.
+The function fl_show_colormap() shows a table of colors and returns an
+Fl_Color index value.
+The Fl_Color_Chooser widget provides a standard RGB color chooser.
+
 \subsection ssect_Lines Line Dashes and Thickness
 
 FLTK supports drawing of lines with different styles and

documentation/src/enumerations.dox

@@ -243,6 +243,16 @@ FLTK standard color cube:
 \li FL_WHITE
 \li FL_YELLOW
 
+The following are named values within the standard grayscale:
+
+\li FL_GRAY0
+\li FL_DARK3
+\li FL_DARK2
+\li FL_DARK1
+\li FL_LIGHT1
+\li FL_LIGHT2
+\li FL_LIGHT3
+
 The inline methods for getting a grayscale, color cube, or
 RGB color value are described in the
 \ref drawing_colors

documentation/src/index.dox

@@ -38,7 +38,7 @@
     \subpage basics
 
     \subpage common
-	- \ref drawing_colors
+	- \ref common_colors
 	- \ref common_boxtypes
 	- \ref common_labels
 	- \ref drawing_images

src/fl_color.cxx

@@ -366,9 +366,6 @@ void Fl::set_color(Fl_Color i, unsigned c) {
     integer with the red value in the upper 8 bits, the green value
     in the next 8 bits, and the blue value in bits 8-15.  The lower
     8 bits will always be 0.
-    
-    The second form returns the red, green, and blue values
-    separately in referenced variables.
 */
 unsigned Fl::get_color(Fl_Color i) {
   if (i & 0xffffff00) return (i);
@@ -383,7 +380,14 @@ void Fl::set_color(Fl_Color i, uchar red, uchar green, uchar blue) {
   Fl::set_color((Fl_Color)(i & 255),
 	((unsigned)red<<24)+((unsigned)green<<16)+((unsigned)blue<<8));
 }
-/** See unsigned get_color(Fl_Color c) */
+/**
+    Returns the RGB value(s) for the given FLTK color index. 
+    
+    This form returns the red, green, and blue values
+    separately in referenced variables.
+
+    See also unsigned get_color(Fl_Color c)
+ */
 void Fl::get_color(Fl_Color i, uchar &red, uchar &green, uchar &blue) {
   unsigned c;