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

1 files changed, 36 insertions, 0 deletions

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