pllegend: Create a discrete annotated legend using boxes, lines, and/or lines of symbols

pllegend (opt, x, y, plot_width, bg_color, nlegend, opt_array, text_offset, text_scale, text_spacing, test_justification, text_colors, text, box_colors, box_patterns, box_scales, line_colors, line_styles, line_widths, symbol_colors, symbol_scales, symbol_numbers, symbols);

(N.B. This is an experimental API that may be subject to further change as we gain more experience with it.) Routine for creating a discrete plot legend with a plotted box, line, and/or line of symbols for each annotated legend entry. The arguments of pllegend provide control over the location and size of the legend within the current subpage 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

opt (PLINT, input)

opt contains bits controlling the overall legend. If the PL_LEGEND_BACKGROUND bit is set, plot a (semi-transparent) background for the 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.

x (PLFLT, input)

Normalized sub-page X position of the upper-left corner of the legend.

y (PLFLT, input)

Normalized sub-page Y position of the upper-left corner of the legend.

plot_width (PLFLT, input)

Horizontal width in normalized subpage units of the plot area (where the rectangular boxes, lines, and/or lines of symbols are drawn) of the legend. N.B. The total horizontal width of the legend in normalized subpage coordinates is calculated internally from plot_width, text_offset (see below), and length (calculated internally) of the longest text string.

bg_color (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 normalized subpage 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 normalized subpage 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 normalized subpage 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 normalized subpage 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 text colors (cmap0 indices).

text (const char **, input)

Array of nlegend text string annotations.

box_colors (const PLINT *, input)

Array of nlegend colors (cmap0 indices) 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).

line_colors (const PLINT *, input)

Array of nlegend line colors (cmap0 indices) (PL_LEGEND_LINE).

line_styles (const PLINT *, input)

Array of nlegend line styles (plsty indices) (PL_LEGEND_LINE).

line_widths (const PLINT *, input)

Array of nlegend line widths (PL_LEGEND_LINE).

symbol_colors (const PLINT *, input)

Array of nlegend symbol colors (cmap0 indices) (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 PLINT *, input)

Array of nlegend symbols (plpoin indices) (PL_LEGEND_SYMBOL).

Redacted form: pllegend(opt, x, y, plot_width, bg_color, opt_array, text_offset, text_scale, text_spacing, test_justification, text_colors, text, box_colors, box_patterns, box_scales, line_colors, line_styles, line_widths, symbol_colors, symbol_scales, symbol_numbers, symbols)

This function is used in examples 4 and 26.