개요

Lucy 스크립트 API는 폼(화면) 스크립트 안에서 앱·데이터·화면 흐름을 제어하는 프로그래밍 인터페이스입니다. 위젯을 배치하는 것만으로는 표현하기 어려운 동작 — 버튼을 눌렀을 때 데이터를 요청하거나, 다른 화면으로 이동하거나, 서버와 통신하는 동작 — 을 구현할 때 사용합니다. 스크립트 API는 성격에 따라 세 그룹으로 나뉩니다.

한눈에 보기

그룹	무엇인가	스크립트에서 부르는 법
Lifecycle Events	폼이나 데이터가 특정 시점에 도달하면 Lucy가 자동으로 호출하는 콜백	폼 스크립트에 같은 이름의 함수를 정의 (예: onStart, onMessage)
Global Objects	어디서나 쓸 수 있는 $ 전역 객체 (앱·폼·데이터·통신)	$객체.멤버 (예: $app.openPage(...))
Widget Methods	화면 위젯을 이름(ID)으로 제어	위젯ID.멤버 (예: textID.setText(...))

그룹 소개

Lifecycle Events

폼이나 데이터가 특정 시점에 도달했을 때 Lucy가 자동으로 호출하는 콜백입니다. 개발자가 직접 호출하지 않고, 정해진 이름의 함수를 폼 스크립트에 정의해 두면 그 시점에 실행됩니다. 세 갈래로 나뉩니다.

• Form/Page Events — 폼이 열리고(onStart), 화면에 나타나고(onActive), 가려지고(onInactive), 닫히는(onClose) 시점.
• Messaging Events — 다른 폼이나 앱이 보낸 메시지를 onMessage(name, data)로 수신.
• Data Lifecycle Events — 데이터 요청·응답·실시간 push 흐름의 각 단계에 개입하는 콜백.

자세한 목록은 Lifecycle Events 섹션에서 확인할 수 있습니다.

Global Objects

스크립트 어디에서나 $ 접두 이름으로 바로 쓸 수 있는 전역 객체입니다. 영역별로 나뉩니다.

• $app — 앱 전역: 페이지 전환, 공유·저장 데이터, 테마, 디바이스 상태 등
• $form / $parentForm / $ownerForm / $rootForm — 실행 중인 폼: 화면 열기, 폼 변수·속성, 폼 간 메시지
• $vm — 폼의 데이터 계층: Data Set·Provider Instance 조회/수정, 요청·구독, 정렬
• $act — 이벤트 응답: Action, State Transition, Detect Transition
• $log — 진단 로그 (d / i / w / e)
• $http — REST 통신 (get / post / put / patch / delete / head / options / multipart)
• $mqtt — MQTT 접속 (연결 객체 MqttClient 반환)

자세한 목록은 Global Objects 섹션에서 확인할 수 있습니다.

Widget Methods

화면에 배치한 위젯을 위젯ID.멤버 형태로 제어합니다. 두 갈래로 나뉩니다.

• Common Widget Methods — 모든 위젯이 공통으로 갖는 컨트롤 (속성 읽기/쓰기, 스타일·레이아웃 제어, 상태 등).
• Individual Widget Methods — 위젯 종류별 고유 컨트롤 (예: TextField의 setText·getText).

자세한 목록은 Widget Methods 섹션에서 확인할 수 있습니다.

표기 규약

• 예시의 위젯ID·textID 등은 캔버스에서 위젯에 지정한 이름(ID)입니다. 스크립트에서는 위젯ID.멤버 형태로 접근합니다.
• 전역 객체는 $ 접두 이름 그대로 사용합니다.
• 라이프사이클 이벤트는 폼 스크립트에 같은 이름의 함수를 정의하면 해당 시점에 자동 실행됩니다.