Skip to content

system.registerWidget

since 1.1.0

Register a Lua Widget.

system.registerWidget(params)

Parameters

Name Type Required Description
params table yes see the fields below

Fields of params:

  • key (string): unique key, with 7 chars max
  • name (string or function): widget name
  • create (function, optional): handler called when the widget is added to the model (created / read from storage), it will return the widget which is passed later to all functions
  • destroy (function, optional): handler called on widget deletion
  • configure (function, optional): handler called on widget configuration
  • build (function, optional): handler called when the widget is built in the Home screen, after creation and configuration
  • wakeup (function, optional): handler called at each loop
  • event (function, optional): handler called when an event is received (event not passed to the parent window if the handler returns True)
  • paint (function): paint function
  • menu (function, optional): handler called when the contextual menu is created, to allow adding more options to the menu, the handler should return a table of pairs { name, function }
  • read (function, optional): optional read handler
  • write (function, optional): optional write handler
  • persistent (boolean, optional): persistent data
  • title (boolean, optional): title forced ON / OFF

Returns

Nothing.

Examples

From the official Ethos documentation
-- Lua Sinus widget
local translations = {en="Lua Sinus", fr="Sinus Lua"}

local function name(widget)
    local locale = system.getLocale()
    return translations[locale] or translations["en"]
end

local function create()
    return {color=lcd.RGB(0, 0, 255)}
end

local function paint(widget)
    local w, h = lcd.getWindowSize()
    lcd.drawLine(0, h/2, w, h/2)
    lcd.color(widget.color)
    for i = 0,w do
      local val = math.sin(i*math.pi/(w/2))
      lcd.drawPoint(i, val*h/2+h/2)
    end
end

local function init()
    system.registerWidget({key="sinus", name=name, create=create, paint=paint})
end

return {init=init}

Used in

Real-world usage

Called 7 times across 7 open-source Ethos Lua projects. A few short excerpts:
local function init()
    system.registerWidget(widget)
end

src/gps-heading/widget.lua:13

local function init()
  system.registerWidget({ key = "FrkJet", name = "Jet dashboard", create = create, build = build, paint = paint, wakeup = wakeup, configure = configure, read = read, write = write, title = false })
end

lua/frsky/JetWidget/main.lua:397

local function init(opts)
  opts = opts or {}
  systemToolHandle = opts.systemToolHandle
  system.registerWidget(widget)
end

src/rfsuite/widgets/dashboard.lua:2205