Application Lifecycle and ViewManager
ViewManager manages a LIFO App stack. Opening a new App does not destroy the App below it; the lower App is paused instead.
The upper half shows push: B is constructed in the arena, then receives onEnter() only after the fade completes. The lower half shows pop: exit callbacks and non-owning references are cleaned before B is destroyed and A resumes.
1 | push B: A.onPause() -> B becomes the current drawable -> fade -> B.onEnter() |
Launching an App
1 | auto result = views.launch(appItem, parameters); |
launch() uses the factory stored in AppItem, which suits AppLauncher and registration systems. push<T>() forwards constructor arguments directly and suits internal navigation when the concrete type is known.
LaunchResult
| Result | Meaning |
|---|---|
Ok |
The App was constructed and committed to the stack |
StackFull |
PIXELUI_MAX_VIEW_DEPTH has been reached |
ArenaFull |
Page depth remains, but the arena lacks object bytes or alignment padding |
ConstructionFailed |
The factory could not construct the object |
TransitionInProgress |
A page is being committed or waiting for fade completion |
Capacity failures are normal observable results and should not be ignored.
Nested navigation is rejected
Do not synchronously push or pop during onEnter(), onExit(), onPause(), onResume(), App construction or destruction, or another navigation call. A transition guard makes ViewManager reject nested requests instead of operating on a half-committed stack.
When a lifecycle callback must navigate elsewhere, record a pending action and run it from the main loop after the current call stack returns.
Fade and onEnter
When pushing over a visible App, the new App first enters m_pendingEnter. renderer() continues advancing the fade and calls onEnter() after the final frame. This prevents a new App from publishing Widgets, Popups, or Animations while the previous page remains visible.
isTransitioning() also returns true while waiting for fade completion, but only the short commit guard blocks the renderer. Otherwise the fade could never complete.
Cleanup before destruction
During pop, ViewManager clears drawable, exit callback, Animation, Coroutine, Focus, and Popup references before calling the concrete App destructor and restoring the arena marker. Never retain an IApplication* returned by a query across a pop.
