DADiSP Online Help

Click here to see this page in full context

DADiSP Worksheet Functions > Function Categories > Annotation > ELLIPSEDRAW

ELLIPSEDRAW

Purpose:

Draws an ellipse at the specified coordinates.

Syntax:

ELLIPSEDRAW(

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 ellipse border color. Defaults to color of primary series.

style

Optional. An integer specifying the ellipse border style:

1:	Solid (default)
2:	Dashed
3:	Dotted

target

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

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

match

Optional. An integer that sets the ellipse 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 ellipse 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 ellipse.

Returns:

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

Example:

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

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

Example:

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

W1: gsin(100,.01)

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

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

An ellipse 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:

Ellipse 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, "ellipse"
style	integer	border line style
width	integer	border width
coords	series	diagonal coordinates as a series
handle	integer	ellipse handle
onmove	string	move callback function
onsize	string	size callback function
tagnum	integer	same as handle, rectangle
target	integer	ellipse coordinate target, glass, paper, etc.
winnum	integer	readonly window number of ellipse target
showtag	integer	show ellipse string tag
visible	integer	ellipse 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 ellipse in window coordinates, lower left X coordinate, Y coordinate, height and width
devposition	series	readonly bounding box coordinates of the ellipse 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.

ELLIPSEDRAW 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 lines via the Drawing Toolbar and the ellipse can subsequently be manipulated with the mouse.

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

The overplot index match associates an ellipse annotation with a specific overplot by guaranteeing that the ellipse 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 ellipse:

h = ellipsedraw(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 LINEDRAW to draw one or more line segments.

See POLYGONDRAW to draw a closed polygon.

See RECTDRAW to draw a rectangle.

ELLIPSEDRAW

Purpose:

Syntax:

Returns:

Example:

Example:

Remarks:

See Also: