Provided by: plplot-doc_5.10.0-0ubuntu5_all bug

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.

                                          February, 2014                        PLLEGEND(3plplot)