# ButtonEvent2()
| Valid For | #HMI |
|---|---|
| Applies To | HMI430, HMI700 and derived products |
This instruction creates a touchable button, drawn on the LCD.
Firmware 4.2
Note: As of 27 February 2015, a new version of SPLat/PC and HMI430 firmware have been released. If you upgrade one, you must upgrade the other, otherwise #HMI ButtonEvent2() may not work.
Function Prototype
# ButtonEvent2(
id:ID,
x:Col,
y:Row,
w:Width,
h:Height,
t:"Text",
m:"Mode",
z:Z-Index,
li:"LabelImageFilename",
ri:"ReleaseImageFilename",
pi:"PressedImageFilename",
rf:ReleasedForegroundColour,
rb:ReleasedBackgroundColour,
pf:PressedForegroundColour,
pb:PressedBackgroundColour,
ev:EventHandler )
Note that almost all of the parameters below support Formatting Functions.
| Parameter | Option | Description |
|---|---|---|
| id | optional | Button Identifier. Numerical id between 0 through 255 – in decimal format only. May be used to identify the button after it has been created and adjust parameters (like move its position). Will also be passed to the application when the button is pressed. Can be set using any of the Byte Formatting methods. |
| x | mandatory | Position of the left edge of the button, relative to the whole screen (not the current bounding box). Any of the positioning methods may be used. |
| y | mandatory | For character coordinates, this is the baseline of the first line in the button (so it lines up with SetCusor(). For pixel coordinates or %, this is the top edge of the button. All are relative to the whole screen (not the current bounding box). Any of the positioning methods may be used. |
| w | depends | Width, either in characters, % (of whole screen) or pixels. If the button uses images, then this parameter is not used. Any of the positioning methods may be used. A width of zero will delete the current instance of the button. |
| h | depends | Height, either in characters, % (of whole screen) or pixels. If the button uses images, then this parameter is not used. Any of the positioning methods may be used. A height of zero will delete the current instance of the button. |
| t | optional | Text to display in the button. May be multiple line, just use “\n” or “\r” to move to the next line. Text is always automatically centered, both vertically and horizontally. Buttons support a maximum of 31 characters. |
| m | optional | Button mode, see table below |
| v | optional | Numerical value that will be passed to the application when the button is pressed. Unlike the ID, this does not have to be unique. |
| z | optional | Sets the z-index of the button. Default is 96. Refer to the z-index page for more information. |
| li | optional | A “label” image. This is an image that is displayed on top of both the pressed and released buttons. |
| ri | optional | The “released” image, drawn when the button is not being pressed. |
| pi | optional | The “pressed” image. |
| rf | optional | Foreground colour (of the text) when the button is released. Defaults to the current colour. Refer to Colour Values. |
| rb | optional | Background colour (of the button) when the button is released. Defaults to the current colour. Not used if the button is an image. Refer to Colour Values. |
| pf | optional | Foreground colour (of the text) when the button is pressed. Defaults to the current colour. Refer to Colour Values. |
| pb | optional | Background colour (of the button) when the button is pressed. Defaults an automatically calculated darker or lighter version of the released background colour. Not used if the button is an image. Refer to Colour Values. |
| ev | mandatory | The subroutine that will be called when the button is pressed (or held, or released if configured by the mode parameter). Remember to Return when you’ve finished handling the button. It’s a bad idea to Pause or Yield in a button subroutine as no other button will be reported until you return. |
Description
You MUST execute RunTasksForever to have MultiTrack multi-tasking running for buttons to work. Without MultiTrack your buttons will be displayed but the button subroutine will not be called when the button is pressed.
Controllers support a maximum of 80 buttons at a time, so best practice is to perform a Reset() before drawing a new screen to erase all the old buttons. Specific buttons can be erased simply by specifying the button ID with a width or height of 0.
Buttons may be positioned by characters, fraction of the screen or pixels, refer to the positioning page for details. Any of the formatting functions may be used on any of the parameters. For example, this button will be drawn pressed (On.png) if X is zero and it will be a member of group 0:
#HMI ButtonEvent2( id:22, x:45%, y:207px, m:(s(=x,"p0","p1"), "g0"), ri:"Off.png", pi:"On.png", ev:_UIFSsubBtnFeature )
Text in a button will use the current font, so be sure to call SetFont() to select the font before calling ButtonEvent2(). A button’s font cannot be changed after the button has been created.
Note: When using an image whose colour is not completely solid on a non-transparent background, the underlying firmware automatically draws a border around the image.
Button Information
The button subroutine can be a simple affair, code that does something when a specific button is pressed. However, if you need to know if the button has been pressed, held or released, or if you need to know the ID of the button, or your want the x,y coordinate of the press, then you’ll want to include this file in your project:
Calling UIsubGetButton will return a bunch of things relating to the button event. Refer to the ui_utils.spt page for more information.
Mode
The mode allows button to be configured in various way as per this table.
| Parameter | Value | Description |
|---|---|---|
| a | alpha (0-255 or 0%-100%) | Fade the button. Alpha is in the range 0 thru 255 or “0%” thru “100%”. 255 or 100% means draw it solid, 0 or 0% means hide it. |
| b | 0/1 | Report both button presses and button releases. The ui_utils.spt file will help you decipher the button events. “b1” means report both, “b0” means only report press (this is the default). |
| d | 0/1 | Disable or enable the button. “d1” means the button is disabled and the event handler won’t be called when it is pressed. “d0″ means enable the button. Combine this with h, or even better, something like a50% to draw a disabled button. Eg, m:”d1a50%” would draw a disabled faded button. |
| g | group (0-255) | Button belong to a group of buttons, only one of which may be active. The “group” the the group number, 0 thru 255. |
| h | 0/1 | Hide or un-hide the button. “h1” means hide the button, “h0” makes it visible. Hidden buttons can still be pressed, they just won’t be displayed. Actually, this is a shortcut for a (alpha), h1 = a0% and h0 = a100%. |
| m | 0/1 | Button is a manual button. This means it won’t beep and will not automatically be drawn in a pressed state when pressed. The application may beep and control the button state. However the event handler will always be called when the button is pressed. “m1” means button is manual, “m0” means it is automatic (this is the default). |
| p | 0/1 | Draw button pressed (“1”) or released (“0”). |
| r | rate (0-20) | Button repeat rate, where the “rate” value is repeats per second. For example, “r10” would call the button event handler 10 times per second while the button is held. Note there is a delay of 0.5s between the initial press and first repeat. Thereafter, the specified repeat rate will be used. |
| s | sensitivity (0-255 or 0%-100%) | Buttons may be drawn a circles or other rectangular shapes and only the solid part of the button will respond to a press. So pressing outside the circle won’t respond. This works by looking at the alpha value of the pixel being pressed, if it’s less than 128 then the press will be ignored. However this can cause problems if you button has transparent sections that should respond to a press. Setting the sensitivity allow you to specify what level of alpha should respond to a press Values are 0 thru 255 or 0% thru 100%, so saying 0 means fully transparent sections should respond. |
| t | 0/1 | Button is a toggle button, meaning press on, press off. The button subroutine will be called for both the ‘press on’ and the ‘press off’. UIsubGetButton in ui_utils.spt is able to say whether it’s the on or off press. As of version 4.3, may be combined with “manual” in which case pressing a “released” button will report “pressed” and a “pressed” button will report “released”. Note though the button will NOT change state as it’s in manual mode. “t1” means this is a toggle button, “t0” means it’s not (this is the default). |
| w | delay (seconds) | For a repeating button, this is the time to wait before the auto-repeat starts. By default, there is a delay of 0.5 seconds. This is most useful for “sliders” where it’s desirable to have no delay. |
Examples
#HMI ButtonEvent2( x:C-5, y:-3, w:10, h:3, t:"My First\nButton", ev:subMyButtonHandler )
Draws a horizontally centered button on the bottom of the screen with 2 lines of text. Calls subMyButtonHandler when it’s pressed.
#HMI ButtonEvent2( id:0, x:102px, y:175px, m:"r10", ri:"BtnUpArrowUp.dif", pi:"BtnDnArrowUp.dif", ev:subBtnUpDown )
Draws a graphic button (note width and height will be calculated automatically). subBtnUpDown is called when the button is pressed and after a half second delay, 10 times per second while the button is held.
#HMI ButtonEvent2( id:5, x:10, y:10, w:7.8, h:1.8, t:"Test", ev:subTestButton )
Creates a button, note we’ve given it an ID so we can refer to it later, so now:
#HMI ButtonEvent2( id:5, m:"d1a50%" )
will disable and fade the button, and
#HMI ButtonEvent2( id:5, m:"d0h0" )
will enable and unfade it.
Destroy the button.
#HMI ButtonEvent2( id:5, w:0 )
Note you should call Reset() to destroy all buttons.
Want a secret button, one that’s not visible on the screen?
#HMI ButtonEvent2( x:0, y:0, w:5, h:5, m:"h1w5.0r1m1", t:"", ev:subSecretButton )
This will create a hidden button, but you’ll need this subroutine to act on the long press only:
subSecretButton:
GoSub UIsubGetButton ;get extra button info
GoIfXne UIkBtnHeld,Return ;ignore this call if it's not a "held" event
KBeep ;ah, it is held, so beep
GoSub ubDoTheSecret ;and go do the secret thing
Return
In the button mode, “h1” means it’s hidden, “w5.0” means it will take 5 seconds for the held event to occur, “r1” means we want held events and finally “m1” means it won’t beep when pressed (so it remains our little secret). The subSecretButton subroutine will only do the secret thing if the button has been held, and as w is 5.0 the user must hold the button for 5 seconds. This will keep the button a secret and prevent accidental activation.