NAME¶
pllegend - Plot legend using discretely annotated filled boxes, lines,
and/or lines of symbols
SYNOPSIS¶
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)
DESCRIPTION¶
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(3plplot) 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
position parameter.)
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.
ARGUMENTS¶
- p_legend_width (PLFLT *, output)
- Pointer to a location which contains (after the call) the legend width in
adopted coordinates. This quantity is calculated from plot_width,
text_offset, ncolumn (possibly modified inside the routine
depending on nlegend and nrow), and the length (calculated
internally) of the longest text string.
- p_legend_height (PLFLT *, output)
- Pointer to a location which contains (after the call) the legend height in
adopted coordinates. This quantity is calculated from text_scale,
text_spacing, and nrow (possibly modified inside the routine
depending on nlegend and nrow).
- opt (PLINT, input)
- opt contains bits controlling the overall legend. If the
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 (semi-transparent) 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) nrow > 1 and ncolumn
> 1, then plot the resulting array of legend entries in row-major
order. Otherwise, plot the legend entries in column-major order.
- position (PLINT, input)
- position 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
plcolorbar(3plplot). However, note that the defaults for the
position bits (see below) are different than the
plcolorbar(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 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 position. For
the standard top or bottom positions, the direction of motion is toward
positive X.
- 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 position. For
the standard left or right positions, the direction of motion is toward
positive Y.
- 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 cmap0 index of the background color for the legend
(PL_LEGEND_BACKGROUND).
- ncolumn (PLINT, input)
- The cmap0 index of the background color for the legend
(PL_LEGEND_BACKGROUND).
- nlegend (PLINT, input)
- Number of legend entries. N.B. The total vertical height of the legend in
adopted coordinates is calculated internally from nlegend,
text_scale (see below), and text_spacing (see below).
- opt_array (const PLINT *, input)
- Array 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.
N.B. The total horizontal width of the legend in adopted coordinates is
calculated internally from plot_width (see above),
text_offset, and length (calculated internally) of the longest text
string.
- text_scale (PLFLT, input)
- Character height scale for text annotations. N.B. The total vertical
height of the legend in adopted coordinates is calculated internally from
nlegend (see above), text_scale, and text_spacing
(see below).
- text_spacing (PLFLT, input)
- Vertical spacing in units of the character height from one legend entry to
the next. N.B. The total vertical height of the legend in adopted
coordinates is calculated internally from nlegend (see above),
text_scale (see above), and text_spacing.
- 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 (const PLINT *, input)
- Array of nlegend cmap0 text colors.
- text (const char * const *, input)
- Array of nlegend text string annotations.
- box_colors (const PLINT *, input)
- Array of nlegend cmap0 colors for the discrete colored boxes
(PL_LEGEND_COLOR_BOX).
- box_patterns (const PLINT *, input)
- Array of nlegend patterns (plpsty indices) for the discrete colored boxes
( PL_LEGEND_COLOR_BOX).
- box_scales (const PLFLT *, input)
- Array of nlegend scales (units of fraction of character height) for the
height of the discrete colored boxes ( PL_LEGEND_COLOR_BOX).
- box_line_widths (const PLFLT *, input)
- Array of nlegend line widths for the patterns specified by box_patterns
(PL_LEGEND_COLOR_BOX).
- line_colors (const PLINT *, input)
- Array of nlegend cmap0 line colors (PL_LEGEND_LINE).
- line_styles (const PLINT *, input)
- Array of nlegend line styles (plsty indices) (PL_LEGEND_LINE).
- line_widths (const PLFLT *, input)
- Array of nlegend line widths (PL_LEGEND_LINE).
- symbol_colors (const PLINT *, input)
- Array of nlegend cmap0 symbol colors (PL_LEGEND_SYMBOL).
- symbol_scales (const PLFLT *, input)
- Array of nlegend scale values for the symbol height
(PL_LEGEND_SYMBOL).
- symbol_numbers (const PLINT *, input)
- Array of nlegend numbers of symbols to be drawn across the width of the
plotted area ( PL_LEGEND_SYMBOL).
- symbols (const char * const *, input)
- Array of nlegend symbols (plpoin indices) (PL_LEGEND_SYMBOL).
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.