.ig >>
<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>
.>>

.TH proc_legend PL "11-MAR-2009   PL ploticus.sourceforge.net"
 
.ig >>
<center>
<img src="../gallery/legend0.gif">
</center>
.>>

\fBproc legend\fR renders a legend
using entries that have been previously supplied in 
plotting procs (usually in an attribute called \fClegendlabel\fR), or
explicitly defined using 
.ig >>
<a href="legendentry.html">
.>>
\0proc legendentry
.ig >>
</a>
.>>
one or more times. 
.LP
Legend entries may be displayed downward or across (\fCformat\fR).
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 \fCreverseorder\fR or \fCspecifyorder\fR is used.
.LP
.ig >>
<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.
.ig >>
<a href="../gallery/legends232.htm">
.>>
\0Example of new features
.ig >>
</a>
.>>
.LP
See also the 
.ig >>
<a href="../gallery/gall.legend.html">
.>>
\0gallery legend examples.
.ig >>
</a>
.>>

.ig >>
<br><br><br>
.>>

.SH Attributes

.LP
\fBformat\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCdown\fR | \fCacross\fR
.IP \0
\fCdown\fR lists legend entries downward.
\fCacross\fR lists legend entries across.
Previous to 2.32 this was specified as \fCmultirow\fR (same as \fCdown\fR), 
or \fCsinglerow\fR (same as \fCacross\fR) and the old notation will be supported indefinately.
.br
Example: \fCformat: across\fR

.ig >>
<br><br>
.>>

.LP
\fBlocation\fR  
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#xy">
.>>
\0x y
.ig >>
</a>
.>>
.IP \0
Location for the legend.  
\fIx\fR will correspond to the beginning of the label (line segments,
color squares, etc. will appear to the left of this).
\fIy\fR will correspond to the top of the legend.
.br
Example: \fClocation: min+1.0 max\fR

.ig >>
<br><br><br>
.>>

.SH Multi-column or multi-row legends

.LP
\fBextent\fR
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR
.IP \0
Enables column breaks (or row breaks).
\fCextent\fR is a distance in
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0absolute units
.ig >>
</a>
.>>
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.
.IP \0
Example 1: suppose \fCformat\fR is \fCdown\fR and \fCextent\fR 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.
.IP \0
Example 2: suppose \fCformat\fR is \fCacross\fR and \fCextent\fR 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.
.IP \0
Usage example: \fCextent: 2.2\fR

.ig >>
<br><br>
.>>

.LP
\fBchunksep\fR
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR
.IP \0
Additional separation to add between columns or rows.
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0Absolute units.
.ig >>
</a>
.>>

.ig >>
<br><br><br>
.>>

.SH Appearance details

.LP
\fBseparation\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR
.IP \0
Amount of additional separation to add between legend entries.  
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0Absolute units.
.ig >>
</a>
.>>

.ig >>
<br><br>
.>>
.LP
\fBsep\fR
.ig >>
&nbsp; &nbsp;
.>>
(discontinued)
.IP \0
As of version 2.32 \fCsep\fR no longer does anything; it has been superseded by the 2.32 improvements
and the new \fCseparation\fR attribute.

.ig >>
<br><br>
.>>
.LP
\fBtextdetails\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="textdetails.html">
.>>
\0textdetails
.ig >>
</a>
.>>
.IP \0
Details regarding the text rendering of the legend labels.

.ig >>
<br><br>
.>>
.LP
\fBwraplen\fR
.ig >>
&nbsp; &nbsp;
.>>
\fInchars\fR
.IP \0
If specified, all legend labels will be wordwrapped to a maximum length 
of \fInchars\fR characters.  Useful when working with longer legend labels.
Note: labels can contain explicit line breaks using the \fC\\n\fR construct;
\fCwraplen\fR takes these into account.  New in 2.32.

.ig >>
<br><br>
.>>

.LP
\fBseglen\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR
.IP \0
If specified, controls the length of line segment samples.
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0Absolute units.
.ig >>
</a>
.>>

.ig >>
<br><br>
.>>
.LP
\fBnlinesym\fR
.ig >>
&nbsp; &nbsp;
.>>
\fC1 | 2 | 0\fR
.IP \0
Allows control over the number of symbols per sample, with line+symbol samples.
New in 2.32.

.ig >>
<br><br>
.>>

.LP
\fBswatchsize\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fIn\fR
.IP \0
If specified, controls the size of color sample square.
\fIn\fR is the length of one side in 
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0absolute units.
.ig >>
</a>
.>>

.ig >>
<br><br>
.>>
.LP
\fBoutlinecolors\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
If \fCyes\fR, color samples will be outlined.
Normally they are not, except for white.

.ig >>
<br><br>
.>>

.LP
\fBcolortext\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
If \fCyes\fR, entry text inherits the color of the
sample.  Normally it does not.
.ig >>
<a href="../gallery/colorfld.htm">
.>>
\0Example.
.ig >>
</a>
.>>

.ig >>
<br><br><br>
.>>

.SH Controlling the order of legend entries

.LP
\fBspecifyorder\fR 
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="attributetypes.html#text">
.>>
\0multiline-text
.ig >>
</a>
.>>
.br
\fBspecifyorder1\fR \fItext\fR
.IP \0
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.)
\fBspecifyorder\fR is multiline text and should have one line for each entry to appear in the legend.
\fBspecifyorder1\fR is single line text, entries should be separated by \fC\\n\fR.
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.
.IP \0
Example: \fCspecifyorder1: Jean\\nJan\\nJoan\\nJohn\\nJuan\fR
.IP \0
Another example:
.nf
  specifyorder: 
   Jean
   Jan
   Joan
   John
   Juan
.fi

.ig >>
<br><br>
.>>

.LP
\fBreverseorder\fR 
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
If \fCyes\fR, entries are rendered from last to first.

.ig >>
<br><br><br>
.>>
.SH Backing box / frame / title

.LP
\fBframe\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="linedetails.html">
.>>
\0linedetails
.ig >>
</a>
.>>
\fC | no | yes | bevel\fR
.IP \0
If specified, a frame is drawn around the legend, using the given
linedetails.  \fCbevel\fR can be specified to get a bevel frame.
New in 2.32.

.ig >>
<br><br>
.>>
.LP
\fBbackcolor\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="color.html">
.>>
\0color
.ig >>
</a>
.>>
.IP \0
If specified, a colored backing box will be shown behind the legend.
New in 2.32.

.ig >>
<br><br>
.>>
.LP
\fBboxmargin\fR
.ig >>
&nbsp; &nbsp;
.>>
\fIh\fR ...or... \fIx1 y1 x2 y2\fR
.IP \0
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.
.ig >>
<a href="attributetypes.html#positionunits">
.>>
\0Absolute units.
.ig >>
</a>
.>>
New in 2.32.
.IP \0
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).
.IP \0
Example: \fCboxmargin: 0.12\fR
.IP \0
Example: \fCboxmargin: 0.08 0.1 0.1 0.04\fR

.ig >>
<br><br>
.>>
.LP
\fBtitle\fR
.ig >>
&nbsp; &nbsp;
.>>
text
.IP \0
A title for the legend.  Text must be specified in one line but can contain 
the \fC\\n\fR construct to indicate displayed line breaks.  New in 2.32

.ig >>
<br><br>
.>>
.LP
\fBtitledetails\fR
.ig >>
&nbsp; &nbsp;
.>>
.ig >>
<a href="textdetails.html">
.>>
\0textdetails
.ig >>
</a>
.>>
.IP \0
Details regarding the text rendering of the title.

.ig >>
<br><br><br>
.>>
.SH Clickmap
.LP
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 \fClegendlabel\fR attribute of your plotting proc (or if you are using
.ig >>
<a href="legendentry.html">
.>>
\0proc legendentry
.ig >>
</a>
.>>
embed it into the \fClabel\fR attribute).  Use this format: \fCurl:\fIurl\fC  \fIlabel\fR
.br
The combined length of the url and the label should not exceed 255 characters.
.br
Mouseover labels are not supported for legend entries.
.br
See this example:
.ig >>
<a href="../gallery/clickmap_leg.htm">
.>>
\0clickmap_leg
.ig >>
</a>
.>>


.ig >>
<br><br><br>
.>>

.SH Specialized uses

.LP
\fBreset\fR  
.IP \0
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: 
.nf
  \0 #proc legend
  \0   reset: yes
.fi

.ig >>
&nbsp; &nbsp;
.>>

.LP
\fBnoclear\fR  
.ig >>
&nbsp; &nbsp;
.>>
\fCyes\fR | \fCno\fR
.IP \0
If \fCyes\fR, 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.
.br
Example: this is used in Gallery example
.ig >>
<a href="../gallery/propbars1.htm">
.>>
\0propbars1
.ig >>
</a>
.>>

.ig >>
<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 &nbsp; <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> &nbsp; </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>
.>>
