Search
Ploticus >
Scripts >
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.
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
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
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
specifyorder:
Jean
Jan
Joan
John
Juan
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.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.
Clickmap
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
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
|
