ARROWDRAW

Purpose:

Draws an arrow line between specified coordinates.

Syntax:

ARROWDRAW(

win, color, style, target, match, focus, width, stem, base, head, x1, y1, x2, y2)

win

-

Optional. The target window. Defaults to the current window.

color

-

Optional. An integer or macro color name (e.g. RED) specifying the arrow line color. Defaults to color of primary series.

style

-

Optional. An integer specifying the arrow line style:

1:

Solid (default)

2:

Dashed

3:

Dotted

target

-

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

0:

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

1:

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

2:

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

3:

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

4:

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

match

-

Optional. An integer that sets the line color to match the color of the selected overplot. Defaults to 1 (primary series). 1 implies use color parameter.

focus

-

Optional. An integer specifying 1-based focus offset for PAPER annotations.

width

-

Optional. An integer specifying the arrow line width in pixels. Defaults to 1.

stem

-

Optional. An integer specifying the length of the arrowhead stem in pixels. Defaults to 1.

base

-

Optional. An integer specifying the width of the arrowhead base in pixels. Defaults to 1.

head

-

Optional. An integer specifying the location of the arrowhead:

0:

Last point. The arrowhead is located at the ending coordinates (default).

1:

First point. The arrowhead is located at the starting coordinates.

2:

Both ends. Arrowheads are located at the start and end coordinates.

x1, y1, x2, y2

-

Real number coordinates representing endpoints of arrow line.

Example:

gtri(100,.01,2);arrowdraw(purple,2,1,-1,0.09,0.04,0.9,0.5)

 

creates a purple dashed (2) arrow in "glass mode" (1). The color of the arrow is purple, and is unrelated to any overplots (match == -1); the arrow spans from coordinates (0.09, 0.04) to (0.9, 0.5).

Example:

gtri(100,.01,2);arrowdraw(lred,1,0,-1,-1,2,-1,-1,2,0.6,1.1,0.75,1.0)

 

Creates a red solid double arrow on the paper. The arrow line scrolls with the series.

Example:

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

 

W1: gsin(100,.01)

h = arrowdraw(W1, 0.2, -0.5, 0.6, 1.0);

h.color = lred; h.width = 4;h.arrowdir = 2;

 

An arrow is placed in W1 at coordinates (0.2, -0.5), (0.6, 1.0) and the color is set to light red, the width is set to 4 and the arrow direction is set to arrow heads at both ends.

Remarks:

Arrow properties can be manipulated with the object handle. The following properties are available:

 

Name

Type

Description

x

real

x coordinate

y

real

y coordinate

tag

string

object identifier

xor

integer

xor background flag

fill

integer

background color

lock

integer

lock interactive movement

type

string

type of object, "shape"

color

integer

arrow color

focus

integer

target overlay focus

match

integer

overplot number to match color

shape

string

readonly type of shape, "arrow"

style

integer

arrow style

width

integer

arrow width

coords

series

arrow coordinates as a series

handle

integer

arrow handle

onmove

string

move callback function

onsize

string

size callback function

tagnum

integer

same as handle, arrow handle

target

integer

arrow coordinate target, glass, paper, etc.

winnum

integer

readonly window number of arrow target

showtag

integer

show arrow string tag

visible

integer

arrow visibility

arrowdir

integer

arrow head direction

arrowlen

integer

length of the stem of the arrow head

arrowwidth

integer

width of the base of the arrow head

oncreate

string

creation callback function

ondelete

string

deletion callback function

onlclick

string

mouse left click callback function

onmotion

string

motion callback function

onrclick

string

mouse right click callback function

onsizing

string

sizing callback function

position

series

readonly bounding box coordinates of the arrow in window coordinates. Lower left X coordinate, Y coordinate, height and width

devposition

series

readonly bounding box coordinates of the arrow in device coordinates

 

Readonly properties can only be queried. All other properties can be set and queried using the handle.property dot syntax.

 

ARROWDRAW can be used directly from the command line or as part of an SPL routine to draw arrows in a Window that contains data. The result is identical to adding arrows via the Line Toolbar and the arrows can subsequently be manipulated with the mouse.

 

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

 

When setting an index match, use 1 to refer to the color of the primary series; use 2 to refer to the color of the first overplot; 3 for the second overplot, etc.

 

The onmove, onsize, oncreate, ondelete, onlclick, onmotion, onrclick and onsizing callbacks specify functions to run when the associated event occurs. For example, consider the following callback function:

 

 

/* motion callback */

shape_onmotion(h)

{

    printf("x1: %g  y1: %g  x2: %g  y2: %g",

            h.x[1], h.y[1], h.x[2], h.y[2]);

}

 

 

A callback function accepts the annotation handle as the sole input.

 

Now for the arrow:

 

h = arrowdraw(0.0, 0.0, 1.0, 1.0);h.onmotion = "shape_onmotion";

 

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

 

 

See FINDSHAPE to return the handles of shape objects based on specific property values.

 

See ELLIPSEDRAW to draw an ellipse line.

 

See LINEDRAW to draw one or more line segments.

 

See POLYGONDRAW to draw a closed polygon.

 

See RECTDRAW to draw a rectangle.

See Also:

ARROWCUR

ELLIPSEDRAW

FINDHANDLE

FINDSHAPE

FINDTEXT

LINECUR

POLYGONDRAW

RECTDRAW

TEXT