DADiSP Worksheet Functions > Function Categories > Annotation > LEGEND
Sets the attributes and location for a standard legend.
|
win, x, y, target, fg, bg, font, box, margin, focus, "s1", ..., "sN") |
win |
- |
Optional. The target window. Defaults to the current window. |
||||||||||||||||||||||||
x, y |
- |
Real numbers that designate the upper left anchor coordinate pair for the legend. |
||||||||||||||||||||||||
target |
- |
Optional. An integer specifying the spatial relationship of the legend to the Window:
|
||||||||||||||||||||||||
fg |
- |
Optional. An integer specifying the foreground color of the legend. Defaults to 1, the color of the primary series. |
||||||||||||||||||||||||
bg |
- |
Optional. An integer specifying the background color of the legend. Defaults to 1, the Window background color. |
||||||||||||||||||||||||
font |
- |
Optional. An integer specifying the font:
|
||||||||||||||||||||||||
box |
- |
Optional. An integer specifying presence or absence of a solid line box framing the legend (with margin if legend is ON, otherwise, no margin). 1: ON; 0: OFF. Defaults to 1. |
||||||||||||||||||||||||
margin |
- |
Optional. An integer specifying the margin to be adjusted:
|
||||||||||||||||||||||||
focus |
- |
Optional. An integer specifying the focus for PAPER annotations. Defaults to 1, the primary focus. |
||||||||||||||||||||||||
"s1", ... "sN" |
- |
Optional. The text that will be printed at coordinates x and y above. Annotation lines are in top to bottom order. If not specified, the text defaults to the series comment. |
W1: gsin(100,.01);setsym(SQUARE,1,10,1);comment("Sine")
W2: gcos(100,.01);setsymb(14,1,10,5);comment("Cosine")
legend(W2,.1,.8,1)
puts a legend in the bottom left corner of W2.
legend(w1,.8,.2,2,-1,-1,1,1,1,"Sinewave")
places a legend in the upper right margin of W1.
Legend annotations can be manipulated by setting the text properties of the returned object handle.
W1: gsin(100,.01)
h = legend(W1, 0.2, 0.0, PAPER, "Example Legend");
h.color = lred; h.fontsize = 20;h.bold = 1;
A legend is placed in W1 at coordinates (0.2, 0.0) and the text color is set to light red, the font size is set to 20 points and the font is in bold.
The standard legend uses the comment field, retrieved via GETCOMMENT, to describe each item. Revising the comments via SETCOMMENT or COMMENT, followed by a PON will revise the standard legend.
As shown, legend properties can be manipulated with the object handle. The following properties are available:
Name |
Type |
Description |
||||||||||||||||||||
x |
real |
x coordinate |
||||||||||||||||||||
y |
real |
y coordinate |
||||||||||||||||||||
bg |
integer |
background color |
||||||||||||||||||||
fg |
integer |
text color |
||||||||||||||||||||
box |
integer |
draw outline around text |
||||||||||||||||||||
fill |
integer |
same as bg, background color |
||||||||||||||||||||
font |
integer |
font type identifier |
||||||||||||||||||||
lock |
integer |
lock interactive movement |
||||||||||||||||||||
text |
string |
text string |
||||||||||||||||||||
color |
integer |
same as fg, text color |
||||||||||||||||||||
focus |
integer |
target overlay focus |
||||||||||||||||||||
pitch |
integer |
font pitch |
||||||||||||||||||||
shape |
string |
readonly type of object, "text" |
||||||||||||||||||||
coords |
series |
text coordinates as a series |
||||||||||||||||||||
handle |
integer |
text handle |
||||||||||||||||||||
italic |
integer |
font italics |
||||||||||||||||||||
legend |
integer |
text is legend |
||||||||||||||||||||
margin |
integer |
plot margin to adjust
|
||||||||||||||||||||
onedit |
string |
edit callback function |
||||||||||||||||||||
onmove |
string |
moved callback |
||||||||||||||||||||
tagnum |
integer |
same as handle, text handle |
||||||||||||||||||||
target |
integer |
text coordinate target, glass, paper, etc. |
||||||||||||||||||||
winnum |
integer |
readonly window number of text target |
||||||||||||||||||||
charset |
integer |
font character set |
||||||||||||||||||||
showtag |
integer |
show font string tag |
||||||||||||||||||||
stretch |
integer |
text stretch to fit flag |
||||||||||||||||||||
visible |
integer |
text visibility |
||||||||||||||||||||
boxcolor |
integer |
color of the box outline |
||||||||||||||||||||
fontname |
string |
font face name |
||||||||||||||||||||
fontsize |
integer |
font size in pixels |
||||||||||||||||||||
location |
integer |
fixed text location
|
||||||||||||||||||||
numlines |
integer |
readonly number of text lines |
||||||||||||||||||||
oncreate |
string |
creation callback function |
||||||||||||||||||||
ondelete |
string |
deletion callback function |
||||||||||||||||||||
onlclick |
string |
mouse left click callback function |
||||||||||||||||||||
onmotion |
string |
movement callback function |
||||||||||||||||||||
onrclick |
string |
mouse right click callback function |
||||||||||||||||||||
position |
series |
readonly bounding box coordinates of text in window coordinates |
||||||||||||||||||||
symwidth |
integer |
symbol width |
||||||||||||||||||||
fontangle |
integer |
font angle (0 for horizontal) |
||||||||||||||||||||
pointsize |
integer |
font size in points |
||||||||||||||||||||
devposition |
series |
readonly bounding box coordinates of text in device coordinates |
||||||||||||||||||||
orientation |
integer |
orientation for multiple lines
|
Readonly properties can only be queried. All other properties can be set and queried using the handle.property dot syntax.
All GLASS coordinates are normalized to the specified rectangular regions in the Window or Worksheet, where the upper left corner is (0.0, 0.0) and the lower right corner is (1.0, 1.0). GLASS annotations "stick" to the Window like the viewfinder in a camera, while PAPER annotations scroll with the data.
The location property specifies a fixed location such that the text remains fixed relative to the plot borders regardless of the window size. To place a legend in the upper right corner of the plotting area:
h = legend(0, 0, PAPER, "My Legend");h.location = 1;
To specify a fixed location outside the plotting area, set target to GLASS_WMARGIN or GLASS_WPMARGIN and set the appropriate margin to adjust. For example:
h = legend(0, 0, GLASS_WMARGIN, "My Legend");h.location = 1;h.margin = 1;
places a legend in the outside upper right margin of the window. The right margin of the plotting area automatically adjusts to accommodate the legend.
LEGEND can be used directly from the command line or as part of an SPL routine to annotate a Window that contains data. The result is identical to adding a legend via the Text Toolbar and the legend can be subsequently manipulated with the mouse or object handle.
Use -2 to specify the default value for any integer parameter.
The onedit, onmove, oncreate, ondelete, onlclick, onmotion and onrclick callbacks specify functions to run when the associated event occurs. For example, consider the following callback function:
/* motion callback */
legend_onmotion(h)
{
printf("x: %g y: %g", h.x, h.y);
}
A callback function accepts the annotation handle as the sole input.
Now for the legend:
h = legend(0, 0, "Series");h.onmotion = "legend_onmotion";
The legend_onmotion function is invoked when the legend moves via the mouse. In this case, the coordinates of the legend are displayed in the status line.
See FINDTEXT to return the handles of text and legend objects based on specific property values.