Widget scripts are avaiable on radios equiped with color LCD. They are designed to run constantly in the background performinfg various task. Widget scripts are mostly used to extend EdgeTX functionality via Widgets that are places by user on Main Views. They are equivalent of Telemetry Scripts on radios equiped with B&W LCD.
Most of the time, widget scripts show some info in a Widget's zone in one of the user defined Main Views. They cannot receive direct input from the user via key events with exeption of being displayed in so called Full Screen mode. Full screen mode can be entered by selecting the widget, pressing ENTER and selecting Full screen from the widget's contextual menu, or by double tapping the widget on radios with a touch screen. Full screen mode can be exited by long pressing the EXIT (RTN) button, or by calling the Lua function lcd.exitFullScreen().
Each model can have up to nine Main Views, with up to 8 widgets per screen, depending on their size and layout. Each instance of a widget has his own options table.
{% hint style="warning" %}
Widget scripts are only available on radios with color LCD screens, such as e.g. FrSky X10 or X12, Radiomaster TX16S, Jumper T16 or T18, Flysky NV14., etc.
Read more about radios.
{% endhint %}
All widget scripts on the SD card are loaded into memory when the model is selected, even widgets that are not used. This has the side effect that any global functions defined in a widget script will always be available to other widget scripts. It also means that any Widget Script placed in proper location on the SD card will consume part of the radio's memory - even if it is not being used.
{% hint style="warning" %} It is important to either keep Widget Scripts small, or to use Lua's loadScript() function to load code dynamically {% endhint %}
Script executes until:
- it misbehaves (e.g. too long runtime, run-time error, or low memory)
- One-Time script is running. When One-time script finishes execution, Wigdet Script resumes execution.
Widget scripts are located on the SD card, each one in their specific folder:
/WIDGETS/<folder name>/
{% hint style="warning" %} Widget script folder name length must be 8 characters or less {% endhint %}
Widget script name is constant and has to be named main.lua
{% hint style="info" %}
Example of proper Widget script placement to be registered by EdgeTX as valid Widget script available to user in Widgets selection menu:
/WIDGETS/MYWGT/main.lua
{% endhint %}
{% hint style="info" %} Try to use unique folder name. In case of naming clash, previously installed widget will be overwritten. {% endhint %}
Every Widget Script must include a return statement at the end, defining its interface to EdgeTX. This statement returns a table with the following fields:
| Field | Type | Required | Desctiption |
|---|---|---|---|
| name | string | true | This variable holds a name that is displayed to user as Widget scripts name in available Widgets list. |
{% hint style="warning" %}
The name length must be 10 characters or less.
{% endhint %}
| Field | Type | Required | Desctiption |
|---|---|---|---|
| options | table | false | Options table is to store Widget's options available to EdgeTX user via Widget's Settings menu. To see valid options read Widget Options Constants. |
{% hint style="info" %}
options table is passed to create function when invoked and then stored in Lua. Changing options table values while Widget script is running has no effect. This table is designed to be changed with EdgeTX system menus.
{% endhint %}
{% hint style="info" %}
If options is changed by the user in the Widget Settings menu, then update will be called with a new options table, unaffected by any changes made by Lua code to the old options table.
{% endhint %}
| Field | Type | Required | Desctiption |
|---|---|---|---|
| create | function | true | function is called once when the widget instance is registered (started). |
Parameters
| Parameter | Decription |
|---|---|
| zone table | This parameter will hold visible dimensions of Widget (height & width) |
| options table | Initial options table as described above |
Return values
| Returns | Description |
|---|---|
| widget table | Create function will return table that has to be later passed to update , background & refresh functions allowing to access widget's unique variables |
{% hint style="info" %} The size of the widget's zone area is as follows:
- Full screen mode:
LCD_WbyLCD_H - Not full screen mode:
zone.wbyzone.h(updated if screen options are changed) {% endhint %}
{% hint style="info" %}
If local variables are declared outside functions in the widget script, then they are shared between all instances of the widget. Therefore, local variables that are private for each instance should be added to the widget table in the create function before returning the widget table to EdgeTX.
{% endhint %}
| Field | Type | Required | Desctiption |
|---|---|---|---|
| update | function | false | This function is called when Widget's Settings are changed by the user. It is mostly used to modify Widget Script variables or behaviour basing on options values entered by user. |
Parameters
| Parameter | Decription |
|---|---|
| widget table | Widget's table returned by create function, decribed above. |
| options table | Initial options table as described above |
Return values
none
| Field | Type | Required | Desctiption |
|---|---|---|---|
| background | function | false | This function is called periodically when the widget instance is NOT VISIBLE. |
Parameters
| Parameter | Decription |
|---|---|
| widget table | Widget's table returned by create function, decribed above. |
Return values
none
| Field | Type | Required | Desctiption |
|---|---|---|---|
| refresh | function | true | This function is called periodically when the widget instance IS VISIBLE. |
Parameters
| Parameter | Decription |
|---|---|
| widget table | Widget's table returned by create function, decribed above. |
| event number |
See Key Events. |
| touchState table | This parameter is only present when radio is equiped with touch interface and
|
Return values
none
{% hint style="info" %}
if you want background function to run when the widget is visible, then call it from refresh function.
{% endhint %}
local name = "WidgetName"
-- Create a table with default options
-- Options can be changed by the user from the Widget Settings menu
-- Notice that each line is a table inside { }
local options = {
{ "Source", SOURCE, 1 },
-- BOOL is actually not a boolean, but toggles between 0 and 1
{ "Boolean", BOOL, 1 },
{ "Value", VALUE, 1, 0, 10},
{ "Color", COLOR, ORANGE },
{ "Text", STRING, "Max8chrs" }
}
local function create(zone, options)
-- Runs one time when the widget instance is registered
-- Store zone and options in the widget table for later use
local widget = {
zone = zone,
options = options
}
-- Add local variables to the widget table,
-- unless you want to share with other instances!
widget.someVariable = 3
-- Return widget table to EdgeTX
return widget
end
local function update(widget, options)
-- Runs if options are changed from the Widget Settings menu
widget.options = options
end
local function background(widget)
-- Runs periodically only when widget instance is not visible
end
local function refresh(widget, event, touchState)
-- Runs periodically only when widget instance is visible
-- If full screen, then event is 0 or event value, otherwise nil
end
return {
name = name,
options = options,
create = create,
update = update,
refresh = refresh,
background = background
}