Overview

The Lucy Script API is the programming interface for controlling your app, its data, and screen flow from inside a form (screen) script. Use it for behavior you can't express by placing widgets alone — requesting data when a button is pressed, moving to another screen, or communicating with a server. The Script API falls into three groups.

At a Glance

Group	What it is	How you call it
Lifecycle Events	Callbacks Lucy invokes automatically when a form or its data reaches a certain point	Define a function of the same name in the form script (for example, onStart or onMessage)
Global Objects	$ global objects available anywhere (app, form, data, and communication)	$object.member (for example, $app.openPage(...))
Widget Methods	Control screen widgets by name (ID)	widgetID.member (for example, textID.setText(...))

About Each Group

Lifecycle Events

Callbacks Lucy invokes automatically when a form or its data reaches a certain point. You never call them yourself — define a function with the expected name in the form script, and it runs at that point. They come in three branches.

• Form/Page Events — when a form opens (onStart), appears on screen (onActive), is covered (onInactive), and closes (onClose).
• Messaging Events — receive messages sent by another form or app through onMessage(name, data).
• Data Lifecycle Events — callbacks that hook into each stage of the data request, response, and real-time push flow.

For the full list, visit the Lifecycle Events section.

Global Objects

Global objects you can use anywhere in a script by their $ prefixed name. They divide up by area.

• $app — app-wide: page transitions, shared and stored data, theme, device state, and more
• $form / $parentForm / $ownerForm / $rootForm — the running form: opening screens, form variables and properties, messages between forms
• $vm — the form's data layer: reading and updating Data Set and Provider Instance values, requests and subscriptions, sorting
• $act — event responses: Actions, State Transitions, Detect Transitions
• $log — diagnostic logs (d / i / w / e)
• $http — REST communication (get / post / put / patch / delete / head / options / multipart)
• $mqtt — MQTT connections (returns the MqttClient connection object)

For the full list, visit the Global Objects section.

Widget Methods

Control the widgets you placed on screen with widgetID.member. They come in two branches.

• Common Widget Methods — controls every widget shares (reading and writing properties, style and layout control, state, and more).
• Individual Widget Methods — controls specific to each widget type (for example, setText and getText on TextField).

For the full list, visit the Widget Methods section.

Notation Conventions

• widgetID and textID in the examples are the name (ID) you gave the widget on the canvas. Scripts reach it as widgetID.member.
• Global objects are used exactly as their $ prefixed names.
• Lifecycle events run automatically at their point in time once you define a function of the same name in the form script.