Application Lifecycle and ViewManager
ViewManager manages a LIFO App stack. Opening a new App pauses the App below it and keeps that lower App in the stack.
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 observable results. Handle each LaunchResult at the navigation call site.
Nested navigation
ViewManager accepts navigation after the current lifecycle or navigation call returns. A transition guard rejects synchronous push or pop requests from onEnter(), onExit(), onPause(), onResume(), App construction or destruction, and other navigation calls, preserving a fully 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. An IApplication* returned by a query remains valid only until the corresponding App is popped.
