⊞ Tileview
The Tileview widget is a multi-dimensional navigation container that arranges content into a grid of "tiles." Unlike the linear Tabview, a Tileview allows users to swipe both horizontally and vertically to navigate, creating a spatial UI map (e.g., swipe right for Settings, swipe down for Notifications).
⚙️ Properties (Props)
The Tileview configuration is defined by the TileViewWidget interface. It manages a coordinate-based system of pages.
| Property | Type | Description |
|---|---|---|
| Rows / Cols | number | The dimensions of the navigation grid (e.g., 2x2, 3x1). |
| Active Tile | Point | The {x, y} coordinate of the currently visible tile. |
| Anim Time | number | The duration of the sliding transition between tiles. |
| Valid Directions | Flags | Restrict movement (e.g., allow horizontal but block vertical). |
🛠 Spatial Navigation
A Tileview is essentially a matrix of Containers:
- Coordinates: Each page is identified by its grid position.
(0,0)is usually the "Home" tile. - Implicit Navigation: Users move between tiles by swiping. If there is no tile to the right of the current one, the engine prevents the swipe.
- Nesting: You can place any other widget inside a tile, including Charts.
🎨 Layout and Styling
In the Inspector Panel, you can configure the global behavior of the grid:
- Scrollbar: Choose to show or hide scrollbars that indicate the user's position in the 2D map.
- Edge Flash: Enable a visual "bounce" effect when a user tries to swipe past the edge of the grid.
- Background: Style the shared background of the Tileview or set unique background colors for individual tiles.
⚡ Runtime API (Lua)
Tileviews are powerful for creating deep, immersive menus via the Logic and Events system.
-- Get the current tile coordinates
local x, y = tv_home:get_tile_act()
-- Programmatically jump to the "Alerts" tile at (0, 1)
tv_home:set_tile_act(0, 1, true) -- x, y, animate
-- Lock navigation to prevent the user from leaving a specific tile
tv_home:set_content_scrollable(false)
-- Check if a specific tile is currently active
if tv_home:get_tile_act() == {x=1, y=0} then
lbl_header:set_text("Settings Menu")
end
Tileviews can be confusing if the user gets "lost" in the grid. Always provide a Label or a small "Map" indicator (pagination dots) so the user knows where they are relative to the Home tile.
🚀 Next Steps
- Tabview — Use if you only need simple, one-dimensional (horizontal) paging.
- Screen — Learn how to transition from a single Tile into a full-screen application.
- Logic and Events — Learn how to trigger hardware actions based on the active tile coordinate.