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

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