StateContext
Generated from engine/core/state_context.h at aceb130. The text under each declaration is the header's own comment, word for word. About the reference says how these pages are made.
Audience: game code.
#include "engine/core/state_context.h" · namespace labrador
class StateContext
Section titled “class StateContext”Owns a stack of states, their suspension and result delivery (docs/design/PHILOSOPHY.md, Structural types). A state's destructor releases what it set up; states beneath a pushed screen remain alive.
transition_to(), push() and pop() issued during this context's update, init, activation walk, close request or operation drain wait for the enclosing call to return. Nested callbacks retain that protection; the drain never reenters itself. Operations outside these calls take effect immediately.
A root State can own a separate StateContext to run code around every game update and draw. It forwards update, draw and activation to the owned context, including its parent's active() value during init(). It forwards on_close_requested() to notify_close_requested() too. Inner states use their own context(); Application::depth() then counts only the root. Frame capture belongs in the root's update after the owned update returns, never in draw() (engine/render/renderer.h, Renderer::read_back_buffer).
~StateContext · StateContext
Section titled “~StateContext · StateContext”StateContext();StateContext · operator=
Section titled “StateContext · operator=”StateContext& operator=(const StateContext&) = delete;update
Section titled “update”void update(float dt);Updates the top state only. Everything below it is suspended.
Draws from the topmost state that covers the screen, upward (State::covers_screen). The level draws, then the pause menu over it, in one pass with no state having to know what is under it.
transition_to
Section titled “transition_to”Replaces the top state, or installs the first one on an empty stack. Rejects nullptr with std::invalid_argument. Safe inside the current state's update(): deferral keeps that state alive until its call returns. The new state's context is set and init() runs before update() or draw().
Consecutive queued transitions collapse to the last one; discarded states never run init(). Pushes and pops between transitions preserve their issue order, because they change which stack entry is being replaced.
Puts a state above the current one and calls the covered state's on_suspend(). It stops updating and keeps drawing if the new top does not cover the screen. Rejects nullptr with std::invalid_argument; deferral and entry follow transition_to().
Calls on_closed after this stack entry is popped, regardless of the result supplied to pop(). The ordering and shutdown rule match on_result below.
template <typename Result> std::function<void(const Result&)> on_result);Calls on_result with the typed result when this stack entry is popped. The callback belongs to the entry and survives transition_to() replacing its state, so a multi-page screen answers the push that opened it.
The type is named at the push and checked at the pop:
this->context()->push<PauseChoice>( std::make_unique<PauseState>(this->app_), [this](const PauseChoice& choice) { ... });// ...and, inside the pause screen, however many pages later:this->context()->pop(PauseChoice::resume);on_result runs after the popped state is destroyed and after the resumed state's on_resume(). Missing or mismatched results throw std::logic_error at delivery (T6). clear() never delivers results.
void pop();Takes the top state off. Throws std::logic_error if there is nothing on the stack to take.
template <typename Result>void pop(const Result& result);int depth() const;How many states are stacked: 1 at a title screen, and 3 with a pause menu over a match over a menu.
notify_activation
Section titled “notify_activation”void notify_activation(bool active);Reports a foreground change to every live state, top first. Repeating the current value does nothing. active() reflects the new value during callbacks; covered states are notified even though they do not update.
Stack operations issued by callbacks wait until the walk and any enclosing callback or active drain return. A nested notification cannot drain operations while an outer update() or init() is still running.
active
Section titled “active”bool active() const;Foreground state as last reported; initially true. A state constructed after a notification receives no retrospective callback and reads this in init() to learn whether it entered an inactive context.
notify_close_requested
Section titled “notify_close_requested”bool notify_close_requested();Asks the current top state's on_close_requested(), or allows closure when the stack is empty. Does not close a window itself. Stack changes wait until the callback returns, preserving its state and captures; the returned decision belongs to that request even if the top changes. Each later request asks the then-current top. A recursive request during this notification or its drain returns false without a callback.
void clear() noexcept;Drops queued operations, then destroys live states top first without delivering result callbacks. It leaves active() unchanged. Also called by the destructor; repeated calls on an empty stack are harmless.
Immediate, never deferred: do not call it from a state's update(), init(), activation or close-request callback. The state whose code is running could be destroyed, along with frames an activation walk has yet to visit. Owners must clear states before destroying any services they borrow; Application clears its stack before its service members are destroyed. A throwing state destructor terminates here: teardown is noexcept (T6).
Related types
Section titled “Related types”Named in the public declarations above: Renderer, State.
In the samples and tests
Section titled “In the samples and tests”The files that include this header directly. A file can also reach it through another header.
samples/components/gallery_touch_tests.cpp,touch_demo_state.cppsamples/minimal/states/confirm_state.cpp,hello_state.cpptests/app/application_loop_tests.cpptests/core/state_context_tests.cpptests/linesweeper/focus_pause_tests.cpp,touch_pause_tests.cpptests/local_multiplayer/join_state_tests.cpptests/minimal/close_request_tests.cpp,state_tests.cpptests/scene/order_tests.cpp
Explained in
Section titled “Explained in”Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.