GUIButton

(Engine-Level Function)

Description: Draws a push-button in a window. Can return a Boolean TRUE when selected by a mouse button or when the <ENTER> key is pressed after focus has been acquired.
Returns: GUI Object Return Codes
Usage: Steady State only.
Function Groups: Graphics
Related to: BitmapInfo | Crop | Brush | GUIBitmap | ImageArray | ImageSweep | MakeBitmap | ModifyBitmap | NextFocusID | Normalize | Pen | Rotate | Trajectory | VStatus | ZButton
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[, ImageSet, ClickSound])
Parameters:  
LeftReference
A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.
BottomReference
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
A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.
TopReference
A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.
ScaleLeft
Required. 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
Required. 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.
ScaleRight
Required. 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.
ScaleTop
Required. 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.
ScaleWhole
Required. 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
Required. 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
Required. 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
Required. 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

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

Value

Locator Buttons

0

No button combination will activate this graphic

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 example, 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 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

Required. Any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is zero, this graphic will not immediately have focus, but will work in any other manner.

This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.
FocusTrigger
Required. Any logical expression. If FocusTrigger changes from a valid false to a valid true, this graphic will attempt to obtain focus.
Brush
Required. Used to fill the background of the button. Any of the following may be used:
HighlightPen
Required. Used to draw the highlight sides of the button, one pixel wide. Any of the following may be used:
  • a Pen object (in which case the pen's width value may be used)
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
ShadowPen
Required. . Used to draw the shadowed sides of the button, one pixel wide. Any of the following may be used:
  • a Pen object (in which case the pen's width value may be used)
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
TextColor
Required.Used to set the color of the text that appears on the button. Any of the following may be used:
  • a Pen object (only the color will be used)
  • a palette index VTScada Color Palette
  • a system color Constants for System Colors
  • an RGB string with optional Alpha value in the format, "<AARRGGBB>", or "<RRGGBB>", where AA, RR, GG and BB are hexadecimal digits.
Sides

Required. Any numeric expression giving the number of sides on the button. If this value is 0, the button will have four sides. If not zero, the value must be greater than or equal to 4.

In general, the use of non-rectangular shapes is discouraged. When the button is selected, a rectangular outline will be shown.
Reserved
Reserved for future use, set to 0.
UpLabel

Required. An expression returning a Bitmap value, or text. If text, it will be drawn in the font set by the Font parameter. Both text and images will be centered on the button while it is up. Images will be scaled to fill the button area. To use an image file, use: MakeBitmap("relative\path\to\file") Any of the recognized image formats may be used. The file extension is not required.
DownLabel
Required. An expression returning a Bitmap value, or text. If text, it will be drawn in the font set by the Font parameter, Both text and images will be centered on the button while it is down. Images will be scaled to fill the button area.
Font

Required. A Font value, or the number zero. Set as "0" to use the default system font.
DownValue
Required. 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
Required. 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
Required. 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

A set of image 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" };
  DownImage        { Image to use when the button is "down" };
  MouseOverUpImage { Image to use when the mouse is over an
                        "up" button };
  MouseOverDownImage { Image to use when the mouse is over
                        a "down" button };
  DisabledImage    { Image to use when user actions on
                        the button are disabled };
]

Examples are provided later in this topic.
ClickSound 
The name of a .wav file that is to be played when the button is clicked. The extension ".wav" will be appended if not provided in the parameter. This file will not be played while another sound (for example, an alarm,) is sounding.
Comments:

GUIButtons drawn on a page cannot be modified using ribbons or properties dialogs. Editing can only be done in code.

Standard practice is to use WinButtons if displaying plain text labels, and to use images for the labels when using a GUIButton.

There are three basic types of buttons:

  • Momentary
  • Toggle (or latching)
  • 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 UpValue 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 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. When the button is focused it may then be selected via the <CR> key on the keyboard.

Because 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 predefined structure varies depending on whether you are working in a script application or a standard VTScada application.

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

The following set of rules defines the ImageSet behavior...
In the absence of the ImageSet parameter or, if that parameter is present but is not valid, the GUIButton statement will display a set of predefined renderings.
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 image values.

You may declare your own structure or use one of the pre-created structures in VTScada. For 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, click-able 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.
  • 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 ability 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 1st 42 pixels of a VTScada application will be obscured by the title bar, if present. Will not display tab characters.

Example:

The following illustrates how to create a momentary button used as an action trigger for a script. Notice that in this particular example images are used to label the button rather than text. The image files are assumed to be in the Bitmaps folder, while the code for this module is in the Pages folder.

Examples often use English text in labels so that you can make a copy as a starting point when building your own version.
Better practice is to replace the text with phrase keys, and the \GetPhrase() function.

  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("..\Bitmaps\StartPict"),
               MakeBitmap("..\Bitmaps\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 },
            0, 0 { Number of sides; reserved },
            MakeBitmap("..\Bitmaps\StartPict"),
            MakeBitmap("..\Bitmaps\StopPict") { Up and down labels },
            \_DialogFont { Font },
            1, ! pos, pos { Latching });

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

[ { variable declaration and initialization }
  Left = 10;
  Right = 100;
  Top = 50;
  Bottom = 140;
]

{ ... state code ... }
  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 },
               MakeBitmap("..\Bitmaps\StartPict"),
               MakeBitmap("..\Bitmaps\StopPict") { Up and down labels },
               0, 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. These file names assume that the files are in the same folder as the module.)

  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");