RECTDRAW

Purpose:

Draws a rectangle at the specified coordinates.

Syntax:

RECTDRAW(

win, color, style, target, match, focus, width, fill, 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 rectangle border color. Defaults to color of primary series.

style

-

Optional. An integer specifying the rectangle border style:

1:

Solid (default)

2:

Dashed

3:

Dotted

target

-

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

0:

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

1:

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

2:

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

3:

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

4:

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

match

-

Optional. An integer that sets the rectangle border 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 rectangle border width in pixels. Defaults to 1.

fill

-

Optional. An integer specifying the interior color. Defaults to 1, transparent.

x1, y1, x2, y2

-

Real number coordinates representing the diagonal of the rectangle.

Returns:

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

Example:

gtri(100,.01,2);rectdraw(purple, 2, 0, -1, 0.2, 0.4, 0.7, 1.0)

 

creates a purple dashed (2) rectangle in "paper mode" (0). The color of the rectangle border is purple, and is unrelated to any overplots (match == -1); the diagonal of the rectangle spans from coordinates (0.2, 0.4) to (0.7, 1.0).

Example:

W1: gnorm(1000, 1);

W2: integ(w1);rectdraw(lred, minloc, min, maxloc, max)

 

A rectangle is placed in W2 with a red border that outlines the region bounded by the minimum and maximum values. Each time W1 changes, the data in W2 updates and the also rectangle updates.

Example:

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

 

W1: gsin(100,.01)

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

h.color = lred; h.width = 4;h.fill = yellow;

 

A rectangle is placed in W1 with the diagonal at coordinates (0.2, -0.5), (0.6, 1.0) and the border color is set to light red, the border width is set to 4 and the fill color is set to yellow.

Remarks:

Rectangle 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

border color

focus

integer

target overlay focus

match

integer

overplot number to match color

shape

string

readonly type of shape, "rectangle"

style

integer

border line style

width

integer

border width

coords

series

diagonal coordinates as a series

handle

integer

rectangle handle

onmove

string

move callback function

onsize

string

size callback function

tagnum

integer

same as handle, rectangle

target

integer

rectangle coordinate target, glass, paper, etc.

winnum

integer

readonly window number of rectangle target

showtag

integer

show rectangle string tag

visible

integer

rectangle visibility

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 rectangle in window coordinates, lower left X coordinate, Y coordinate, height and width

devposition

series

readonly bounding box coordinates of the rectangle in device coordinates

transparency

integer

interior transparency

 

 

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

 

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

 

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

 

The overplot index match associates a rectangle annotation with a specific overplot by guaranteeing that the rectangle border color will be the same as the overplot color.

 

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 rectangle:

 

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

 

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

 

 

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

 

See ARROWDRAW to draw an arrow line.

 

See ELLIPSEDRAW to draw an ellipse.

 

See LINEDRAW to draw one or more line segments.

 

See POLYGONDRAW to draw a closed polygon.

See Also:

ARROWDRAW

ELLIPSEDRAW

FINDHANDLE

FINDSHAPE

FINDTEXT

LINECOPY

LINECUR

LINEDEL

LINEDRAW

LINEMOVE

POLYGONDRAW

TEXT