# 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:

`ID`	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 `ID` is omitted, the SimpleHMI client will automatically allocate one, starting at number 100 and working downwards. If you plan to change the button's parameters, say to dynamically change its text, you must nominate a specific button. Note that all buttons are de-allocated by `HideAllButtons`.
`Row`	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.
`Col`	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.
`Height`	The height of the button in multiples of the character height of the current font.
`Width`	The width of the button in multiples of the character width of the current font.
`"text"`	The text to be displayed on the button. This must be enclosed in quotation marks. Non-printing characters are not possible
`Mode`	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: `#HMI ButtonEvent(,5,9,3,20,"Touch me",R2,evButton) ;Draw SimpleHMI button, declare its handler` 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.
`ClickHandler`	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
`5`	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
`-5`	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
`0`	The top character row	The left-most character column
`-0`	The bottom character row	The right-most character column
`0.25`	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.
`-0.25`	One quarter of the screen height from the bottom.	One quarter of the screen width from the right.
`C`	The top-bottom centre of the screen.	The left-right centre of the screen.
`C+5`	Five character rows down from the centre	Five character widths right from the centre.
`C-5`	Five character rows up from the centre	Five character width left from the centre.
`C+.25`	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.
`C-3.25`	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`	5 character rows in height	5 character rows in width
`0.25`	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.