Decorations
| API | Purpose | Important contract |
|---|---|---|
decoration.text | Main TDML presentation | Assign a string |
decoration.backgroundColor | Whole-surface background | #RRGGBB, #RRGGBBAA, or empty string |
decoration.widthMode | Requested layout mode | Content, Fixed, Flexible |
decoration.fixedWidth | Fixed flow extent | Integer 1..4096 logical pixels; automatically selects Fixed mode |
decoration.geometry | Realized surface geometry | Read-only; may be nil |
decoration.interval | Periodic updates | 50..2147483647 ms; initialization only |
decoration:createText(key) | Positioned text element | Unique non-empty key |
decoration.graphics | Replace retained lines and paths | Complete copied { lines = {...}, paths = {...} } value |
storage.set/get/... | Persistent private state | Name-keyed storage |
For decoration.graphics, line endpoints are normalized from 0.0 through 1.0 relative to the surface. Paths use a logical-pixel placement rectangle plus normalized path operations. The supported path operations are move, line, cubic, and close.
See Scripted Decorations for property precedence, coordinate shapes, drawing limits, and TDML behavior. See Concepts for storage operations, commit errors, and scheduling.
| Callback | Arguments and purpose |
|---|---|
onLoad() | Initialize after successful top-level execution |
onTick(frameTimeSeconds) | Update; elapsed seconds for periodic/Window frames, absent for explicit requests |
onTaskLeftClick(modifiers) | Taskbar left-click; boolean shift, ctrl, alt, meta fields |
onTaskMiddleClick(modifiers) | Taskbar middle-click with the same modifier fields |
onClose(windowId) | A Script-Created Window was closed |
onHide(windowId) | A Script-Created Window became hidden |
onResize(windowId, dimensions) | Visible Window’s logical grid/aspect changed |
onKey(key, modifiers) | Key press in a focused, visible Script-Created Window |
onStorageError(error) | An accepted persistence write failed |
onStop() | Normal teardown; not a final-save guarantee |
All are optional global functions. Window callbacks are not application-task callbacks. There is no right-click/menu callback. A callback failure faults its owning runtime; later results from that runtime cannot update a replacement. Content or property mutations in one successful callback publish together rather than painting immediately.