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. Case-insensitive RCSS aliases must identify one case-sensitive Engine reference; case collisions reject construction.

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
Rml::Context &context()

Declaration: [[nodiscard]]

Borrow the native RmlUi context on its live UI owner.

Author documents/styles/listeners natively and release external native references before session teardown.

Capabilities capabilities() const

Declaration: [[nodiscard]]

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

bool load_font(const std::filesystem::path &file, const Rml::String &family, bool fallback = false)

Load an explicit face from file into the native family alias.

Nonempty family is required; collisions with managed Engine/private fallback aliases reject. Core retains loaded font storage; unavailable/native load returns false. fallback explicitly permits global glyph fallback; specialty fonts should ordinarily leave it false.

bool load_font(std::span<const unsigned char> bytes, const Rml::String &family, bool fallback = false)

Copy nonempty font bytes through Core shutdown, without borrowing application storage.

Alias/availability rules follow file loading. Invalid arguments/allocation failures throw; native face rejection returns false.

Rml::String font_family(const CE::Text::Font &selected)

Declaration: [[nodiscard]]

Register retained primary variants and return the Engine reference as its RCSS alias.

Preserves actual face indices and nearest missing normal/italic styles without synthesizing glyphs. Empty selections, case collisions or a different snapshot under an already reserved alias reject. Common fallbacks use separate aliases; specialty fonts do not become global fallbacks.

See also

RmlUi font naming and styles

void set_font(Rml::Element &element, const CE::Text::Font &selected)

Set the native font-family property to font_family(selected).

The element must belong to this session, including its root; foreign elements reject. Other RCSS properties such as weight/italic/size remain native style choices; property/registration failures throw.

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 update_time(double delta_seconds)

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

Invalid durations reject; native layout/update failures may propagate. Call record() to update authored layout without advancing elapsed time. 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.

Update native layout without advancing simulation time, then render 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.