<html>
<head>
<!-- This file has been generated by unroff 1.0, 03/11/09 12:56:16. -->
<!-- Do not edit! -->
<STYLE TYPE="text/css">
<!--
A:link{text-decoration:none}
A:visited{text-decoration:none}
A:active{text-decoration:none}
OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }
H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>ploticus: proc legend</title>
<body bgcolor=D0D0EE vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550><tr>
<td>
<table cellpadding=2 width=550><tr>
<td><br><h2>proc legend</h2></td>
<td align=right>
<small>
<a href="../doc/welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
Version 2.41 Mar2009
</small><br><a href="../doc/scripthome.html">Scripts</a>
<td></tr></table>
</td></tr>
<td>
<br>
<br>
<title>Manual page for proc_legend(PL)</title>
</head>
<body>
<center>
<img src="../gallery/legend0.gif">
</center>
<b>proc legend</b> renders a legend
using entries that have been previously supplied in
plotting procs (usually in an attribute called <tt>legendlabel</tt>), or
explicitly defined using
<a href="legendentry.html">
proc legendentry
</a>
one or more times.
<p>
Legend entries may be displayed downward or across (<tt>format</tt>).<tt> </tt>
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 <tt>reverseorder</tt> or <tt>specifyorder</tt> is used.<tt> </tt>
<p>
<img src="../gallery/gif/new.gif">
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.<tt> </tt>
<a href="../gallery/legends232.htm">
Example of new features
</a>
<p>
See also the
<a href="../gallery/gall.legend.html">
gallery legend examples.<tt> </tt>
</a>
<br><br><br>
<h2>Attributes</h2>
<p>
<b>format</b>
<tt>down</tt> | <tt>across</tt>
<dl>
<dt> <dd>
<tt>down</tt> lists legend entries downward.<tt> </tt>
<tt>across</tt> lists legend entries across.<tt> </tt>
Previous to 2.32 this was specified as <tt>multirow</tt> (same as <tt>down</tt>),
or <tt>singlerow</tt> (same as <tt>across</tt>) and the old notation will be supported indefinately.<tt> </tt>
<br>
Example: <tt>format: across</tt>
<br><br>
</dl>
<p>
<b>location</b>
<a href="attributetypes.html#xy">
x y
</a>
<dl>
<dt> <dd>
Location for the legend.
<i>x</i> will correspond to the beginning of the label (line segments,
color squares, etc. will appear to the left of this).<tt> </tt>
<i>y</i> will correspond to the top of the legend.<tt> </tt>
<br>
Example: <tt>location: min+1.0 max</tt>
<br><br><br>
</dl>
<h2>Multi-column or multi-row legends</h2>
<p>
<b>extent</b>
<i>n</i>
<dl>
<dt> <dd>
Enables column breaks (or row breaks).<tt> </tt>
<tt>extent</tt> is a distance in
<a href="attributetypes.html#positionunits">
absolute units
</a>
that will be used to execute column breaks or row breaks, in order to produce
multi-column or multi-row legends.<tt> </tt>
New in version 2.32.<tt> </tt>
<dt> <dd>
Example 1: suppose <tt>format</tt> is <tt>down</tt> and <tt>extent</tt> 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.<tt> </tt>
<dt> <dd>
Example 2: suppose <tt>format</tt> is <tt>across</tt> and <tt>extent</tt> 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.<tt> </tt>
<dt> <dd>
Usage example: <tt>extent: 2.2</tt>
<br><br>
</dl>
<p>
<b>chunksep</b>
<i>n</i>
<dl>
<dt> <dd>
Additional separation to add between columns or rows.<tt> </tt>
<a href="attributetypes.html#positionunits">
Absolute units.<tt> </tt>
</a>
<br><br><br>
</dl>
<h2>Appearance details</h2>
<p>
<b>separation</b>
<i>n</i>
<dl>
<dt> <dd>
Amount of additional separation to add between legend entries.
<a href="attributetypes.html#positionunits">
Absolute units.<tt> </tt>
</a>
<br><br>
</dl>
<p>
<b>sep</b>
(discontinued)
<dl>
<dt> <dd>
As of version 2.32 <tt>sep</tt> no longer does anything; it has been superseded by the 2.32 improvements
and the new <tt>separation</tt> attribute.<tt> </tt>
<br><br>
</dl>
<p>
<b>textdetails</b>
<a href="textdetails.html">
textdetails
</a>
<dl>
<dt> <dd>
Details regarding the text rendering of the legend labels.<tt> </tt>
<br><br>
</dl>
<p>
<b>wraplen</b>
<i>nchars</i>
<dl>
<dt> <dd>
If specified, all legend labels will be wordwrapped to a maximum length
of <i>nchars</i> characters. Useful when working with longer legend labels.<tt> </tt>
Note: labels can contain explicit line breaks using the <tt>\n</tt> construct;
<tt>wraplen</tt> takes these into account. New in 2.32.<tt> </tt>
<br><br>
</dl>
<p>
<b>seglen</b>
<i>n</i>
<dl>
<dt> <dd>
If specified, controls the length of line segment samples.<tt> </tt>
<a href="attributetypes.html#positionunits">
Absolute units.<tt> </tt>
</a>
<br><br>
</dl>
<p>
<b>nlinesym</b>
<tt>1 | 2 | 0</tt>
<dl>
<dt> <dd>
Allows control over the number of symbols per sample, with line+symbol samples.<tt> </tt>
New in 2.32.<tt> </tt>
<br><br>
</dl>
<p>
<b>swatchsize</b>
<i>n</i>
<dl>
<dt> <dd>
If specified, controls the size of color sample square.<tt> </tt>
<i>n</i> is the length of one side in
<a href="attributetypes.html#positionunits">
absolute units.<tt> </tt>
</a>
<br><br>
</dl>
<p>
<b>outlinecolors</b>
<tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
If <tt>yes</tt>, color samples will be outlined.<tt> </tt>
Normally they are not, except for white.<tt> </tt>
<br><br>
</dl>
<p>
<b>colortext</b>
<tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
If <tt>yes</tt>, entry text inherits the color of the
sample. Normally it does not.<tt> </tt>
<a href="../gallery/colorfld.htm">
Example.<tt> </tt>
</a>
<br><br><br>
</dl>
<h2>Controlling the order of legend entries</h2>
<p>
<b>specifyorder</b>
<a href="attributetypes.html#text">
multiline-text
</a>
<br>
<b>specifyorder1</b> <i>text</i>
<dl>
<dt> <dd>
If specified, allows the order of legend entries to be controlled
explicitly. Also allows entries to selected/omitted.<tt> </tt>
(Normally, entries are rendered in the order that they were added
and all entries are rendered.)
<b>specifyorder</b> is multiline text and should have one line for each entry to appear in the legend.<tt> </tt>
<b>specifyorder1</b> is single line text, entries should be separated by <tt>\n</tt>.<tt> </tt>
Each entry will be compared against all defined legend labels.
Upon a match, that legend label will be rendered. The comparison is case-insensitive.<tt> </tt>
Only the first few characters (enough to uniquely match) need be given.<tt> </tt>
<dt> <dd>
Example: <tt>specifyorder1: Jean\nJan\nJoan\nJohn\nJuan</tt>
<dt> <dd>
Another example:
<pre>
specifyorder:
Jean
Jan
Joan
John
Juan
</pre>
<br><br>
</dl>
<p>
<b>reverseorder</b>
<tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
If <tt>yes</tt>, entries are rendered from last to first.<tt> </tt>
<br><br><br>
</dl>
<h2>Backing box / frame / title</h2>
<p>
<b>frame</b>
<a href="linedetails.html">
linedetails
</a>
<tt> | no | yes | bevel</tt>
<dl>
<dt> <dd>
If specified, a frame is drawn around the legend, using the given
linedetails. <tt>bevel</tt> can be specified to get a bevel frame.<tt> </tt>
New in 2.32.<tt> </tt>
<br><br>
</dl>
<p>
<b>backcolor</b>
<a href="color.html">
color
</a>
<dl>
<dt> <dd>
If specified, a colored backing box will be shown behind the legend.<tt> </tt>
New in 2.32.<tt> </tt>
<br><br>
</dl>
<p>
<b>boxmargin</b>
<i>h</i> ...or... <i>x1 y1 x2 y2</i>
<dl>
<dt> <dd>
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.<tt> </tt>
<a href="attributetypes.html#positionunits">
Absolute units.<tt> </tt>
</a>
New in 2.32.<tt> </tt>
<dt> <dd>
If one value is given it is used on all four sides.<tt> </tt>
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).<tt> </tt>
<dt> <dd>
Example: <tt>boxmargin: 0.12</tt>
<dt> <dd>
Example: <tt>boxmargin: 0.08 0.1 0.1 0.04</tt>
<br><br>
</dl>
<p>
<b>title</b>
text
<dl>
<dt> <dd>
A title for the legend. Text must be specified in one line but can contain
the <tt>\n</tt> construct to indicate displayed line breaks. New in 2.32
<br><br>
</dl>
<p>
<b>titledetails</b>
<a href="textdetails.html">
textdetails
</a>
<dl>
<dt> <dd>
Details regarding the text rendering of the title.<tt> </tt>
<br><br><br>
</dl>
<h2>Clickmap</h2>
<p>
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.<tt> </tt>
To do this, embed a URL into the <tt>legendlabel</tt> attribute of your plotting proc (or if you are using
<a href="legendentry.html">
proc legendentry
</a>
embed it into the <tt>label</tt> attribute). Use this format: <tt>url:</tt><i>url</i><tt> </tt><i>label</i>
<br>
The combined length of the url and the label should not exceed 255 characters.<tt> </tt>
<br>
Mouseover labels are not supported for legend entries.<tt> </tt>
<br>
See this example:
<a href="../gallery/clickmap_leg.htm">
clickmap_leg
</a>
<br><br><br>
<h2>Specialized uses</h2>
<p>
<b>reset</b>
<dl>
<dt> <dd>
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:
<pre>
#proc legend
reset: yes
</pre>
</dl>
<p>
<b>noclear</b>
<tt>yes</tt> | <tt>no</tt>
<dl>
<dt> <dd>
If <tt>yes</tt>, the defined legend entries list is not cleared.<tt> </tt>
Normally this list is cleared once the legend has been rendered.<tt> </tt>
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.<tt> </tt>
<br>
Example: this is used in Gallery example
<a href="../gallery/propbars1.htm">
propbars1
</a>
<br>
<br>
</td></tr>
<td align=right>
<a href="../doc/welcome.html">
<img src="../doc/ploticus.gif" border=0></a><br><small>data display engine <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif">
</center>
</td></tr>
</table>
<br>
<center>
<table><tr><td>
Ploticus is hosted at http://ploticus.sourceforge.net</td><td> </td><td>
<a href="http://sourceforge.net/projects/ploticus"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=38453&type=12"
width="120" height="30" border="0"
alt="Get ploticus data display engine at SourceForge.net. Fast, secure and Free Open Source software downloads" /></a>
</td></tr></table>
</center>
</dl>
<p><hr>
Markup created by <em>unroff</em> 1.0, <tt> </tt> <tt> </tt>March 11, 2009.
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
ed05dc5f357c49fdded780f52b150dce
>
files
>
50
