1.4 handlers

Handlers in Lua

The term "handler" is likely familiar to programmers. For those who might not immediately understand, here is a "beginner's explanation": A handler in the context of Lua can be considered a type of program module. Essentially, a handler is triggered by an overarching (system) event. There are various "specialized" modules/handlers for different tasks or different "events"/triggers. Each module has a well-defined name, and an overview of the handlers is listed below. Each module, or handler, executes a self-contained routine corresponding to its task through the program flow contained within. Data exchange between handlers, if desired, takes place via a unified data structure, such as a "widget." This data structure is typically generated during the initial call (by the create handler).

Below is a brief explanation of each handler. More detailed functionality will become clear from example scripts included in the respective chapters.

List of Typical Handlers

init()

This handler is called during the boot process of the transmitter. It is used to inform the transmitter of a list of all Lua scripts with their unique "keys" and their types. The "environment" (which handlers exist in the script) is also set up.

Code Example:

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

create()

The create handler is executed the first time the script is called, such as when a widget's screen is activated for the first time. Typically, the central data structure/an array is defined in the create handler, which can be passed to other handlers. This data structure must be defined as the handler's return value. Often (e.g., in a widget), this is named "widget."

wakeup(widget)

The wakeup handler is the general background handler for all sorts of tasks (except those handled by the specific handlers listed below). This usually includes reading sources such as switch positions, analog inputs, telemetry values, processing them, and updating the central data structure (input, processing, output principle). It is generally called dozens of times per second. A key element is to decide whether data relevant to the display (in the paint handler) has changed. If so, the wakeup handler triggers a display update through the lcd.invalidate() method. Ideally (for performance reasons), the area to be updated is specified. Multiple areas can be specified in a single wakeup cycle.

paint(widget)

The paint handler is responsible for graphical representations in a script. Therefore, it is only necessary in scripts that display something, such as widgets and system scripts, but not source scripts. Only here are methods/functions for drawing, text, and value display relevant (lcd class). Ideally, the wakeup handler has pre-processed all necessary texts, values, and other variables, leaving almost only presentation-relevant code blocks here.

Note: There are often misunderstandings in forums about the interaction of the wakeup handler, the paint handler, and the lcd.invalidate() method. Generally, it should be understood as follows:

• wakeup is responsible for general background processing and, as much as possible, for pre-processing data used in paint. Wakeup is called very frequently by the system.
• paint is also called frequently by the system and essentially follows the wakeup handler. Its focus is on graphical presentation. VERY IMPORTANT: Calling a graphical method, such as drawing lines or printing text or values, does NOT necessarily mean that this is directly shown on the screen. Initially, a very fast image buffer is filled.
• lcd.invalidate(x, y, w, h): only this call ensures that the screen (or the specified area) is cleared and the relatively "slow" screen buffer is filled with new data. This method should only be called from wakeup, ideally when it has been determined that something in the display has changed!

The fact that the paint cycle does not necessarily lead to a screen refresh can be confusing for beginners but has significant performance advantages for the overall system.

event(widget, category, value, x, y)

This handler processes "external events," usually user interactions. For example, touching a screen, pressing control buttons (Page Up/Down), scroll wheel, etc. As seen above, besides the typical "widget" structure, Ethos also passes the category (e.g., touch event), the value (press/release), and coordinates as input parameters.

configure(widget)

Those who have worked with widgets may know the option to configure them via a menu call. This call triggers the configure handler. It provides possibilities, especially via the forms class, to create a comprehensive configuration menu.

write(widget)

The write handler saves model-specific parameters to the model file. Typically, changes in values in the configure handler trigger this write action. The handler must, of course, have been defined by the init handler.

read(widget)

Parameters written by the write handler should naturally be loadable when loading the model (or otherwise). This is done by the read handler.

menu(widget)

Handler called when creating the context menu to add additional options.

close(widget)

Handler called when the current page is closed.