DADiSP Online Help
Click here to see this page in full context

DADiSP Worksheet Functions > Function Categories > Annotation > TEXT

 

TEXT

Purpose:

Draws a left-justified block of text at a given point.

Syntax:

TEXT(

win, x, y, target, fg, bg, font, box, legend, stretch, margin, focus, bold, italic, fontsize, fontangle, lock, visible, "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 text.

target

-

Optional. An integer specifying the spatial relationship of the text to the Window:

0:

PAPER (default). The text is located on the "graph paper" in the Window; within the coordinate system of the data. The text scrolls with the series.

1:

GLASS. The text is located within the plotting area of Window. The text remains fixed in place when the series scrolls.

2:

GLASS_WMARGIN. The text is located within the area of the entire Window. The text remains fixed in place when the series scrolls.

3:

GLASS_WPMARGIN. The text is located within the vertical dimensions of a Window, and within the horizontal dimensions of the plotting area. The text remains fixed in place when the series scrolls.

4:

GLASS_WSMARGIN. The text is located anywhere within the entire Worksheet area.

fg

-

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

bg

-

Optional. An integer specifying the background color of the text. 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 text (with margin if legend is ON, otherwise, no margin). 1: ON; 0: OFF. Defaults to 1.

legend

-

Optional. An integer specifying whether legend symbols are present or absent. 1: ON; 0: OFF. Defaults to 0.

stretch

-

Optional. An integer specifying whether to stretch the annotation to fit the rectangular region where the text block resides. 1: ON; 0: OFF. Defaults to 0.

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.

bold

-

Optional. An integer specifying the bold property of the text font. Defaults to 0, not bold.

italic

-

Optional. An integer specifying the italic property of the text font. Defaults to 0, not italic.

fontsize

-

Optional. An integer specifying the size of the font in points. Defaults to the system font size.

fontangle

-

Optional. An integer specifying the angle of the text font. Defaults to 0, horizontal text.

lock

-

Optional. An integer specifying whether the text can be moved interactively via the mouse or keyboard. Defaults to 0, allow interactive text movement.

visible

-

Optional. An integer specifying the visibility of the text. Defaults to 1, the text is visible.

"s1", ... "sN"

-

One or more strings. Additional strings are optional and separated by commas. This is the text that will be printed at the specified x and y coordinates. Annotation lines are in top to bottom order.

Returns:

An integer object handle that can be used to set or adjust text properties.

Example:

grand(100,1)*10;text(6.0, 3.0, 0, -1, YELLOW, 1, 1, 0, "Temp over Time")

 

In this example, TEXT prints the text, Temp over Time at axis coordinates (6.0, 3.0) of the Window.

 

The 0 as the target indicates that the text will scroll with the data (PAPER).

 

The -1, YELLOW arguments use the color of the primary series and yellow for the background.

 

The text will be drawn using the small font (1), and it will be surrounded by a box.

Example:

W1: gsin(100,.01);setsymb(SQUARE,1,10,1)

W2: W1;overlay(gcos(100,.01),RED);setsymb(9,2,10,5)

text(0.5, 0.2, 1, "Sampled Data")

 

Places text that remains fixed as the data scrolls (GLASS) in the current Window.

Example:

text(W2,.1,.8,2,-1,-1,1,1,1,0,3,'Sine','Cosine')

 

puts a legend in the left window margin of W2.

Example:

Text annotations can be manipulated by setting the text properties of the returned object handle.

 

W1: gsin(100,.01)

h = text(W1, 0.2, 0.0, "Example Text");

h.color = lred; h.fontsize = 20;h.bold = 1;

 

Text is placed in W1 at coordinates (0.3, 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:

In general, TEXT replaces the older TEXTANN function.

 

As shown, text properties can be manipulated with the object handle. The following text 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

tag

string

object identifier

bold

integer

font bold

fill

integer

same as bg, background color

font

integer

font type identifier

lock

integer

lock interactive movement

text

string

text string

type

string

readonly type of object, "text"

color

integer

same as fg, text color

focus

integer

target overlay focus

group

integer

group number

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

move callback function

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 background stretches to occupy plot width

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 (if legend)

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

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 text in the upper right corner of the plotting area:

 

h = text(0, 0, PAPER, "My Text");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 = text(0, 0, GLASS_WMARGIN, "My Text");h.location = 1;h.margin = 1;

 

places text in the outside upper right margin of the window. The right margin of the plotting area automatically adjusts to accommodate the text.

 

TEXT 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 text via the Text Toolbar and the text can be subsequently manipulated with the mouse or object handle.

 

Use -2 to specify the default value for any integer parameter.

 

If box is ON, then its background will be filled with the background color, and its edges will be drawn as solid lines in the foreground color.

 

If legend is ON, then the x,y parameters refer to the lower left corner of the first symbol in the legend block, not to the lower left corner of the first line in the text block. Each next line in the legend refers to the next OVERPLOT for color, line style, and symbols. Also, the interline spacing in legends is greater than in the no-legend-symbol case.

 

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 */

text_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 text:

 

h = text(0, 0, "My Text");h.onmotion = "text_onmotion";

 

The text_onmotion function is invoked when the text moves via the mouse. In this case, the coordinates of the text are displayed in the status line.

 

 

A subset of TeX equation formatting is supported to annotate graphics with Greek letters and mathematical symbols. For example:

 

text(0.5, 0.5, "$y(t) = \sin(2\pif_0t + \theta)$")

 

Produces the annotation:

 

y(t) = sin(2πf0t + θ)

 

See TEX for further details.

 

See FINDTEXT to return the handles of text and legend objects based on specific property values.

See Also:

FINDTEXT

LEGEND

LINEDRAW

TEX

TEXTANN

TEXTCUR

TEXTDEL

TEXTEDIT

TEXTMOVE