updated documentation for color handling - see STR #2226

- added text about color(0xRRGGBBII) call to common.dox and drawing.dox
- added doxygen comments for fl_show_chooser(), including image.



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

4 files changed, 77 insertions, 3 deletions

diff --git a/FL/fl_show_colormap.H b/FL/fl_show_colormap.H
index 29acf5eab..12159e50b 100644
--- a/FL/fl_show_colormap.H
+++ b/FL/fl_show_colormap.H
@@ -25,9 +25,25 @@
 //     http://www.fltk.org/str.php
 //
 
+/** \file
+   The fl_show_colormap() function hides the implementation classes used
+   to provide the popup window and color selection mechanism.
+*/
+
 #ifndef fl_show_colormap_H
 #define fl_show_colormap_H
 
+/* doxygen comment here to avoid exposing ColorMenu in fl_show_colormap.cxx
+*/
+/**
+  \brief Pops up a window to let the user pick an colormap entry.
+  \image html fl_show_colormap.gif 
+  \image latex  fl_show_colormap.eps "fl_show_colormap" width=8cm
+  \param[in] oldcol color to be highlighted when grid is shown.
+  \retval Fl_Color value of the chosen colormap entry.
+  \sa Fl_Color_Chooser
+*/
+ 
 FL_EXPORT Fl_Color fl_show_colormap(Fl_Color oldcol);
 
 #endif
diff --git a/documentation/src/common.dox b/documentation/src/common.dox
index 37a068b26..6f1b577cb 100644
--- a/documentation/src/common.dox
+++ b/documentation/src/common.dox
@@ -214,7 +214,7 @@ Fl::get_color(c, r, g, b);                  // Fl_Color to RGB
 The widget color is set using the \p color() method:
 
 \code
-button->color(FL_RED);
+button->color(FL_RED);                      // set color using named value
 \endcode
 
 Similarly, the label color is set using the \p labelcolor() method:
@@ -223,6 +223,27 @@ Similarly, the label color is set using the \p labelcolor() method:
 button->labelcolor(FL_WHITE);
 \endcode
 
+The Fl_Color encoding maps to a 32-bit unsigned integer representing
+RGBI, so it is also possible to specify a color using a hex constant
+as a color map index:
+
+\code
+button->color(0x000000ff);                  // colormap index #255 (FL_WHITE)
+\endcode
+
+or specify a color using a hex constant for the RGB components:
+
+\code
+button->color(0xff000000);                  // RGB: red
+button->color(0x00ff0000);                  // RGB: green
+button->color(0x0000ff00);                  // RGB: blue
+button->color(0xffffff00);                  // RGB: white
+\endcode
+
+\note
+If TrueColor is not available, any RGB colors will be set to
+the nearest entry in the colormap.
+
 \section common_boxtypes Box Types
 
 The type Fl_Boxtype stored and returned in Fl_Widget::box()
diff --git a/documentation/src/drawing.dox b/documentation/src/drawing.dox
index f06fec31f..99fa231a7 100644
--- a/documentation/src/drawing.dox
+++ b/documentation/src/drawing.dox
@@ -240,6 +240,42 @@ 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.
 
+As the Fl_Color encoding maps to a 32-bit unsigned integer representing
+RGBI, it is also possible to specify a color using a hex constant as a
+color map index:
+<pre>
+// COLOR MAP INDEX
+color(0x000000II)
+        ------ |
+           |   |
+           |   Color map index (8 bits)
+           Must be zero
+</pre>
+\code
+button->color(0x000000ff);                  // colormap index #255 (FL_WHITE)
+\endcode
+
+or specify a color using a hex constant for the RGB components:
+<pre>
+// RGB COLOR ASSIGNMENTS
+color(0xRRGGBB00)
+         | | | |
+         | | | Must be zero
+         | | Blue (8 bits)
+         | Green (8 bits)
+         Red (8 bits)
+</pre>
+\code
+button->color(0xff000000);                  // RGB: red
+button->color(0x00ff0000);                  // RGB: green
+button->color(0x0000ff00);                  // RGB: blue
+button->color(0xffffff00);                  // RGB: white
+\endcode
+
+\note
+If TrueColor is not available, any RGB colors will be set to
+the nearest entry in the colormap.
+
 \subsection ssect_Lines Line Dashes and Thickness
 
 FLTK supports drawing of lines with different styles and
diff --git a/src/fl_color.cxx b/src/fl_color.cxx
index b50b0794d..eab61af7f 100644
--- a/src/fl_color.cxx
+++ b/src/fl_color.cxx
@@ -361,8 +361,9 @@ void Fl::set_color(Fl_Color i, unsigned c) {
 
 #endif // end of X-specific code
 /**
-    Returns the RGB value(s) for the given FLTK color index. The
-    first form returns the RGB values packed in a 32-bit unsigned
+    Returns the RGB value(s) for the given FLTK color index.
+    
+    This form returns the RGB values packed in a 32-bit unsigned
     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.