Frame Primitive
Introduction
The Frame primitive represents a complete user interface surface in ProntoGUI™. Depending on its embodiment, a Frame can serve as a top-level application window, a modal dialog, an inline container for organizing other primitives, or a transient snackbar notification. Frames are the primary way to structure and present your GUI.
Fields
| Field | Type | Default | Description |
|---|---|---|---|
frameItems |
[]Primitive |
[] |
The child primitives contained in the frame |
showing |
bool |
false |
Whether the frame is currently shown on screen |
title |
string |
'' |
Title displayed for the frame (used in certain embodiments) |
icon |
Primitive |
nil |
Optional icon displayed alongside the title |
status |
int |
0 |
Controls visibility and interactivity (see Status section) |
Status Values
The status field controls the visibility and interactivity of the frame:
| Value | State | Visible | Interactive | Occupies Space |
|---|---|---|---|---|
| 0 | Normal | Yes | Yes | Yes |
| 1 | Disabled | Yes | No | Yes |
| 2 | Hidden | No | No | Yes |
| 3 | Collapsed | No | No | No |
Embodiments
A Frame can be rendered as one of four embodiments:
| Embodiment | Description |
|---|---|
default |
An inline container for organizing child primitives |
full-view |
A full-screen application window |
dialog-view |
A modal dialog window |
snackbar |
A transient notification bar |
Default (Inline Container)
The default embodiment renders a Frame as an inline layout container, analogous to a <div> in HTML. Use it to group and arrange child primitives within a larger interface. Default frames can be nested inside other frames or used as items in groups, lists, and tables.
Full-View (Application Window)
The full-view embodiment renders the Frame as a full-screen page.
Key behaviors:
– Set showing to true to display the window and false to dismiss it.
– Only one full-view frame is displayed at a time. When multiple full-view frames have showing set to true, the one with the highest index in the top-level primitives list takes precedence.
– Switching between full-view frames uses a page replacement transition rather than stacking.
Dialog-View (Modal Dialog)
The dialog-view embodiment presents the Frame as a modal dialog that appears on top of the current content.
Key behaviors:
– Set showing to true to open the dialog and false to close it.
– Multiple dialogs can be stacked simultaneously, appearing in the order of their index in the top-level primitives list.
– When the user dismisses a dialog (e.g., tapping outside of it), the showing field is automatically set to false.
Snackbar (Notification)
The snackbar embodiment displays the Frame as a transient notification bar at the bottom of the screen.
Key behaviors:
– Set showing to true to display the snackbar. It is automatically set back to false when the snackbar is dismissed (by timeout or user action).
– The first item in frameItems must be a Text primitive (used as the snackbar message).
– The second item (optional) can be a Command primitive (used as the snackbar action button).
Snackbar-specific embodiment settings:
| Setting | Type | Default | Description |
|---|---|---|---|
snackbarBehavior |
string |
fixed |
fixed pins to the bottom; floating hovers above content |
snackbarDuration |
number |
3 |
Duration in seconds before auto-dismiss |
snackbarShowCloseIcon |
bool |
false |
Whether to show a close icon on the snackbar |
Layout
Frames that use the default, full-view, or dialog-view embodiments support two layout methods for arranging their child primitives.
Flow Layout
Flow layout is the default. Child primitives are arranged sequentially in a single direction, either as a column or a row.
Embodiment Settings
| Setting | Type | Default | Values |
|---|---|---|---|
layoutMethod |
string |
flow |
flow, positioned |
flowDirection |
string |
topToBottom |
topToBottom, leftToRight |
horizontalItemAlignment |
string |
left |
left, center, right, expand, baseline, spaceBetween, spaceAround, spaceEvenly |
verticalItemAlignment |
string |
top |
top, middle, bottom, expand, baseline, spaceBetween, spaceAround, spaceEvenly |
When flowDirection is topToBottom, child primitives are stacked vertically in a column. The verticalItemAlignment setting controls spacing along the main axis (vertical) and horizontalItemAlignment controls alignment along the cross axis (horizontal).
When flowDirection is leftToRight, child primitives are arranged horizontally in a row. The horizontalItemAlignment setting controls spacing along the main axis (horizontal) and verticalItemAlignment controls alignment along the cross axis (vertical).
Positioned Layout
Positioned layout allows child primitives to be placed at absolute coordinates within the frame, similar to CSS absolute positioning.
Set layoutMethod to positioned to enable this mode. Each child primitive can then use the common positioning settings (left, top, right, bottom, width, height) to specify its location and size within the frame.
Children without explicit positioning will expand to fill the frame.
Common Embodiment Settings
In addition to the layout settings above, Frames support the full set of common embodiment settings described in the Layout Model documentation:
- Background:
backgroundColor - Border:
borderAll,borderLeft,borderRight,borderTop,borderBottom,borderColor - Margin:
marginAll,marginLeft,marginRight,marginTop,marginBottom - Padding:
paddingAll,paddingLeft,paddingRight,paddingTop,paddingBottom - Size:
width,height - Alignment:
horizontalAlignment,verticalAlignment(alignment of the frame itself within its parent) - Position:
left,right,top,bottom(when the parent uses positioned layout)
Ordering Top-Level Primitives
The order of frames in the top-level primitives list matters. Follow this convention:
- Full-view frames first, listed in order of increasing detail. For example, a summary screen should appear before a detail screen.
- Dialog-view frames next, listed in order of display depth. If dialog A leads to showing dialog B, then A should be listed before B.
- Snackbar frames last.
This ordering aligns with how the rendering engine selects which frames to display. For full-view frames, the highest-indexed showing frame takes precedence, so ordering from general to specific ensures that navigating deeper into your application naturally shows the correct screen. For dialog-view frames, multiple dialogs can be stacked simultaneously and their stacking order follows their index, so listing them in order of depth produces the expected layering.
Usage Patterns
Main Application Window
Use a full-view frame as the primary screen of your application. Set showing to true to display it. Place all of your UI primitives inside frameItems.
Multi-Screen Navigation
Create multiple full-view frames and toggle their showing fields to switch between screens. Only the highest-indexed showing frame is displayed, so setting one to true and the previous one to false creates a screen transition.
Modal Dialogs
Use a dialog-view frame for confirmations, forms, or any content that should appear as an overlay. Set showing to true to open it. The frame’s title field is typically displayed in the dialog header.
Organizing Content
Use default frames to create layout structure within a screen. For example, a full-view frame might contain several default frames arranged in a row, each containing a vertical stack of primitives. This nesting of frames with different flow directions is how complex layouts are composed.
Transient Notifications
Use a snackbar frame to briefly inform the user of an event. Populate it with a Text primitive and optionally a Command for an action button. Set showing to true to trigger it.