# ButtonEvent(ID, Row, Col, Height, Width, "text"{, Mode}, ClickHandler) hash function
Valid for use with hash command: HMI
Name:Value Pairs are not supported
Implemented on the following platforms: Android, Windows.
Mode
is optional
Display a button at the specified screen location, with a text label. Raise the specified Event (execute a GoSub
to the given line label) when the button is clicked.
The parameters are:
| The button number to use. The HMI client contains a fixed number of buttons that can be re-used on different screens. You may nominate which of the buttons to use. Initial releases of the SimpleHMI for Android and Windows has 100 buttons, numbered 1-100. See the latest HMI documentation for details. If |
| The screen row where the top of the button is to be positioned. This refers to character rows in the prevailing font size. Row numbers are 0 based, so the top row is row 0. |
| The screen column where the left of the button is to be positioned. This refers to character columns in the prevailing font size. Column numbers are 0 based, so the start of each line is 0. |
| The height of the button in multiples of the character height of the current font. |
| The width of the button in multiples of the character width of the current font. |
| The text to be displayed on the button. This must be enclosed in quotation marks. Non-printing characters are not possible |
| The optional Mode parameter allows you to specify an autorepeat behaviour; so long as the user "holds down" the button it will generate regular click events. This is specified by the letter R followed optionally by the number of clicks per second. The default rate if not specified is 5. Example:
This will generate 2 clicks per second. If I leave out the '2', I'll get 5 clicks per second The second click is delayed twice as long as subsequent clicks, but up to a maximum of 1 second. This gives the effect of Click - delay - click - click - click ... The repeat rate must not be too fast for the system to handle. System loading is a function of how much work the host must do for each click event, plus the data transmission time of any response sent back to the SimpleHMI client. If you want a fast rate you should test carefully. In particular look out for evidence of clicks continuing to be processed after the button has been released. The system can buffer up a number of messages in serial buffers. |
| You must place a subroutine at a program line with this label, which handles the click of the button |
Notes:
- A given button can be re-used any number of times on different screens.
- The click handler will be run automatically when the button is clicked.
- The button can only be clicked if it is visible.
- A program can contain a maximum of 127 HMI related events
In addition to being simple numbers, the row/column coordinates may also be specified in relative or proportional terms. The following table illustrates the possibilities.
Format (example) | As a row specifier | As a column specifier |
---|---|---|
| Row number 5 from the top, counting from 0. This can be a fractional number such as 5.5 | Column number 5 from the left, counting from 0 |
| Row 5 from the bottom, counting from 0. This can be a fractional number such as -5.25 | Column 5 from the right, counting from 0 |
| The top character row | The left-most character column |
| The bottom character row | The right-most character column |
| One quarter of (0.25 times) the screen height from the top. Fractional number between -1 and +1 are interpreted as a fraction of the screen. | One quarter of the screen width from the left. |
| One quarter of the screen height from the bottom. | One quarter of the screen width from the right. |
| The top-bottom centre of the screen. | The left-right centre of the screen. |
| Five character rows down from the centre | Five character widths right from the centre. |
| Five character rows up from the centre | Five character width left from the centre. |
| One quarter character row down from the centre. After a "C" all numbers are interpreted as multiples of the character pitch. | One quarter character width right from the centre. |
| Three and a quarter character rows up from the centre. After a "C" all numbers are interpreted as multiples of the character pitch. | Three and a quarter character widths left from the centre. |
In addition to being simple numbers, the width and height coordinates may also be specified in relative or proportional terms. The following table illustrates the possibilities.
Format (example) | As a height specifier | As a width specifier |
---|---|---|
| 5 character rows in height | 5 character rows in width |
| One quarter of (0.25 times) the screen height. Always calculated as a full number of rows, always rounded down, but forced to be at least 1. | One quarter of (0.25 times) the screen width. Always calculated as a full number of columns, always rounded down, but forced to be at least 1. |