#set TITLE = "proc legend"
#include top
 
.ig >>
<center>
<img src="../gallery/legend0.gif">
</center>
.>>

.SH DESCRIPTION
Renders a legend.
\fBproc legend\fR uses entries that you must have already supplied in 
previous plotting procs (usually in an attribute called \fClegendlabel\fR).
You can also explicitly define legend entries using \fBproc legendentry\fR
one or more times.  If this is not clear, check the example.
.LP
For bars, each legend entry is shown with a small square sample of color.
For lineplot and curvefit, a small segment of the line is shown.
For scatterplot, a symbol is shown.
Legend entries are presented in the order that the plotting procs were 
executed (or reverse order if specified).
.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.


.SH EXAMPLES
See the Gallery Legends examples
.ig >>
<a href="../gallery/gall.legend.html"><img src="../gallery/btn/here.gif"></a>
.>>

.SH PREREQUISITES
Plotting proc(s) containing a \fClegendlabel\fR specification,
and/or \fBproc legendentry\fR must have already been executed.


.SH MANDATORY ATTRIBUTES
None.  


.SH ATTRIBUTES

.LP
\fBformat\fR \fCmultiline\fR | \fCsingleline\fR
.IP
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

.LP
\fBlocation\fR  
.ig >>
<a href="attributetypes.html#xy">
.>>
\fI x y \fR
.ig >>
</a>
.>>
.IP
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

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

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

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

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

.LP
\fBoutlinecolors\fR \fCyes\fR | \fCno\fR
.IP
If \fCyes\fR, color samples will be outlined.
Normally they are not, except for white.

.LP
\fBspecifyorder\fR 
.ig >>
<a href="attributetypes.html#text">
.>>
\fI multiline-text \fR
.ig >>
</a>
.>>
.IP
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">
.>>
 timeline2 
.ig >>
</a>
.>>
and
.ig >>
<a href="../gallery/km2.htm">
.>>
 km2 
.ig >>
</a>
.>>

.LP
\fBreverseorder\fR \fCyes\fR | \fCno\fR
.IP
If \fCyes\fR, entries are rendered from last to first.

.LP
\fBcolortext\fR \fCyes\fR | \fCno\fR
.IP
If \fCyes\fR, entry text inherits the color of the
sample.  Normally it does not.
#set FILE = "../gallery/colorfld.htm"
#set TAG = "Example."
#include link

.LP
\fBnoclear\fR  \fCyes\fR | \fCno\fR
.IP
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">
.>>
 propbars1 
.ig >>
</a>
.>>

.LP
\fBreset\fR  
.IP
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.  New in version 1.40.

#include bottom
