proc legend


Version 2.33 Jun'06

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


Ploticus is hosted at http://ploticus.sourceforge.net
SourceForge Logo


Markup created by unroff 1.0,    June 02, 2006.