pllegend
( | p_legend_width, |
p_legend_height, | |
opt, | |
position, | |
x, | |
y, | |
plot_width, | |
bg_color, | |
bb_color, | |
bb_style, | |
nrow, | |
ncolumn, | |
nlegend, | |
opt_array, | |
text_offset, | |
text_scale, | |
text_spacing, | |
test_justification, | |
text_colors, | |
text, | |
box_colors, | |
box_patterns, | |
box_scales, | |
box_line_widths, | |
line_colors, | |
line_styles, | |
line_widths, | |
symbol_colors, | |
symbol_scales, | |
symbol_numbers, | |
symbols) ; |
Routine for creating a discrete plot legend with a plotted
filled box, line, and/or line of symbols for each annotated legend
entry. (See plcolorbar
for similar functionality for creating
continuous color bars.) The arguments of pllegend provide control
over the location and size of the legend as well as the location and
characteristics of the elements (most of which are optional) within
that legend. The resulting legend 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
parameter.)
position
p_legend_width
(PLFLT_NC_SCALAR
, output)
Returned value of the
legend width in adopted coordinates. This quantity is
calculated from
,
plot_width
,
text_offset
(possibly modified
inside the routine depending on
ncolumn
and
nlegend
), and the length
(calculated internally) of the longest text string.
nrow
p_legend_height
(PLFLT_NC_SCALAR
, output)
Returned value of the
legend height in adopted coordinates. This quantity is
calculated from
,
text_scale
, and
text_spacing
(possibly modified
inside the routine depending on
nrow
and
nlegend
).
nrow
opt
(PLINT
, input)
contains
bits controlling the overall legend. If the
opt
PL_LEGEND_TEXT_LEFT
bit is set, put the text area
on the left of the legend and the plotted area on the
right. Otherwise, put the text area on the right of the legend and the
plotted area on the left. If the
PL_LEGEND_BACKGROUND
bit is set, plot a
(semitransparent) background for the legend. If the
PL_LEGEND_BOUNDING_BOX
bit is set, plot a bounding
box for the legend. If the PL_LEGEND_ROW_MAJOR
bit
is set and (both of the possibly internally transformed)
> 1 and
nrow
> 1, then plot
the resulting array of legend entries in row-major order.
Otherwise, plot the legend entries in column-major order.
ncolumn
position
(PLINT
, input)
contains bits which control the overall position of the legend and the
definition of the adopted coordinates used for positions just like
what is done for the position argument for position
plcolorbar
. However,
note that the defaults for the position bits (see below) are
different than the plcolorbar
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 legend 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 the
combination of PL_POSITION_RIGHT
and
PL_POSITION_TOP
. If neither of
PL_POSITION_INSIDE
or
PL_POSITION_OUTSIDE
is set, use
PL_POSITION_INSIDE
. If neither of
PL_POSITION_VIEWPORT
or
PL_POSITION_SUBPAGE
is set, use
PL_POSITION_VIEWPORT
.
x
(PLFLT
, input)
X offset of the legend position in adopted coordinates
from the specified standard position of the legend. 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
. For
the standard top or bottom positions, the direction of motion is
toward positive X.
position
y
(PLFLT
, input)
Y offset of the legend position in adopted coordinates
from the specified standard position of the legend. 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
.
For the standard left or right positions, the
direction of motion is toward positive Y.
position
plot_width
(PLFLT
, input)
Horizontal width in adopted coordinates of the plot area (where the colored boxes, lines, and/or lines of symbols are drawn) of the legend.
bg_color
(PLINT
, input)
The cmap0 color of the background for the legend
(PL_LEGEND_BACKGROUND
).
bb_color
(PLINT
, input)
The cmap0 color of the bounding-box line for the legend
(PL_LEGEND_BOUNDING_BOX
).
bb_style
(PLINT
, input)
The pllsty style number for the bounding-box line for the legend
(PL_LEGEND_BACKGROUND
).
nrow
(PLINT
, input)
The number of rows in the matrix used to render the
nlegend
legend entries. For internal
transformations of nrow
, see further remarks
under nlegend
.
ncolumn
(PLINT
, input)
The number of columns in the matrix used to render the
nlegend
legend entries. For internal
transformations of ncolumn
, see further remarks
under nlegend
.
nlegend
(PLINT
, input)
Number of legend entries. The above
nrow
and ncolumn
values
are transformed internally to be consistent with
nlegend
. If either nrow
or ncolumn
is non-positive it is replaced by
1. If the resulting product of nrow
and
ncolumn
is less than
nlegend
, the smaller of the two (or
nrow
, if nrow
==
ncolumn
) is increased so the product is >=
nlegend
. Thus, for example, the common
nrow
= 0, ncolumn
= 0
case is transformed internally to nrow
=
nlegend
, ncolumn
= 1;
i.e., the usual case of a legend rendered as a single column.
opt_array
(PLINT_VECTOR
, input)
A vector of nlegend
values of options to control each
individual plotted area corresponding to a legend entry. If the
PL_LEGEND_NONE
bit is set, then nothing is
plotted in the plotted area. If the
PL_LEGEND_COLOR_BOX
,
PL_LEGEND_LINE
, and/or
PL_LEGEND_SYMBOL
bits are set, the area
corresponding to a legend entry is plotted with a colored box; a line;
and/or a line of symbols.
text_offset
(PLFLT
, input)
Offset of the text area from the plot area in units of character width.
text_scale
(PLFLT
, input)
Character height scale for text annotations.
text_spacing
(PLFLT
, input)
Vertical spacing in units of the character height from one legend entry to the next.
text_justification
(PLFLT
, input)
Justification parameter used for text justification. The most common values of text_justification are 0., 0.5, or 1. corresponding to a text that is left justified, centred, or right justified within the text area, but other values are allowed as well.
text_colors
(PLINT_VECTOR
, input)
A vector containing nlegend
cmap0 text colors.
text
(PLCHAR_MATRIX
, input)
A vector of nlegend
UTF-8 character strings containing
the legend annotations.
box_colors
(PLINT_VECTOR
, input)
A vector containing nlegend
cmap0 colors for the discrete colored boxes
(PL_LEGEND_COLOR_BOX
).
box_patterns
(PLINT_VECTOR
, input)
A vector containing nlegend
patterns (plpsty indices) for the discrete colored
boxes (PL_LEGEND_COLOR_BOX
).
box_scales
(PLFLT_VECTOR
, input)
A vector containing nlegend
scales (units of fraction of character height) for
the height of the discrete colored boxes
(PL_LEGEND_COLOR_BOX
).
box_line_widths
(PLFLT_VECTOR
, input)
A vector containing nlegend
line widths for the patterns specified by
box_patterns (PL_LEGEND_COLOR_BOX
).
line_colors
(PLINT_VECTOR
, input)
A vector containing nlegend
cmap0 line colors
(PL_LEGEND_LINE
).
line_styles
(PLINT_VECTOR
, input)
A vector containing nlegend
line styles (plsty indices)
(PL_LEGEND_LINE
).
line_widths
(PLFLT_VECTOR
, input)
A vector containing nlegend
line widths
(PL_LEGEND_LINE
).
symbol_colors
(PLINT_VECTOR
, input)
A vector containing nlegend
cmap0 symbol colors
(PL_LEGEND_SYMBOL
).
symbol_scales
(PLFLT_VECTOR
, input)
A vector containing nlegend
scale values for the symbol height
(PL_LEGEND_SYMBOL
).
symbol_numbers
(PLINT_VECTOR
, input)
A vector containing nlegend
numbers of symbols to be drawn across the width of
the plotted area (PL_LEGEND_SYMBOL
).
symbols
(PLCHAR_MATRIX
, input)
A vector of nlegend
UTF-8 character strings containing
the legend symbols.
(PL_LEGEND_SYMBOL
).
Redacted form: pllegend(p_legend_width, p_legend_height,
opt, position, x, y, plot_width,
bg_color, bb_color, bb_style,
nrow, ncolumn,
opt_array,
text_offset, text_scale, text_spacing, test_justification,
text_colors, text,
box_colors, box_patterns,
box_scales, box_line_widths,
line_colors, line_styles, line_widths,
symbol_colors, symbol_scales,
symbol_numbers, symbols)
This function is used in examples 4, 26, and 33.