.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.30
     </small><br><a href="../doc/scripthome.html">Scripts</a>
  <td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>

.TH proc_legend PL "25-AUG-2004   PL ploticus.sourceforge.net"
 
.ig >>
<center>
<img src="../gallery/legend0.gif">
</center>
.>>

\fBproc legend\fR renders a legend
using entries that you must have already supplied in 
previous 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 one per line, or all on the same line (\fCformat\fR).
Each legend entry is accompanied by a small square of color, or a line segment, or a symbol,
as appropriate.  Legend entries are presented in the order given,
unless \fCreverseorder\fR or \fCspecifyorder\fR is used.
.LP
After the legend is rendered, the internal list of legend entries is normally
cleared (this can be suppressed using the \fCnoclear\fR attribute).
It is also possible to clear the internal list without rendering any
legend using the \fCreset\fR attribute.
.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;
.>>
\fCmultiline\fR | \fCsingleline\fR
.IP \0
Controls the overall format of the legend.
\fCmultiline\fR gives entries that are placed downward on multiple lines.
\fCsingleline\fR gives entries that are placed across all on the same line.
.br
Example: \fCformat: singleline\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 Controlling appearance details

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

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

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

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

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

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

.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>
.>>
.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.)
\fImultilinetext\fR 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 \fCspecifyorder\fR attribute.
.br
Example:
.br
.nf
.ft C
\fCspecifyorder: 
   Jean
   Jan
   Joan
   John
   Juan
.fi
.ft R
Other Gallery examples:
.ig >>
<a href="../gallery/timeline2.htm">
.>>
\0timeline2
.ig >>
</a>
.>>
and
.ig >>
<a href="../gallery/km2.htm">
.>>
\0km2
.ig >>
</a>
.>>

.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 Clearing the legend entry list

.LP
\fBreset\fR  
.IP \0
If specified, no legend will be rendered and the internal list
of legend entries will be cleared.  This might be useful in situations
where a number of cloned plots (and cloned legendentries) are being
done, but only one actual legend is desired.  Example: 
.nf
  \0 #proc legend
  \0   reset:
.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 they are cleared out after the legend has been rendered.
This is useful in rendering multi-column legends.
.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>
.>>
