Author: engelsman
Date: 2010-10-27 15:07:55 -0700 (Wed, 27 Oct 2010)
New Revision: 7762
Log:
reworked color documentation as suggested in STR #2373
part of the confusion was the main page link to
Common Widgets and Attributes/Colors actually went to
Drawing Things in FLTK/Colors therefore making it harder
to find information.
Common Widgets and Attribute/Colors now simplified
Drawing Things in FLTK/Colors now expanded
FLTK Enumerations/Colors now simplified
Modified:
branches/branch-1.3/FL/Fl.H
branches/branch-1.3/documentation/src/common.dox
branches/branch-1.3/documentation/src/drawing.dox
branches/branch-1.3/documentation/src/enumerations.dox
branches/branch-1.3/documentation/src/index.dox
branches/branch-1.3/src/fl_color.cxx
Modified: branches/branch-1.3/FL/Fl.H
===================================================================
--- branches/branch-1.3/FL/Fl.H 2010-10-27 20:03:37 UTC (rev 7761)
+++ branches/branch-1.3/FL/Fl.H 2010-10-27 22:07:55 UTC (rev 7762)
@@ -718,15 +718,15 @@
Sets an entry in the fl_color index table. You can set it to any
8-bit RGB color. The color is not allocated until fl_color(i) is used.
*/
- static void set_color(Fl_Color, unsigned); // platform dependent
- static Fl_Color get_color(Fl_Color);
- static void get_color(Fl_Color, uchar&, uchar&, uchar&);
+ static void set_color(Fl_Color i, unsigned c); // platform dependent
+ static unsigned get_color(Fl_Color i);
+ static void get_color(Fl_Color i, uchar &red, uchar &green, uchar &blue);
/**
Frees the specified color from the colormap, if applicable.
If overlay is non-zero then the color is freed from the
overlay colormap.
*/
- static void free_color(Fl_Color, int overlay = 0); // platform dependent
+ static void free_color(Fl_Color i, int overlay = 0); // platform dependent
// fonts:
static const char* get_font(Fl_Font);
Modified: branches/branch-1.3/documentation/src/common.dox
===================================================================
--- branches/branch-1.3/documentation/src/common.dox 2010-10-27 20:03:37 UTC
(rev 7761)
+++ branches/branch-1.3/documentation/src/common.dox 2010-10-27 22:07:55 UTC
(rev 7762)
@@ -174,6 +174,12 @@
the X or WIN32 colormap, but instead is an internal table with
fixed contents.
+See the
+\ref drawing_colors
+section of
+\ref drawing
+for implementation details.
+
There are symbols for naming some of the more common colors:
\li \p FL_BLACK
@@ -186,20 +192,23 @@
\li \p FL_WHITE
\li \p FL_WHITE
-These symbols are the default colors for all FLTK widgets. They are
-explained in more detail under
-\ref enumerations_colors in
-\ref enumerations.
+Other symbols are used as the default colors for all FLTK widgets.
\li \p FL_FOREGROUND_COLOR
\li \p FL_BACKGROUND_COLOR
\li \p FL_INACTIVE_COLOR
\li \p FL_SELECTION_COLOR
-RGB colors can be set using the \p fl_rgb_color() function:
+The full list of named color values can be found in
+\ref enumerations_colors "FLTK Enumerations".
+A color value can be created from its RGB components by using the
+\p %fl_rgb_color() function, and decomposed again with
+\p Fl::get_color():
+
\code
-Fl_Color c = fl_rgb_color(85, 170, 255);
+Fl_Color c = fl_rgb_color(85, 170, 255); // RGB to Fl_Color
+Fl::get_color(c, r, g, b); // Fl_Color to RGB
\endcode
The widget color is set using the \p color() method:
Modified: branches/branch-1.3/documentation/src/drawing.dox
===================================================================
--- branches/branch-1.3/documentation/src/drawing.dox 2010-10-27 20:03:37 UTC
(rev 7761)
+++ branches/branch-1.3/documentation/src/drawing.dox 2010-10-27 22:07:55 UTC
(rev 7762)
@@ -153,8 +153,13 @@
\section drawing_colors Colors
-FLTK manages colors as 32-bit unsigned integers. Values from
-0 to 255 represent colors from the FLTK 1.0.x standard colormap
+FLTK manages colors as 32-bit unsigned integers, encoded as RGBI.
+When the RGB bytes are non-zero, the value is treated as RGB.
+If these bytes are zero, the I byte will be used as an index
+into the colormap.
+
+Values from 0 to 255, i.e. the I index value, represent
+colors from the FLTK 1.3.x standard colormap
and are allocated as needed on screens without TrueColor support.
The \b Fl_Color enumeration type defines the
standard colors and color cube for the first 256 colors. All of
@@ -164,12 +169,15 @@
Color values greater than 255 are treated as 24-bit RGB
values. These are mapped to the closest color supported by the
screen, either from one of the 256 colors in the FLTK 1.3.x
-colormap or a direct RGB value on TrueColor screens. You can
-generate 24-bit RGB color values using the
-fl_rgb_color(uchar r, uchar b, uchar c) and
-fl_rgb_color(uchar grayscale)
-functions.
+colormap or a direct RGB value on TrueColor screens.
+Fl_Color fl_rgb_color(uchar r, uchar g, uchar b) <br>
+Fl_Color fl_rgb_color(uchar grayscale)
+
+\par
+Generate Fl_Color out of specified
+8-bit RGB values or one 8-bit grayscale value.
+
void fl_color(Fl_Color c) <br>
void fl_color(int c)
@@ -198,6 +206,40 @@
is used directly on TrueColor displays. For colormap visuals the
nearest index in the gray ramp or color cube is used.
+unsigned Fl::get_color(Fl_Color i) <br>
+void Fl::get_color(Fl_Color i, uchar &red, uchar &green, uchar &blue)
+
+\par
+Generate RGB values from a colormap index value \p i.
+The first returns the RGB as a 32-bit unsigned integer,
+and the second decomposes the RGB into three 8-bit values.
+\todo work out why Fl::get_color() does not give links!
+
+Fl::get_system_colors() <br>
+Fl::foreground() <br>
+Fl::background() <br>
+Fl::background2()
+
+\par
+The first gets color values from the user preferences or the system,
+and the other routines are used to apply those values.
+
+Fl::own_colormap() <br>
+Fl::free_color(Fl_Color i, int overlay) <br>
+Fl::set_color(Fl_Color i, unsigned c)
+
+\par
+\p Fl::own_colormap() is used to install a local colormap [X11 only].
+\par
+\p Fl::free_color() and \p Fl::set_color() are used to remove and replace
+entries from the colormap.
+\todo work out why these do not give links!
+
+There are two predefined graphical interfaces for choosing colors.
+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.
+
\subsection ssect_Lines Line Dashes and Thickness
FLTK supports drawing of lines with different styles and
Modified: branches/branch-1.3/documentation/src/enumerations.dox
===================================================================
--- branches/branch-1.3/documentation/src/enumerations.dox 2010-10-27
20:03:37 UTC (rev 7761)
+++ branches/branch-1.3/documentation/src/enumerations.dox 2010-10-27
22:07:55 UTC (rev 7762)
@@ -243,6 +243,16 @@
\li FL_WHITE
\li FL_YELLOW
+The following are named values within the standard grayscale:
+
+\li FL_GRAY0
+\li FL_DARK3
+\li FL_DARK2
+\li FL_DARK1
+\li FL_LIGHT1
+\li FL_LIGHT2
+\li FL_LIGHT3
+
The inline methods for getting a grayscale, color cube, or
RGB color value are described in the
\ref drawing_colors
Modified: branches/branch-1.3/documentation/src/index.dox
===================================================================
--- branches/branch-1.3/documentation/src/index.dox 2010-10-27 20:03:37 UTC
(rev 7761)
+++ branches/branch-1.3/documentation/src/index.dox 2010-10-27 22:07:55 UTC
(rev 7762)
@@ -38,7 +38,7 @@
\subpage basics
\subpage common
- - \ref drawing_colors
+ - \ref common_colors
- \ref common_boxtypes
- \ref common_labels
- \ref drawing_images
Modified: branches/branch-1.3/src/fl_color.cxx
===================================================================
--- branches/branch-1.3/src/fl_color.cxx 2010-10-27 20:03:37 UTC (rev
7761)
+++ branches/branch-1.3/src/fl_color.cxx 2010-10-27 22:07:55 UTC (rev
7762)
@@ -366,9 +366,6 @@
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.
-
- The second form returns the red, green, and blue values
- separately in referenced variables.
*/
unsigned Fl::get_color(Fl_Color i) {
if (i & 0xffffff00) return (i);
@@ -383,7 +380,14 @@
Fl::set_color((Fl_Color)(i & 255),
((unsigned)red<<24)+((unsigned)green<<16)+((unsigned)blue<<8));
}
-/** See unsigned get_color(Fl_Color c) */
+/**
+ Returns the RGB value(s) for the given FLTK color index.
+
+ This form returns the red, green, and blue values
+ separately in referenced variables.
+
+ See also unsigned get_color(Fl_Color c)
+ */
void Fl::get_color(Fl_Color i, uchar &red, uchar &green, uchar &blue) {
unsigned c;
_______________________________________________
fltk-commit mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-commit
