Using Key and Touch Events
This section will discuss how interactive scripts receiving user inputs via key and touch events can be created.
The two Lua widgets EventDemo and LibGUI are provided on the SD card content for color screen radios. EventDemo is just a small widget showing off how key, and especially touch events, can be used. LibGUI contains a globally available library, and a widget showing how the library can be used by other widgets. This section will discuss these two widgets for color screen radios, but generally, what is stated about key events here also applies to the run
function in Telemetry and One-Time scripts.
EventDemo Widget
This widget uses the design pattern for saving memory by loadable files discussed in the previous section, so all of the action takes place in the file loadable.lua. The following code listing is an outline of the refresh
function with comments explaining what is going on.
LibGUI
This is a widget that comes with a global library. Since all widgets are loaded whether or not they are being used, global functions declared in the body of a widget script will always be available. It is not necessary to setup the widget to use the library, and the only purpose of the widget is to show how LibGUI
can be used to create apps.
The library is implemented in the loadable file /WIDGETS/LibGUI/libgui.lua. The widget that demonstrates how to use the library is implemented in the loadable file /WIDGETS/LibGUI/loadable.lua. The file /WIDGETS/LibGUI/main.lua contains a global function that loads the library and the standard functions needed for a widget.
The global function loadGUI()
returns a new libGUI
object. This object can be used to create new GUI
objects, which are used to create screens with elements like buttons, menus, labels, numbers that can be edited, and timers.
libGUI Properties
libGUI
has the following properties controlling general settings for the library.
libGUI.flags
These are default drawing flags to be applied if no flags are given at creation of screen elements.
Note: these flags should not contain color values, as colors are added by the following.
libGUI.colors
This is a table of the colors used for drawing the GUI elements. These are all theme colors by default, but they can be changed for the libGUI
instance without changing the theme colors anywhere else.
libGUI.widgetRefresh
A function f()
to draw the zone of the screen in widget mode. It takes no arguments.
libGUI Functions
libGUI.match(x, ...)
This is a small utility function that returns true
if the first argument x
matches any of the following arguments. It is useful for comparing values of event
, e.g. if we want to test if the user pressed either of the following buttons, we can use:libGUI.match(event, EVT_VIRTUAL_ENTER, EVT_VIRTUAL_EXIT, EVT_VIRTUAL_MENU)
libGUI.newGUI()
This is the main function that creates a new GUI
object. If an application has different screens, then a GUI
object is created for each screen.
GUI Object Properties
GUI.fullScreenRefresh
A function f(event, touchState)
to draw the screen background in full screen mode. The GUI elements are drawn afterwards on top.
GUI.prompt
A GUI (or another table with a function run(event, touchState
). When this is set, the GUI will first be drawn, and then it will call prompt.run(event, touchState)
instead of running itself. That way, the prompt
can implement a modal prompt window.
GUI Object Functions
GUI.run(event, touchState)
Redraws the screen and processes key and touch events. It can directly replace a widget's refresh
function, or it can be called by refresh
.
GUI.SetEventHandler(event, f)
Sets a function f(event, touchState)
to handle an event. If no GUI element is being edited, then this can trap events before they are passed to the GUI, e.g. to press EXIT to go back to the previous screen. If f
is nil
, then the event handler is removed.
GUI Screen Elements
The screen elements are drawn in the order that they are added to the GUI, and touch events are sent to the first element that covers the touched point of the screen. GUI elements therefore should never overlap.
There are some common properties that can be set for all or most of the GUI elements.
element.disabled = true
prevents the element from taking focus and receiving events, and disabled buttons are greyed out.element.hidden = true
in addition to the above, the element is not drawn.element.title
can be changed for elements with a title.element.value
can be changed for elements with a value.element.flags
drawing flags for the element's text. If no flags were given at element creation, it defaults toGUI.flags
.elements.blink
will make non-button elements blinkelements.invers
will make non-button elements draw in inversed colors.
The various screen elements are added to the GUI with the functions described below. The functions all add the element to the GUI and returns a reference so the element subsequently can be accessed by the client.
GUI.button (x, y, w, h, title[, callBack] [, flags])
Add a button to the GUI.
When tapped, it calls callBack(self)
so a call back function can tell which button activated it.
GUI.toggleButton(x, y, w, h, title, value[, callBack] [, flags])
Add a toggle button to the GUI.
The value
is either true
or false
.
When tapped, it calls callBack(self)
so a call back function can tell which toggle button activated it, and what self.value
is.
GUI.number(x, y, w, h, value[, callBack] [, flags])
Add an editable number to the GUI.
The value
can be either a number or text. By setting the value to a text, it can be shown that the number is not present e.g. by "- -" or similar.
When tapped, the number will go to edit mode. In edit mode, events are passed to callBack(self, event, touchState)
. Thereby, the call back function can use events to edit the number, e.g. sliding a finger up and down can increase and decrease the value. You can look in the LibGUI widget's loadable file for an example of this.
GUI.timer(x, y, w, h, tmr[, callBack] [, flags])
Add a timer to the GUI.
If no value
is present, then the model timer tmr
will be shown. If value
is a number, then it indicates the time in seconds, and it will be shown as MM:SS. The value
can also be text, e.g. "- - : - -" to show that the timer is disabled.
When tapped, the timer will go to edit mode, as described above for number.
GUI.label(x, y, w, h, title[, flags])
Add a text label to the GUI.
The label does not respond to any events, but its title
and flags
can be changed.
GUI.menu(x, y, visibleCount, items[, callBack] [, flags])
Add a scrollable menu to the GUI. This function returns a table with each of the menu's line elements.
visibleCount
is the number of visible menu items.
items
is a table with the menu item texts.
When a menu item is tapped, it calls callBack(self)
. Each menu element has a field self.idx
giving the index in the menu, and this can be used by callBack
to see which menu item was selected.
Notice that the menu's width is decided by the item texts and the font flags, and the height is decided by visibleCount
and the font flags.
GUI.dropDown(x, y, w, h, items, selected, callBack, flags)
Add a field with values that can be selected on a drop down menu.
items
is a table with the items that can be selected from.
selected
is the index of the initially selected item.
When an item has been selected, it calls callBack(self)
. The index of the selected item is given by self.selected
.
GUI.gui.horizontalSlider(x, y, w, value, min, max, delta, callBack)
Adds a horizontal slider that starts at (x, y)
and has the width w
.
value
is the initial value, and min - max
is the interval of values that can be selected with step size delta
.
When the value is changed, callBack(self)
is called, and the value is given by self.value
.
GUI.gui.verticalSlider(x, y, w, value, min, max, delta, callBack)
The same as the above, just vertical.
Last updated