Provided by: plplot-doc_5.10.0+dfsg2-0.1ubuntu2_all 
NAME
plcolorbar - Plot color bar for image, shade or gradient plots
SYNOPSIS
plcolorbar(p_colorbar_width, p_colorbar_height, opt, position, x, y, x_length, y_length,
bg_color, bb_color, bb_style, low_cap_color, high_cap_color, cont_color, cont_width,
n_labels, label_opts, labels, naxes, axis_opts, ticks, sub_ticks, n_values, values)
DESCRIPTION
Routine for creating a continuous color bar for image, shade, or gradient plots. (See
pllegend(3plplot) for similar functionality for creating legends with discrete elements).
The arguments of plcolorbar provide control over the location and size of the color bar as
well as the location and characteristics of the elements (most of which are optional)
within that color bar. The resulting color bar is clipped at the boundaries of the
current subpage. (N.B. the adopted coordinate system used for some of the parameters is
defined in the documentation of the position parameter.)
Redacted form: plcolorbar(p_colorbar_width, p_colorbar_height, opt, position, x, y,
x_length, y_length, bg_color, bb_color, bb_style, low_cap_color, high_cap_color,
cont_color, cont_width, label_opts, labels, axis_opts, ticks, sub_ticks, values)
This function is used in examples 16 and 33.
ARGUMENTS
p_colorbar_width (PLFLT *, output)
Pointer to a location which contains (after the call) the labelled and decorated
color bar width in adopted coordinates.
p_colorbar_height (PLFLT *, output)
Pointer to a location which contains (after the call) the labelled and decorated
color bar height in adopted coordinates.
opt (PLINT, input)
opt contains bits controlling the overall color bar. The orientation (direction of
the maximum value) of the color bar is specified with PL_ORIENT_RIGHT,
PL_ORIENT_TOP, PL_ORIENT_LEFT, or PL_ORIENT_BOTTOM. If none of these bits are
specified, the default orientation is toward the top if the colorbar is placed on
the left or right of the viewport or toward the right if the colorbar is placed on
the top or bottom of the viewport. If the PL_COLORBAR_BACKGROUND bit is set, plot a
(semi-transparent) background for the color bar. If the PL_COLORBAR_BOUNDING_BOX
bit is set, plot a bounding box for the color bar. The type of color bar must be
specified with one of PL_COLORBAR_IMAGE, PL_COLORBAR_SHADE, or
PL_COLORBAR_GRADIENT. If more than one of those bits is set only the first one in
the above list is honored. The position of the (optional) label/title can be
specified with PL_LABEL_RIGHT, PL_LABEL_TOP, PL_LABEL_LEFT, or PL_LABEL_BOTTOM. If
no label position bit is set then no label will be drawn. If more than one of this
list of bits is specified, only the first one on the list is honored. End-caps for
the color bar can added with PL_COLORBAR_CAP_LOW and PL_COLORBAR_CAP_HIGH. If a
particular color bar cap option is not specified then no cap will be drawn for that
end. As a special case for PL_COLORBAR_SHADE, the option PL_COLORBAR_SHADE_LABEL
can be specified. If this option is provided then any tick marks and tick labels
will be placed at the breaks between shaded segments. TODO: This should be expanded
to support custom placement of tick marks and tick labels at custom value locations
for any color bar type.
position (PLINT, input)
position contains bits which control the overall position of the color bar and the
definition of the adopted coordinates used for positions just like what is done for
the position argument for pllegend(3plplot). However, note that the defaults for
the position bits (see below) are different than the pllegend(3plplot) case. The
combination of the PL_POSITION_LEFT, PL_POSITION_RIGHT, PL_POSITION_TOP,
PL_POSITION_BOTTOM, PL_POSITION_INSIDE, and PL_POSITION_OUTSIDE bits specifies one
of the 16 possible standard positions (the 4 corners and centers of the 4 sides for
both the inside and outside cases) of the color bar relative to the adopted
coordinate system. The corner positions are specified by the appropriate
combination of two of the PL_POSITION_LEFT, PL_POSITION_RIGHT, PL_POSITION_TOP, and
PL_POSITION_BOTTOM bits while the sides are specified by a single value of one of
those bits. The adopted coordinates are normalized viewport coordinates if the
PL_POSITION_VIEWPORT bit is set or normalized subpage coordinates if the
PL_POSITION_SUBPAGE bit is set. Default position bits: If none of PL_POSITION_LEFT,
PL_POSITION_RIGHT, PL_POSITION_TOP, or PL_POSITION_BOTTOM are set, then use
PL_POSITION_RIGHT. If neither of PL_POSITION_INSIDE or PL_POSITION_OUTSIDE is set,
use PL_POSITION_OUTSIDE. If neither of PL_POSITION_VIEWPORT or PL_POSITION_SUBPAGE
is set, use PL_POSITION_VIEWPORT.
x (PLFLT, input)
X offset of the color bar position in adopted coordinates from the specified
standard position of the color bar. For positive x, the direction of motion away
from the standard position is inward/outward from the standard corner positions or
standard left or right positions if the PL_POSITION_INSIDE/PL_POSITION_OUTSIDE bit
is set in position. For the standard top or bottom positions, the direction of
motion is toward positive X.
y (PLFLT, input)
Y offset of the color bar position in adopted coordinates from the specified
standard position of the color bar. For positive y, the direction of motion away
from the standard position is inward/outward from the standard corner positions or
standard top or bottom positions if the PL_POSITION_INSIDE/PL_POSITION_OUTSIDE bit
is set in position. For the standard left or right positions, the direction of
motion is toward positive Y.
x_length (PLFLT, input)
Length of the body of the color bar in the X direction in adopted coordinates.
y_length (PLFLT, input)
Length of the body of the color bar in the Y direction in adopted coordinates.
bg_color (PLINT, input)
The cmap0 color of the background for the color bar (PL_COLORBAR_BACKGROUND).
bb_color (PLINT, input)
The cmap0 color of the bounding-box line for the color bar
(PL_COLORBAR_BOUNDING_BOX).
bb_style (PLINT, input)
The pllsty(3plplot) style number for the bounding-box line for the color bar
(PL_COLORBAR_BACKGROUND).
low_cap_color (PLFLT, input)
The cmap1 color of the low-end color bar cap, if it is drawn (PL_COLORBAR_CAP_LOW).
high_cap_color (PLFLT, input)
The cmap1 color of the high-end color bar cap, if it is drawn
(PL_COLORBAR_CAP_HIGH).
cont_color (PLINT, input)
The cmap0 contour color for PL_COLORBAR_SHADE plots. This is passed directly to
plshades(3plplot), so it will be interpreted according to the design of
plshades(3plplot).
cont_width (PLFLT, input)
Contour width for PL_COLORBAR_SHADE plots. This is passed directly to
plshades(3plplot), so it will be interpreted according to the design of
plshades(3plplot).
n_labels (PLINT, input)
Number of labels to place around the color bar.
label_opts (const PLINT *, input)
Options for each of n_labels labels.
labels (const char * const *, input)
n_labels text labels for the color bar. No label is drawn if no label position is
specified with one of the PL_COLORBAR_LABEL_RIGHT, PL_COLORBAR_LABEL_TOP,
PL_COLORBAR_LABEL_LEFT, or PL_COLORBAR_LABEL_BOTTOM bits in the corresponding
label_opts field.
n_axes (PLINT, input)
Number of axis definitions provided. This value must be greater than 0. It is
typically 1 (numerical axis labels are provided for one of the long edges of the
color bar), but it can be larger if multiple numerical axis labels for the long
edges of the color bar are desired.
axis_opts (const char * const *, input)
An array of n_axes axis options (interpreted as for plbox(3plplot)) for the color
bar's axis definitions.
ticks (const PLFLT *, input)
An array of n_axes values of the spacing of the major tick marks (interpreted as
for plbox(3plplot)) for the color bar's axis definitions.
sub_ticks (const PLINT *, input)
An array of n_axes values of the number of subticks (interpreted as for
plbox(3plplot)) for the color bar's axis definitions.
n_values (const PLINT *, input)
An array containing the number of elements in each of the n_axes rows of the two-
dimensional values array.
values (const PLFLT * const *, input)
A two-dimensional array containing the numeric values for the data range
represented by the color bar. For a row index of i_axis (where 0 < i_axis <
n_axes), the number of elements in the row is specified by n_values[i_axis]. For
PL_COLORBAR_IMAGE and PL_COLORBAR_GRADIENT the number of elements is 2, and the
corresponding row elements of the values array are the minimum and maximum value
represented by the colorbar. For PL_COLORBAR_SHADE, the number and values of the
elements of a row of the values array is interpreted the same as the nlevel and
clevel arguments of plshades(3plplot).
AUTHORS
Many developers (who are credited at http://plplot.sourceforge.net/credits.php) have
contributed to PLplot over its long history.
SEE ALSO
PLplot documentation at http://plplot.sourceforge.net/documentation.php.
February, 2016 PLCOLORBAR(3plplot)