Ploticus > Scripts >
proc legend

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.

There's multi-column / multi-row capability, wordwrap on legend labels, and backing box and title for the legend. Examples of these features

See also the gallery legend examples.


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

Appearance details

separation     n

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

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
specifyorder1 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.) specifyorder is multiline text and should have one line for each entry to appear in the legend. specifyorder1 is single line text, entries should be separated by \\n. Each entry will be compared against all defined legend labels. Upon a match, that legend label will be rendered. The comparison is case-insensitive. Only the first few characters (enough to uniquely match) need be given.
    Example: specifyorder1: Jean\\nJan\\nJoan\\nJohn\\nJuan
    Another example:

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.


Legend entries can be added to the image map so that when a user clicks on a legend entry they open a new web page. To do this, embed a URL into the legendlabel attribute of your plotting proc (or if you are using proc legendentry embed it into the label attribute). Use this format: url:url label
The combined length of the url and the label should not exceed 255 characters.
Mouseover labels are not supported for legend entries.
See this example: clickmap_leg

Specialized uses


    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


Ploticus 2.42 ... May 2013 Terms of use /