ChartDirector Ver 3.1 (PHP Edition Edition)
Color Specification
Many functions in the ChartDirector API accept colors as parameters.
ChartDirector supports colors specified in web and HTML compatible ARGB format,
in which ARGB refers to the Alpha transparency, Red, Green and Blue components
of the color.
In addition to ARGB colors, ChartDirector supports "dynamic" colors. A dynamic
color is a color that changes depending on the position of the pixels. The
"dynamic" colors that ChartDirector supports include "gradient colors", "pattern
colors" and "dash line colors".
ChartDirector supports specifying colors indirectly using "palette colors". When
a "palette color" is used, the color is specified as an index to a palette. The
actual color is looked up from the palette.
ARGB Color
ARGB color consists of 4 components - alpha transparency, red, green and blue.
The four components are encoded as a 32-bit number, with each component occupying
8 bits. In hexadecimal notation, it is AARRGGBB, where
AA, RR, GG and BB are
the alpha transpareny, red, green and blue components.
Each component ranges from 00 - FF (0 - 255), representing its intensity. For
example, pure red color is 00FF0000, pure green color is 0000FF00, and pure blue
color is 000000FF. White color is 00FFFFFF, and black color is 00000000.
For the alpha transparency component, a zero value means the color is not
transparent all at. This is equivalent to traditional RGB colors. A non-zero
alpha transparency means the the color is partially transparent. The larger the
alpha transparency, the more transparent the color will be. If a partially
transparent color is used to draw something, the underlying background can still
be seen.
For example, 80FF0000 is a partially transparent red color, while 00FF0000 is a
non-transparent red color.
Note that ChartDirector's ARGB color is web and HTML compatible. For example,
red is FF0000, the same as in HTML. There are many resources on the web that
provide tables in which you can click a color and it will show its HTML color
code. These color codes can be used in ChartDirector.
If alpha transparency is FF (255), the color is totally transparent. That means
the color is invisible. It does not matter what the RGB components are. So in
ChartDirector, only one totally transparent color is used - FF000000. All other
colors of the form FFnnnnnn are reserved to represent palette colors and dynamic
colors, and should not be interpreted as the normal ARGB colors.
The totally transparent color FF000000 is often used in ChartDirector to disable
drawing something. For example, if you want to disable drawing the border of a
rectangle, you can set the border color to totally transparent.
For convenience, ChartDirector pre-defines a constant called Transparent,
which is equivalent to FF000000.
Pattern Color
A pattern color is a dynamic color that changes according to a 2D periodic
pattern. When it is used to fill an area, the area will look like being tiled
with a wallpaper pattern.
Pattern colors are created using
BaseChart.patternColor,
BaseChart.patternColor2,
DrawArea.patternColor and
DrawArea.patternColor2. The patternColor method creates
pattern colors using an array of colors as a bitmap. The patternColor2 method creates
pattern colors by loading the patterns from image files.
These methods return a 32-bit integer acting as a handle to the pattern color.
The handle can be used in any ChartDirector API that expects a color as its
input.
Gradient Color
A gradient color is a color that changes progressively across a direction.
Gradient colors are created using
BaseChart.gradientColor,
BaseChart.gradientColor2,
DrawArea.gradientColor and
DrawArea.gradientColor2. The gradientColor method creates
a 2-point gradient color that changes from color A to color B. The gradientColor2
method creates a multi-point gradient colors that changes from color A to B to C ....
These methods return a 32-bit integer acting as a handle to the gradient color.
The handle can be used in any ChartDirector API that expects a color as its
input.
One common use of multi-point gradient colors is to define colors that have
metallic look and feel. Please refer to
DrawArea.gradientColor2 for details.
Dash Line Colors
A dash line color is a color that switches on and off periodically. When used
to draw a line, the line will appear as a dash line.
Dash line colors are created using
BaseChart.dashLineColor and
DrawArea.dashLineColor. They accept a line color and a dash pattern code as
arguments, and return a 32-bit integer acting as a handle to the dash line
color. The handle can be used in any ChartDirector API that expects a color as
its input.
Palette Colors
Palette colors are colors of the format FFFFnnnn, where the least significant 16
bits (nnnn) are the index to the palette. A palette is simply an array of colors.
For a palette color, the actual color is obtained by looking up the palette using
the index. For example, the color FFFF0001 is the second color in the palette
(first color is index 0).
The colors in the palette can be ARGB colors or "dynamic" colors (pattern, gradient
and dash line colors).
The first eight palette colors have special significance. The first three
palette colors are the background color, default line color, and default text
color of the chart. The 4th to 7th palette colors are reserved for future use.
The 8th color is a special dynamic color that is equal to the data color of the
"current data set".
The 9th color (index = 8) onwards are used for automatic data colors. For example,
in a pie chart, if the sector colors are not specified, ChartDirector will
automatically use the 9th color for the first sector, the 10th color for the second
sector, and so on. Similarly, for a multi-line chart, if the line colors are not
specified, ChartDirector will use the 9th color for the first line, the 10th color for
the second line, and so on.
The ChartDirector API pre-defines several constants to facilitate using palette colors.
Constant | Value | Description |
---|
Palette | FFFF0000 |
The starting point of the palette. The first palette color is (Palette + 0). The nth palette color is
(Palette + n - 1).
|
BackgroundColor | FFFF0000 | The background color.
|
LineColor | FFFF0001 | The default line color.
|
TextColor | FFFF0002 | The default text color.
|
[Reserved] | FFFF0003 - FFFF0006 |
These palette positions are reserved. Future versions of ChartDirector may use these palette positions
for colors that have special significance.
|
SameAsMainColor | FFFF0007 | A dynamic color that is equal to the data color of the
current data set. This color is useful for objects that are associated with data sets. For example,
in a pie chart, if the sector label background color is SameAsMainColor, its color will be the same
as the corresponding sector color.
|
DataColor | FFFF0008 | The starting point for the automatic data color allocation.
|
When a chart is created, it has a default palette. You may modify the palette
using
BaseChart.setColor,
BaseChart.setColors, or
BaseChart.setColors2.
The advantages of using palette colors are that you can change the color schemes
of the chart in one place. ChartDirector comes with several built-in palettes
represented by the following pre-defined constants.
Constant | Description |
defaultPalette |
An array of colors representing the default palette. This palette is designed for drawing charts
on white backgrounds (or lightly colored backgrounds).
|
whiteOnBlackPalette |
An array of colors useful for drawing charts on black backgrounds (or darkly colored backgrounds).
|
transparentPalette |
An array of colors useful drawing charts on white backgrounds (or lightly colored backgrounds).
The data colors in this palette are all semi-transparent.
|
© 2004 Advanced Software Engineering Limited. All rights reserved.