Set the text color used in the group spreadsheet using values in the spreadsheet or in a different series.
Syntax
group_name.settextcolor(spec) fill_color_args
where the required spec is one of the following:
type = arg | Type of fill coloring for spreadsheet cells: “single” (single color), “posneg” (positive-negative single threshold), “range” (single range coloring), “hilo” (high-low-median), “custom” (custom coloring). |
s = arg | Colormap source: “none” (do not use a colormap and therefore do not color) or “series” (use the same colormap used by the individual series. |
The first form specifies a colormap for all of the series in the group. The second form, uses individual colormaps obtained from the individual series.
General Arguments
To specify the series or expression whose values will determine the background color:
• mapser(spec)
where spec is a series name or expression.
To specify the minimum and maximum values where the coloring begins and ends:
• min(color_arg)
• max(color_arg)
To set the missing value (NA) background color:
• naclr(color_arg)
where
color_arg is described below in
“Color definitions”. If omitted, the color defaults to “black”.
Type-specific Arguments
There are optional type-specific arguments that correspond to each of the type choices:
Single color
To set the single text color:
clr(color_arg)
where
color_arg is described below in
“Color definitions”. If omitted, the color defaults to “black”.
Positive-negative single threshold
You may set the color for both the non-negative (posclr) and the negative (negclr) values
posclr(color_arg)
negclr(color_arg)
where
color_arg is described below in
“Color definitions”. If omitted, the non-negative color defaults to “black” and the negative color defaults to “red”.
Single range
To specify the range, you must specify the range endpoints:
range(lower_val, upper_val[, range_def)
where range_def specifies the range endpoints:
cright | closed on the right only |
cboth | closed on both sides |
cleft | closed on the left only |
oboth | open on both sides |
By default, the range will be open on the lower and closed on the upper threshold limits.
You should provide a color specification for the inside range color (inclr) and outside range color (outclr):
inclr(color_arg)
outclr(color_arg)
where
color_arg is described below in
“Color definitions”. If omitted, the interior color defaults to light-red, and the exterior defaults to white.
High-Low-Median
When “type=hilo” you may specify the high, low, and median coloring values:
highclr(color_arg)
lowclr(color_arg)
medianclr(color_arg)
where
color_arg is described below in
“Color definitions”. If omitted, the colors default to light-red.
Custom
When “type=custom” you may specify custom coloring options.
You may optionally set a base text color, and then add one or more custom threshold or range color specifications. Multiple threshold and range specifications will layer, with the first applied first, followed by the second, and so on.
Custom Base Color
To set the base color (optional):
clr(color_arg)
as described below in
“Color definitions”. If omitted, the color defaults to “white”.
Custom Threshold
To add a threshold specification:
thresh(limit(threshold_value, threshold_spec), lowclr(below_arg), highclr(above_arg), threshold_name])
where threshold_spec is one of
cright | closed on the right |
cleft | closed on the left |
and the below_arg and above_arg are one of
color_arg | solid color specification |
@grad(color_arg) | gradient using color specification |
@trans | transparent |
and
color_arg are as described below in
“Color definitions”. If omitted, the color defaults to “white”.
The optional threshold_name argument may be used to attach a name to the corresponding definition.
Custom Range
To add a range specification:
range(limit(low_value, high_value, range_spec), inclr(inside_arg), outclr(outside_arg)[, range_name])
where range_spec is one of
cright | closed on the right only |
cboth | closed on both sides |
cleft | closed on the left only |
oboth | open on both sides |
inside_arg is one of
color_arg | solid color specification |
@grad(color_arg1, color_arg2) | gradient using color specification, where color_arg1 and color_arg2 are the low and high colors, respectively. |
@trans | transparent |
outside_arg is one of
color_arg | solid color specification |
@grad(color_arg) | gradient using color specification |
@trans | transparent |
color_arg1 and
color_arg2 are as described below in
“Color definitions”.
The optional range_name argument may be used to attach a name to the corresponding definition.
Color definitions
color_arg specifies the color to be employed in the arguments above. The color may be specified using predefined color names, by specifying the individual red-green-blue (RGB) components using the special “@RGB” function, or by specifying the individual red-green-blue (RGB) components in hexadecimal using the special “@HEX” function.
The predefined colors are given by the keywords (with their RGB and HEX equivalents):
blue | @rgb(0, 0, 255) | @hex(0000ff) |
red | @rgb(255, 0, 0) | @hex(ff0000) |
ltred | @rgb(255, 168, 168) | @hex(ffa8a8) |
green | @rgb(0, 128, 0) | @hex(008000) |
black | @rgb(0, 0, 0) | @hex(000000) |
white | @rgb(255, 255, 255) | @hex(ffffff) |
purple | @rgb(128, 0, 128) | @hex(800080) |
orange | @rgb(255, 128, 0) | @hex(ff8000) |
yellow | @rgb(255, 255, 0) | @hex(ffff00) |
gray | @rgb(128, 128, 128) | @hex(808080) |
ltgray | @rgb(192, 192, 192) | @hex(c0c0c0) |
Examples
To set a gray text color for all cells in the spreadsheet, you may use:
grp1.settextcolor(type=single) clr(gray)
To set a text color for negative values, you may use
grp1.settextcolor(type=posneg) mapser(ser1)
which sets the text color to black for non-negative values and red for negative values of SER1.
Similarly,
grp1.settextcolor(type=posneg) mapser(ser1) posclr(@rgb(10, 20, 30)) negclr(purple)
sets the text color to @rgb(10, 20, 30) for non-negative values and purple for negative values of SER1.
Range coloring may be specified using the “type=range” option. The command
grp1.settextcolor(type=range) mapser(ser1) clr(ltgray) range(10, 20, cleft) inclr(@rgb(128, 0, 128)) outclr(ltred) naclr(green)
sets the text to @rgb(128, 0, 128) for values between 10 and 20, light-red to values outside of the range 10 to 20, and green, for missing values.
Custom coloring allows you to construct more complex text coloring:
grp1.settextcolor(type=custom) mapser(ser1) clr(@rgb(10, 0, 0)) range(limit(-10, 10, oboth), inclr(green), outclr(white))) thresh(limit(-1, oleft), highclr(grey), lowclr(@trans))
Cross-reference