## proc legend

Version 2.32
Scripts

Manual page for proc_legend(PL)

proc legend renders a legend using entries that have been previously supplied in plotting procs (usually in an attribute called `legendlabel`), or explicitly defined using proc legendentry one or more times.

Legend entries may be displayed downward or across (`format`).`` Each legend entry is accompanied by a small square of color, a line segment, and/or a symbol as appropriate. Legend entries are presented in the order given, unless `reverseorder` or `specifyorder` is used.``

In ploticus version 2.32 a number of new legend capabilities were added, including multi-column or multi-row capability, wordwrap on legend labels, and backing box and title for the legend.`` Example of new features

See also the gallery legend examples.``

## Attributes

format `down` | `across`

  `down` lists legend entries downward.`` `across` lists legend entries across.`` Previous to 2.32 this was specified as `multirow` (same as `down`), or `singlerow` (same as `across`) and the old notation will be supported indefinately.``
  Example: `format: across`

location x y

  Location for the legend. x will correspond to the beginning of the label (line segments, color squares, etc. will appear to the left of this).`` y will correspond to the top of the legend.``
  Example: `location: min+1.0 max`

## Multi-column or multi-row legends

extent n

  Enables column breaks (or row breaks).`` `extent` is a distance in absolute units that will be used to execute column breaks or row breaks, in order to produce multi-column or multi-row legends.`` New in version 2.32.``
  Example 1: suppose `format` is `down` and `extent` is 1.0. When a legend entry is placed more than 1 inch below the beginning of the legend, the next legend entry (if any) will be placed in a new column.``
  Example 2: suppose `format` is `across` and `extent` is 3.0. When a legend entry is placed more than 3 inches to the right of the beginning, the next legend entry (if any) will be placed on a new row.``
  Usage example: `extent: 2.2`

chunksep n

  Additional separation to add between columns or rows.`` Absolute units.``

## Appearance details

separation n

  Amount of additional separation to add between legend entries. Absolute units.``

sep (discontinued)

  As of version 2.32 `sep` no longer does anything; it has been superseded by the 2.32 improvements and the new `separation` attribute.``

textdetails textdetails

  Details regarding the text rendering of the legend labels.``

wraplen nchars

  If specified, all legend labels will be wordwrapped to a maximum length of nchars characters. Useful when working with longer legend labels.`` Note: labels can contain explicit line breaks using the `\n` construct; `wraplen` takes these into account. New in 2.32.``

seglen n

  If specified, controls the length of line segment samples.`` Absolute units.``

nlinesym `1 | 2 | 0`

  Allows control over the number of symbols per sample, with line+symbol samples.`` New in 2.32.``

swatchsize n

  If specified, controls the size of color sample square.`` n is the length of one side in absolute units.``

outlinecolors `yes` | `no`

  If `yes`, color samples will be outlined.`` Normally they are not, except for white.``

colortext `yes` | `no`

  If `yes`, entry text inherits the color of the sample. Normally it does not.`` Example.``

## Controlling the order of legend entries

specifyorder multiline-text

  If specified, allows the order of legend entries to be controlled explicitly. Also allows entries to selected/omitted.`` (Normally, entries are rendered in the order that they were added and all entries are rendered.) multilinetext should have one line for each entry to appear in the legend.`` Each line will be compared against all defined legend labels. Upon a match, that entry will be rendered.`` The comparison is case-insensitive.`` Only the first few characters (enough to uniquely match) need be given in the `specifyorder` attribute.``
  Example:

      specifyorder:
         Jean
         Jan
         Joan
         John
         Juan

  ``Other Gallery examples: timeline2 and km2

reverseorder `yes` | `no`

  If `yes`, entries are rendered from last to first.``

## Backing box / frame / title

frame linedetails `| no | yes | bevel`

  If specified, a frame is drawn around the legend, using the given linedetails. `bevel` can be specified to get a bevel frame.`` New in 2.32.``

backcolor color

  If specified, a colored backing box will be shown behind the legend.`` New in 2.32.``

boxmargin h ...or... x1 y1 x2 y2

  Allows control over the amount that the frame / backing box exceeds the actual size of the legend. Default is 0.08 inches on all four sides.`` Absolute units.`` New in 2.32.``
  If one value is given it is used on all four sides.`` If four values are given (left, bottom, right, top) the margin can be controlled individually for each of the four sides (sometimes useful when ploticus takes a bad guess with variable-spaced fonts).``
  Example: `boxmargin: 0.12`
  Example: `boxmargin: 0.08 0.1 0.1 0.04`

title text

  A title for the legend. Text must be specified in one line but can contain the `\n` construct to indicate displayed line breaks. New in 2.32

titledetails textdetails

  Details regarding the text rendering of the title.``

## Specialized uses

reset

  If specified, no legend will be rendered and the internal list of legend entries will be cleared. This may be useful when a number of cloned plots (with legendlabels) are being done, but only one actual legend is desired. Example:

          #proc legend
            reset: yes

noclear `yes` | `no`

  If `yes`, the defined legend entries list is not cleared.`` Normally this list is cleared once the legend has been rendered.`` This was a crude way to create multi-column legends; this attribute may not be useful with versions 2.32+ since they support more flexible legend rendering.``
  Example: this is used in Gallery example propbars1
  data display engine
  Copyright Steve Grubb

Markup created by unroff 1.0, `` `` August 23, 2005.