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, 22 insertions, 1 deletions

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