DADiSP Online Help

Click here to see this page in full context

DADiSP Worksheet Functions > Function Categories > Annotation > LEGEND

LEGEND

Purpose:

Sets the attributes and location for a standard legend.

Syntax:

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:

0:	PAPER (default). The legend is located on the "graph paper" in the Window; within the coordinate system of the data. The legend scrolls with the series.
1:	GLASS. The legend is located within the plotting area of Window. The legend remains fixed in place when the series scrolls.
2:	GLASS_WMARGIN. The legend is located within the area of the entire Window. The legend remains fixed in place when the series scrolls.
3:	GLASS_WPMARGIN. The legend is located within the vertical dimensions of a Window, and within the horizontal dimensions of the plotting area. The legend remains fixed in place when the series scrolls.
4:	GLASS_WSMARGIN. The legend is located anywhere within the entire Worksheet area.

Optional. An integer specifying the foreground color of the legend. Defaults to 1, the color of the primary series.

Optional. An integer specifying the background color of the legend. Defaults to 1, the Window background color.

font

Optional. An integer specifying the font:

0:	NORM_FONT (default)
1:	SMALL_FONT
2:	STATLINE_FONT
3:	POPBOX_FONT
4:	WINLABEL_FONT
5:	TOOLBAR_FONT
6:	LISTBOX_FONT
7:	MENU_FONT
8:	USER1_FONT
9:	USER2_FONT
10:	USER3_FONT
11:	PANEL_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:

-1:	No Margin Adjustment (default)
0:	Top Margin
1:	Right Margin
2:	Bottom Margin
3:	Left Margin

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.

Example:

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.

$image\legendpic.gif$

Example:

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.

Remarks:

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

real

x coordinate

real

y coordinate

integer

background color

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

-1:	No Margin Adjustment (default)
0:	Top Margin
1:	Right Margin
2:	Bottom Margin
3:	Left Margin

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

0:	No Fixed Location (default)
1:	Upper Right
2:	Upper Left
3:	Lower Left
4:	Lower Right
5:	Upper Center
6:	Lower Center
7:	Right Center
8:	Left Center
9:	Center

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

0:	Vertical (default)
1:	Horizontal

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.

LEGEND

Purpose:

Syntax:

Example:

Example:

Remarks:

See Also: