GUIButton

Description: This function draws a push-button 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: GUIButton(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Visibility, Reserved, Button, FocusID, FocusTrigger, Brush, HighlightPen, ShadowPen, TextColor, Sides, Reserved, UpLabel, DownLabel, Font, DownValue, UpValue, Variable[, ButtonImages, ClickSound])

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. If this is a Brush value, that brush will be used to draw the background of the button. If this is a numeric value, it will be used as a solid background color.

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

Any expression returning a Pen or a numeric value. If this is a Pen value, that pen will be used to draw the highlight sides of the button. If this is a numeric value, it will be used as the color of a solid pen 1 pixel wide.

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

Any expression returning a Pen or numeric value. If this is a Pen value, that pen will be used to draw the shadowed sides of the button. If this is a numeric value, it will be used as the color of a solid pen 1 pixel wide.

TextColor { numeric, Pen or Brush } { required } { no default }

Any expression returning a Pen value, a Brush value or a numeric value. If it is a numeric value it will be the color of the text which appears on the button. If it is a Brush value its foreground color will be used for the color of the text on the button. If it is a Pen value its color will be used for the color of the text on the button.

Sides { numeric } { required } { no default }

Any numeric expression giving the number of sides on the button. If this value is 0, the button will look like a Windows four-sided button. Otherwise, the value must be greater than or equal to 4.

Reserved n/a

Reserved for future use, set to 0.

UpLabel { Bitmap } { required } { no default }

Any text expression or any expression returning a Bitmap value. The text will be drawn in the font indicated by the Font parameter, and both text and bitmaps will be centered on the button while it is up (released).

DownLabel { Bitmap } { required } { no default }

Font { Font } { required } { no default }

Any expression returning a Font value, or any numeric expression. If this is a valid numeric expression, the font for text labels will be the default font. Otherwise, the text labels will be drawn using this font.

DownValue { varies } { required } { no default }

Any expression. This will be assigned to the variable parameter when the button is down (pressed). If the value of Variable matches the value of this expression, the button will immediately be drawn as down.

UpValue { varies } { required } { no default }

Any expression. This will be assigned to the variable parameter when the button is up (released). If the value of Variable matches the value of this expression, the button will immediately be drawn as up.

Variable { varies } { required } { no default }

Any variable or any expression which may receive an assignment (any l-value). This will be set whenever the button is pressed or released. If this value is changed by another expression (or is given a default value) to match either the UpValue or the DownValue, the button will be drawn in whatever status the value represents - up or down.

ImageSet { struct } { optional } { no default }

A set of bitmap values, stored in a structure, to be used in response to various mouse actions. Not all need be specified.

The full list of possible members for the structure is as follows:

ImageSetStruct STRUCT [

UpImage { Image to use when the button is “up” };

MouseOverUpImage { Image to use when the mouse is over an

“up” button };

DownImage { Image to use when the button is “down” };

MouseOverDownImage { Image to use when the mouse is over

a “down” button };

DisabledImage { Image to use when user actions on

the button are disabled };

];

ClickSound { text } { optional } { no default }

The name of a .wav file that is to be played when the button is clicked upon. The extension “.wav” will be appended if not provided in the parameter. This file will not be played while another sound such as an alarm, is sounding.

Comments: There are three basic types of buttons: momentary, toggle (or latching) and radio (which is actually a group of buttons behaving as a unit). For details on how to create each of these types, see the Examples section.

A momentary button is one that immediately releases when pressed (i.e. it does not remain in its pressed position). It is usually used in conjunction with an If statement as an action trigger for a script.

A toggle or latching button is a button that when pressed remains locked (latched) into its pressed position until it is pressed again (unlatched). Its Variable parameter will be set according to the position of the button - if it is latched in (pressed), the variable will be set to 1, otherwise it will be 0. Similarly, if the variable's value is set by an external source from 0 to 1, the button will become pressed to match the value. This latching/toggling effect is achieved by the second last parameter being set to ! Variable, which is the same as saying "not the value of the Variable parameter" or more simply, "toggle the value from what it currently is".

A radio button is one of a set of latching buttons that are mutually exclusive, that is to say, only one button in the set may be latched (down) at one time. When another button in the same set is pressed, the current depressed button will "pop out"; two buttons cannot be latched in at once.

If the FocusID parameter of a GUIButton is to be used in a NextFocusID statement to force this graphic to get the focus, it is important to note that this does not cause the GUIButton statement to become true (selected), but only for it to become focused. Once the button is focused it may then be selected via the <CR> key on the keyboard.

Since structures cannot be initialized in steady state, the ImageSet parameter must be created in a script. You may create your own structures, or use one that has been created for you. The syntax to use the pre-defined structure varies depending on whether you are working in a script application or a standard VTS application.

• For script applications, use \System\ImageSetStruct()

• For standard applications, use \ImageSetStruct().

The following set of rules defines the ImageSet behavior:

• This parameter was introduced with VTS 9.0 and is backwards compatible. In the absence of the ImageSet parameter or, if that parameter is present but is not valid, the GUIButton statement will behave as it did in ver does. (GUIButton statements in applications created prior to the release of 9.0 continue to operate unaffected.)

• In the presence of a valid ImageSet parameter, the current GUIButton rendering will be disabled. (Note that providing a valid variable that holds Invalid for this parameter will not disable the older GUIButton rendering).

• It is possible to specify the ImageSet parameter as Invalid and use only the ClickSound parameter

• The ImageSet parameter, when valid, must consist of a structure holding the images.

• Each structure member must be named as described in the parameter listing above.

• The only valid formats for each image in the structure are bitmap values.

• You may declare your own structure or use one of the two pre-created structures in VTS. Dior standard apps you can simply use \ImageSetStruct ()and for script apps you can use \System\ImageSetStruct()

In addition to these rules for the ImageSet structure, the following rules govern how the button will be rendered:

• If no image is provided in the set, no images shall be displayed for the button. You will end up with a blank, clickable area

• If the button is disabled, the “Disabled” image will be displayed at all times. If there is no Disabled image the “Up” image will be displayed.

• If the mouse cursor is not within the bounding box of the button:

• If the button state is logically up, the “Up” image (if any) shall be displayed. If there is no “Up” image, no image shall be displayed.

• If the button state is logically down, the “Down” image (if any) shall be displayed. If there is no “Down” image, no image shall be displayed.

• If the mouse cursor is within the bounding box of the button:

• If the button state is logically up, the “MouseOverUp” image (if any) shall be displayed. If there is no “MouseOverUp” image, the “Up” image (if any) shall be displayed. If there is no “Up” image, no image shall be displayed.

• If the button state is logically down, the “MouseOverDown” image (if any) shall be displayed. If there is no “MouseOverDown” image, the “Down” image (if any) shall be displayed. If there is no “Down” image, no image shall be displayed.

• The control has the capability to display text layered on top of the images. The text is displayed regardless of which image is being displayed. The text must be provided by the existing UpLabel, DownLabel, TextColor and Font parameters. If the UpLabel and DownLabel parameters are images, then they will not be used if the ImageSet parameter has prevented old GUIButton rendering.

• The following parameters do not affect how the new images are displayed:

Brush, HighlightPen, ShadowPen, Sides.

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

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:

The following illustrates how to create a momentary button used as an action trigger for a script. Notice that in this particular example bitmaps are used to label the button rather than text:

If GUIButton(10, 90, 100, 50 { Outline of the button },

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

0, 0, 1, 0 { No movement; visible },

64 + 4, 1, 0 { Triggered by left mouse

button release },

GetSystemColor(15){ Windows button face color },

GetSystemColor(20){ Windows button highlight color},

GetSystemColor(16){ Windows button shadow color },

GetSystemColor(18){ Windows button text color },

0, 0 { Windows standard attributes },

MakeBitmap("StartPict"), MakeBitmap("StopPict")

{ Up and down labels },

0, 0, 1, 2 { No variable assignment });

[

...

]

This statement is a latching button that sets the value of the variable called pos:

GUIButton(10, 90, 100, 50 { Outline of the button },

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

0, 0 { No movement },

1, 0 { Visible; reserved },

64 + 4, 1, 0 { Left mouse button release },

7, 15, 8, 0 { Colors },

6, 0 { Number of sides; reserved },

"Start", "Stop", 0 { Up and down labels },

1, ! pos, pos { Latching });

To create a set of radio buttons, the latching buttons should be used in conjunction with a script as follows:

If GUIButton(10, 60, 50, 50 { Outline of the button },

1, 1, 1, 1, 1, 0, 0 { No scaling/movement },

1, 0, 68, 1, 0 { Visible; selectable },

7, 15, 8, 0, 4, 0 { Colors; sides },

"Pos 1", "Pos 1", 0 { Labels },

1, ! pos1, pos1 { Latching });

[

pos2 = 0;

]

If GUIButton(10, 61, 50, 51 { Outline of the button },

1, 1, 1, 1, 1, 0, 0 { No scaling/movement },

1, 0, 68, 2, 0 { Visible; selectable },

7, 15, 8, 0, 4, 0 { Colors; sides },

"Pos 2", "Pos 2", 0 { Labels },

1, ! pos2, pos2 { Latching });

[

pos1 = 0;

]

To situate a button at a position given by left, bottom, right, top:

If GUIButton(0, 1, 1, 0 { Unit bounding box },

1 - (left) { Left scaling }, bottom { Bottom scaling }, right { Right scaling },

1 - (top) { Top scaling },

1, 0, 0 { No overall scaling/movement },

1, 0, 68, 2, 0 { Visible; selectable },

7, 15, 8, 0, 4, 0 { Colors; sides },

"Start", "Stop", 0 { Up and down labels },

0, 1, 2 { No variable assignment });

[

...

]

To use the ImageSetStruct structure, you can either set the images in one statement like so: (note that in a script application, \System must be prefixed)

ButtonImages = \ImageSetStruct(MakeBitMap(“UpButton.png”),
                                MakeBitmap(“DownButton.png”),
                                MakeBitmap(“HoverUpButton.png”),
                                MakeBitmap(“HoverDownButton.png”),
                                MakeBitmap(“DisabledButton.png”);

You can also set the images in multiple statements (which is recommended as better practice):

ButtonImages                    = \ImageSetStruct();
ButtonImages\UpImage            = MakeBitMap(“UpButton.png”);
ButtonImages\MouseOverUpImage   = MakeBitmap(“HoverUpButton.png”);
ButtonImages\DownImage          = MakeBitmap(“DownButton.png”);
ButtonImages\MouseOverDownImage = MakeBitmap(“HoverDownButton.png”);
ButtonImages\DisabledImage      = MakeBitmap(“DisabledButton.png”);

Having initialized the structure as shown, you can then use it in a GUIButton:

GUIButton(10, 90, 100, 50     { Outline of the button },
           1, 1, 1, 1, 1      { No scaling },
           0, 0, 1, 0         { No movement; visible },
           64 + 4, 1, 0       { Left mouse button release },
           GetSystemColor(15){ Windows button face color },
         GetSystemColor(20){ Windows button highlight color},
           GetSystemColor(16){ Windows button shadow color },
           GetSystemColor(18){ Windows button text color },
           0, 0               { Windows standard attributes },
           “Up”, “Down”,      { Up and down labels },
           0, 0, 1, 2         { No variable assignment },
           ButtonImages, “Click.WAV”);