
pllegend: Plot legend using discretely annotated filled boxes, lines, and/or lines of symbols 

DESCRIPTION:

    This function is used in examples 4, 26, and 33. 

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)

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. 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 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). 
