WinButton

(Engine-Level Function)

Description Windows native button.
Returns Integer
Usage Steady State only.
Function Groups Graphics,  Window
Related to: ZButton
Format: WinButton(X0, Y0, X1, Y1, Style[, Text, FocusID, Font, ToggleVal, Bitmap, BitmapJustify])
Parameters  
X0, Y0, X1, Y1   
Required. Any four numeric values, locating the edges of the button in the window.  To ensure consistent sizing, these parameters should be set using constants.  A commonly-seen example follows:

WinWd-2*BtnWd-2*Space, WinHt-Space, WinWd-BtnWd-2*Space, WinHt-BtnHt-Space
Style
Required. Defines the button's appearance. A binary OR operation is done with a style number and the extra style bits shown in the following table.
If the style number is 0, the button will have a normal appearance. If the style number is 1, the button will be a toggling button. Further style refinements are as follows:

Value

Meaning

0x00000100

orient text to the left

0x00000200

orient text to the right

0x00000400

orient text to the top

0x00000800

orient text to the bottom

0x00002000

allow multiple lines of text on button

0x10000000make the button invisible, but still respond to clicks

(See: Bitwise Parameters & Operations)
Text

An optional expression for text to display on the button. Use the \GetPhrase function for multilingual applications.

Will not display tab characters.
FocusID  
An optional parameter from 0 to 32767 indicating the focus id. If Invalid or "0", no user interaction is permitted.
Font   
An optional parameter specifying the font to use for text.
Note that underlining is not supported.
ToggleVal   

An output value, whose meaning depends on the button style.

  • In a toggling button, ToggleVal is set to the toggle state of the button - 1 for pushed-in and 0 for not-pushed-in.
  • For this button style, ToggleVal can also be used to change the state of the button programmatically.
  • In a normal button, ToggleVal is purely an output parameter, indicating whether the button is currently being pressed. NOTE: This behavior does not apply on the Anywhere client, where ToggleVal will not be set.
Bitmap   
An optional parameter specifying an image to use on the button. May be used with or without a value for the Text parameter. See example.
BitmapJustify   
An optional numeric value, specifying how the image is aligned on the button.  Possible values are as follows:

Value

Meaning

0

align image to the left (default)

1

align image to the right

2

align image to the top

3

align image to the bottom

4

align image to the center (not a valid option if text is also provided for the button)
Comments: None.

Example:

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.

Plain button, with monitoring of the current toggle state.

  If WinButton(232, 148, 412, 100,
               0                      { normal appearance }, 
               Concat("Press Me ", ButtonPresses) { label },
               1                { focus id enables button },
               0                    { default system font },
               ToggleVal                  { monitor state});
  [
    ButtonPresses++;
  ]

Button with image

  MyImage    = MakeBitmap("..\Bitmaps\warning symbol.bmp", 12, 9);
  If WinButton(232, 148, 412, 100,
               0                      { normal appearance }, 
               Concat("Press Me ", ButtonPresses) { label },
               1                { focus id enables button },
               0                    { default system font },
               Invalid                { no ToggleVal used },
               MyImage     { image displayed in the button});
  [
    ButtonPresses++;
  ]