Widget panel arrangements
Use WidgetLayoutState when users should reopen a composed surface with the
same widget panels. This includes a WidgetLayoutContainer and the outer panel
arrangement of a Trading Terminal.
Persist a widget panel arrangement when users can add, close, move, resize, or group panels and expect those choices to survive a reload. A fixed product surface, or one that intentionally starts from the same default every time, does not need this persisted state.
What WidgetLayoutState contains
| Included in the widget panel arrangement | Stored elsewhere |
|---|---|
| Panel instances, groups, split positions, tab order, and the active panel | Symbols, intervals, indicators, comparisons, drawings, and other chart content in ChartLayout |
| The stable widget type id and parameters for each panel instance | Live quotes, depth, and historical bars from the datafeed |
| Widget panel titles and opaque panel-engine topology | Orders, positions, accounts, and broker connection state from the broker backend |
| Optional resizable-container height | User preferences whose lifecycle is independent from this composed surface |
WidgetLayoutState is a complete snapshot of widget panel topology. It does
not serialize the live state inside a mounted chart or trading widget.
Keep chart layouts separate
| Product question | Chart workspace layout | Widget panel arrangement |
|---|---|---|
| What returns? | Charts and their saved chart content | The panels that host charts, order tickets, watchlists, and other widgets |
| Public state | ChartLayout | WidgetLayoutState |
| Stable identity | ChartLayout.id | Host-defined arrangementId for the persisted snapshot |
| Changes when | A chart's symbol, interval, indicators, drawings, chart grid, or sync settings change | A panel is added, closed, moved, resized, activated, regrouped, or given new parameters |
| Deletion affects | Only the saved chart layout | Only the saved widget panel arrangement |
A Trading Terminal commonly restores both state objects. Restoring the widget panel arrangement creates the places where chart widgets mount; it does not restore those charts' saved content. Restoring a chart layout changes chart content; it does not rearrange the surrounding widget panels.
Keep identity stable
arrangementId identifies one product surface, not one chart layout. Keep it
stable when the visible terminal title changes, and scope it by user or
workspace when different users or workspaces need different arrangements.
terminalId identifies a live Trading Terminal instance. It is not persisted
state and does not save a widget panel arrangement by itself. Products may
derive terminalId and arrangementId from the same product concept, but they
remain separate identities.
Every WidgetLayoutSurfaceWidgetDefinition.id is also persisted. Keep each id
stable and register every supported widget definition before restoration. If a
saved id is no longer registered, the panel renders the unknown-widget
placeholder instead of silently changing to another widget type.
Preserve the opaque payload
WidgetLayoutState has three public fields:
| Field | Meaning |
|---|---|
version | Widget panel state schema version; currently 1 |
dockview | Opaque SDK-owned widget panel engine payload |
containerHeight | Optional container height in pixels when the surface is resizable |
Persist dockview as JSON and pass it back unchanged. Do not inspect its
engine-specific fields, normalize it into backend columns, partially merge it,
or use its shape as application logic. The SDK's widget panel container is the
only owner allowed to interpret that payload.
Treat WidgetLayoutState.version as part of the saved-state contract. If a
future application release no longer supports a stored version, handle that as
an explicit persisted-state migration or an incompatible snapshot; do not
guess from the dockview shape.
Define the lifecycle
- One snapshot replaces the complete widget panel arrangement for one
arrangementId; it is not a patch over the previous snapshot. - A widget panel change creates new
WidgetLayoutState. A chart-content change does not. - Renaming or removing a persisted widget definition id is a stored-data compatibility change, even when the visual widget is otherwise unchanged.
- Deleting a widget panel arrangement must not delete chart layouts. Deleting a chart layout must not delete the widget panel arrangement.
- Product defaults apply when no saved widget panel arrangement exists. They are not another persisted record unless the product explicitly saves them.
Next steps
- Widget layout storage — implement persistence for
WidgetLayoutState. - Chart workspace layouts — define the separate state inside chart workspaces.
- Trading Terminal — compose chart and widget panel state in one product surface.