4 files changed, 75 insertions, 14 deletions
diff --git a/documentation/src/common.dox b/documentation/src/common.dox
index 6b3e19587..37a068b26 100644
--- a/documentation/src/common.dox
+++ b/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:
diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox
index 68bb2df24..f06fec31f 100644
--- a/documentation/src/drawing.dox
+++ b/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
diff --git a/documentation/src/enumerations.dox b/documentation/src/enumerations.dox
index 9a1a5ae88..c34cdd962 100644
--- a/documentation/src/enumerations.dox
+++ b/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
diff --git a/documentation/src/index.dox b/documentation/src/index.dox
index 99c602975..4adfb3386 100644
--- a/documentation/src/index.dox
+++ b/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