GUIEllipse

Description: This function draws an ellipse in a window and returns an indication when selected by a mouse button or the <ENTER> key.

Returns: Numeric (see table in appendix)

Usage: Steady State

Format: GUIEllipse(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Visibility, Reserved, Button, FocusID, FocusTrigger, Brush, Pen)

Parameters: LeftReference { numeric } { required constant } { no default }

A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.

BottomReference { numeric } { required constant } { no default }

A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen.

RightReference { numeric } { required constant } { no default }

A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.

TopReference { numeric } { required constant } { no default }

A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.

ScaleLeft { numeric or Normalize } { required } { no default }

Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position; a value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position; if the value is at the low level, the side will be at the opposite side reference position.

ScaleBottom { numeric or Normalize} { required } { no default }

ScaleRight { numeric or Normalize } { required } { no default }

ScaleTop { numeric or Normalize } { required } { no default }

ScaleWhole { numeric or Normalize } { required } { no default }

Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.

Trajectory { numeric or Trajectory} { required } { no default }

Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.

Rotation { numeric or Rotate } { required } { no default }

Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.

Visibility { Boolean } { required } { no default }

Any logical expression. If true, the image is drawn normally. If false, the image is not drawn.

Reserved n/a

Reserved for future use, set to 0.

Button { numeric } { required } { no default }

Any numeric expression giving the button combination that activates this graphic.

Value	Locator Buttons
0	No buttons
1	Right button
2	Middle button
3	Right and middle buttons
4	Left button
5	Left and right buttons
6	Left and middle buttons
7	All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For ex ample, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7); to accept the left mouse button regardless of whether or not the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID { numeric } { required } { no default }

Any numeric expression giving the focus number of this graphic. If FocusID is zero, this graphic cannot receive the input focus. This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.

FocusTrigger { Boolean } { required } { no default }

Any logical expression. If FocusTrigger changes from a valid false to a valid true, this graphic will attempt to obtain focus.

Brush { numeric or Brush } { required } { no default }

Any expression that returns a Brush value or a numeric value that describes the color used to fill the ellipse.

Pen { numeric or Pen } { required } { no default }

Any expression that returns a Pen value or a numeric value that describes the color used to draw the ellipse.

Comments: This function is a layered graphics statement. See Use Scaling to Position GUI Objects for information about positioning a layered graphic.

GUIEllipses whose Pen value has an even numbered width are subject to pixel rounding errors, which is particularly obvious when drawing two concentric ellipses, one with an even width outline and one with an odd. To avoid this, always use all even or all odd outline widths for concentric ellipses.

The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1^st 42 pixels of a VTS application will be obscured by the title bar, if present.

Example:

sizeVal = 100;

...

If ZButton(10, 100, 110, 70, "Grow", 1);

[

sizeVal++;

]

If ZButton(10, 100, 110, 70, "Shrink", 1);

[

sizeVal--;

]

GUIEllipse(580, 565, 720, 500 { Bounding box of ellipse },

1, 1, 1, 1, { No component scaling }

Normalize(sizeVal, 0, 100) { Scale according to var },

0, 0 { No trajectory or rotation },

1 { Ellipse is visible },

0 { Reserved },

0, 0, 0 { Cannot be focused },

Brush(11, 1, 21) { Brush is cyan, with a dark blue

background, style is checkered },

Pen(8, 1, 1) { Pen draws dark gray solid

lines 1 pixel wide });

This draws two buttons in the upper right corner, and a cyan and dark blue checkered ellipse outlined in gray in the lower right corner of the window. The ellipse cannot be focused, but the buttons can. As the mouse clicks on one of the buttons, the ellipse will grow or shrink (depending which button is selected). Normally, it is not a good idea to animate an object with a complicated fill pattern, however, since the changes to the object's size are done manually, the time is more limited by the speed of human interaction than by re-draw speed.

The first four parameters must be constants. See GUITransform for an example of how to compute the position dynamically.