Class Session

Class Documentation

class Session

Declaration: final

Owns one toolkit process-global session on its creating simulation/UI thread.

Input outlives the session; external native toolkit references must be released before teardown. Calls after close or from another owner throw.

See also

Session integration

Public Functions

Session(CE::Input::System &input, CE::Input::Routing::TargetId target, SessionOptions options = {})

Construct a standalone toolkit session on the UI owner before creating widgets/documents.

target must be nonzero; capture support and toolkit global ownership are required. Borrow input for the session lifetime; option/capture/global-state/allocation failures throw. Configure standalone fonts explicitly as needed.

See also

Session routing and widget focus

Parameters:

target – Nonzero application-chosen keyboard/text routing identity for this entire session. Components share it; numeric magnitude gives no priority. Choose distinct IDs for independent recipients sharing one input system.

Session(CE::Input::System &input, const CE::Text::FontService &fonts, CE::Input::Routing::TargetId target, SessionOptions options = {})

Construct with a retained catalogue/default snapshot: ordinary native text inherits the configured default.

Existing Font handles/bytes are retained without reopening paths; later service reconfiguration does not rebind this session. Input remains borrowed, but the font service need not outlive the imported snapshot. Theme font aliases use configured Engine references.

See also

Session routing and widget focus

Parameters:

target – Nonzero application-chosen keyboard/text routing identity for this entire session. Components share it; numeric magnitude gives no priority. Choose distinct IDs for independent recipients sharing one input system.

Session(CE::Runtime::Context &engine, CE::Input::Routing::TargetId target, SessionOptions options = {})

Construct using engine.input() and engine.fonts().

Acquire this on the permitted owner after Engine initialization; preserve the input lifetime and release the session before runtime input teardown.

See also

Session routing and widget focus

Parameters:

target – Nonzero application-chosen keyboard/text routing identity for this entire session. Components share it; numeric magnitude gives no priority. Choose distinct IDs for independent recipients sharing one input system.

~Session()

Release toolkit globals and retained CPU state after callers/native references quiesce.

Uploaded Cheryl scenes and CPU recordings remain independently retained. Use close_after_quiescence() for final platform teardown after simulation joins.

Session(const Session&) = delete
Session &operator=(const Session&) = delete
Session(Session&&) = delete
Session &operator=(Session&&) = delete
tgui::BackendGui &gui()

Declaration: [[nodiscard]]

Borrow the native GUI on its live UI owner.

Do not retain widgets/font/texture/backend references past session teardown; use native widget APIs within this lifetime.

Capabilities capabilities() const

Declaration: [[nodiscard]]

Return a copied input/toolkit support snapshot; query on the live creating UI owner.

tgui::Font font(const CE::Text::Font &selected, CE::Text::FontStyle style = {})

Declaration: [[nodiscard]]

Resolve a retained Engine font to a native font using closest weight/italic variants and actual collection face indices.

Empty Font rejects; native loading/allocation failures propagate. Release returned native font/widget references before the session.

void set_font(tgui::Widget::Ptr widget, const CE::Text::Font &selected, CE::Text::FontStyle style = {})

Set a native renderer font from the retained Engine selection/style.

Null widgets or empty fonts reject. The widget/native font must not outlive this session; the operation can affect widgets sharing that renderer.

void set_view(CE::Platform::Dimensions<int> logical, CE::Platform::FramebufferSize framebuffer)

Copy logical window and framebuffer-pixel dimensions; neither reads a native window.

Negative sizes reject. Zero logical extent disables pointer input; zero logical/framebuffer extent suppresses drawing. Native layout uses logical units. In manual mode, initialize before first input/recording and refresh when either size changes. A valid manual call acknowledges detach from automatic sizing before applying; invalid arguments preserve the attachment. A native apply failure after detach leaves manual mode selected.

See also

View/time options

void follow_view(const CE::Runtime::SimulationViewSource &source)

Attach and seed on the simulation owner.

On the live UI/source owner, attach required automatic sizing and apply the coherent current seed before returning.

A valid set_view() detaches automatic sizing.

Uninitialized/closed/foreign-owner sources reject. A failed seed leaves no new subscription; later required apply failure propagates before dependent runtime work. Public set_view() selects manual mode after validation. Standalone sessions may attach explicitly.

void set_layout(tgui::Widget::Ptr widget, const WidgetLayout &layout)

Bind typed placement to the current parent’s content size.

Add the widget to this GUI with native Manual layout first; null/foreign/unparented widgets or invalid/nonfinite rules reject. Reapply after reparenting. Releasing a formerly scalable axis freezes its current size; other native sizing is preserved.

See also

Typed layout

void update_time(double seconds)

Advance toolkit simulation time by a finite nonnegative representable number of seconds.

Invalid durations reject; native layout/update failures may propagate. Uses the session’s UI owner and does not poll platform events. Reject while automatic time is attached, including a zero delta. detach_time() explicitly returns to manual advancement. This call does not detach sizing or deliver input.

void follow_time(const CE::Runtime::RuntimeServices&)

Attach on the simulation owner; starts next step without replaying a past delta.

Attach required advancement on the initialized simulation/UI owner.

Future selected steps advance toolkit time before the game hook; the current/past step is not replayed. Manual update_time() rejects while attached. This operation does not deliver input or adopt a scene.

void detach_time()

On the live UI owner, acknowledge automatic-time detach.

Later manual update_time() is allowed; elapsed time is retained. Empty/already detached time participation is harmless.

void request_keyboard_focus(CE::Input::Routing::KeyboardPolicy routing = CE::Input::Routing::KeyboardPolicy::Exclusive)

Acquire committed-text capture and a new focus lease/epoch for this target.

Requires keyboard-focus and Text capabilities. New focus affects future polls; already collected records retain their earlier target/epoch. Toolkit widget/element focus is authored separately.

void release_keyboard_focus()

Release this session’s focus/Text leases and native widget focus.

Releasing an old lease cannot erase another owner’s newer focus. Drain already collected poll-latched records before release.

bool owns_keyboard_focus() const

Declaration: [[nodiscard]]

Return whether this session’s current focus lease owns routing; this is distinct from a particular widget being focused.

void handle_input(std::span<const CE::Input::Events::Record> records, bool pointer_selected)

Deliver one complete ordered tick batch on the UI owner without consuming/modifying shared records.

Keyboard/Text delivery requires matching target and entry focus epoch; observe modifier releases even when not selected. pointer_selected explicitly admits mouse records, whose recorded positions are authoritative. Missing/invalid positions or text reject; unavailable clipboard shortcuts do not delete selected text.

See also

Batch routing

void handle_input(std::span<const CE::Input::Events::Record> records, bool pointer_selected, const std::function<bool(const CE::Input::Events::Record&)> &before_record)

Before each record, synchronously run application controls and use the returned bool for that record’s pointer selection.

The callback is borrowed for this call. Keyboard/Text retains the batch-entry epoch even if callbacks change focus; acknowledge preemption after draining the batch. Callback/event failures propagate after any earlier widget effects; no rollback is promised.

RecordedScene record()

Declaration: [[nodiscard]]

Record one complete owned CPU scene on the UI owner.

Invoke toolkit drawing when drawable. A zero view returns an empty recording; failure discards the incomplete recording and propagates. No graphics upload occurs.

void close_after_quiescence()

Release toolkit ownership after UI/simulation calls have stopped.

Final teardown may run on platform after join; release external toolkit widget/font/element/listener references first. No calls may race teardown; later session calls reject. Retained CPU recordings/uploaded Cheryl scenes remain independent.