📺 Screen
The Screen is the top-level container for every page in your application. Every widget you create must reside within a Screen. It defines the global canvas size, background behavior, and the transition logic used when navigating between different parts of your HMI.
⚙️ Properties (Props)
The Screen configuration is defined by the ScreenWidget interface. As the root object, its properties dictate the environment for all child widgets.
| Property | Type | Description |
|---|---|---|
| Screen ID | string | The unique name used for navigation (e.g., main_menu, settings). |
| Transition | Dropdown | The animation used when this screen appears (e.g., Slide, Fade, None). |
| Background Color | string | The base color of the canvas. |
| Wallpaper | imageId | An optional full-screen background image asset. |
🔄 Screen Transitions
When moving from one screen to another, the engine handles the visual transition to provide a polished user experience. Common modes include:
- None: Instant switch (fastest performance).
- Slide Left/Right: Ideal for linear menu navigation.
- Fade: A smooth alpha-transparency blend between screens.
- Move Over: The new screen slides on top of the old one.
🎨 Global Styling
While individual widgets have their own styles, the Screen defines the "world" they live in:
- Orientation: Set via the Project Settings, but the Screen adapts its layout to the defined resolution.
- Input Handling: The Screen is responsible for capturing raw touch/click data and propagating it down to the child widgets.
⚡ Runtime API (Lua)
Navigation is almost exclusively handled via the Logic and Events system using Screen-specific commands.
-- Navigate to a new screen with a specific transition
app:load_screen("settings_menu", "slide_left", 300) -- ScreenID, Type, Duration(ms)
-- Get the currently active screen ID
local current = app:get_active_screen()
print("Currently viewing: " .. current)
-- Force a screen to refresh its layout
screen_main:invalidate()
Keep the number of widgets per screen balanced. If a screen becomes too complex, consider splitting content into multiple screens or using Containers that you toggle on and off to save memory and improve rendering speed.
🚀 Next Steps
- Container — Use for grouping widgets inside a screen.
- Logic and Events — Learn how to trigger screen changes based on hardware button presses.