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

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()

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