Class UiSystem¶
Namespace: Apogee.UI
Assembly: Apogee.UI.dll
The game's user interface: RmlUi with one context (the screen), its documents, fonts and input, behind the script global ui. Documents are written in RML and RCSS (HTML and CSS as RmlUi
knows them) with scripts of their own in Luau, or built from Luau; both go through
public sealed class UiSystem : EngineObject, IDisposable
Inheritance¶
object ← EngineObject ← UiSystem
Implements¶
Inherited Members¶
EngineObject.IsAdopted, EngineObject.Handle, EngineObject.IsDestroyed, EngineObject.Class, EngineObject.Adopt(), EngineObject.TryGet(SlotHandle, out EngineObject), EngineObject.Destroy(), object.Equals(object?), object.Equals(object?, object?), object.GetHashCode(), object.GetType(), object.ReferenceEquals(object?, object?), object.ToString()
Remarks¶
Call Mouse, Key and Text calls; each says whether the UI used it, so the game can leave it alone. Without a renderer (headless runs, tests) everything but drawing works.
What a document asks to read (its stylesheets, images and fonts) is read through the virtual file system, as res://, mod:// and user:// paths.
RmlUi has no stylesheet of its own: ui_base.rcss is put under every document (the document's own rules win), with the default font, Inter.
Constructors¶
UiSystem(VirtualFileSystem, ContentLoader?, int, int)¶
Starts RmlUi with width x height pixels of screen. Throws when there is a system already (RmlUi has one state per process) or the library is missing.
public UiSystem(VirtualFileSystem files, ContentLoader? content = null, int width = 1280, int height = 720)
Parameters¶
files VirtualFileSystem
content ContentLoader?
width int
height int
Properties¶
BaseStyle¶
The engine's base stylesheet (ui_base.rcss), which every document is given under its own rules.
public static string BaseStyle { get; }
Property Value¶
Class¶
What the registry knows about this object's class.
public override ClassInfo Class { get; }
Property Value¶
Cursor¶
The mouse cursor the UI wants (pointer, text, default...), as RmlUi last said.
public string Cursor { get; }
Property Value¶
Debugger¶
RmlUi's inspector (the element tree and styles of every document, and a log) as a window over the UI.
public bool Debugger { get; set; }
Property Value¶
Density¶
How many pixels a density-independent pixel (dp in RCSS) is: 1 on an ordinary screen, 2 on a high-density one, or what the player's UI scale says.
public float Density { get; set; }
Property Value¶
DocumentsLoaded¶
How many documents have been loaded since the system started: a host makes the renderer only when this is more than zero.
public int DocumentsLoaded { get; }
Property Value¶
Height¶
The height of the screen in pixels.
public int Height { get; }
Property Value¶
ListenerCount¶
The number of listeners scripts have on elements that still exist (after the dead ones are pruned).
public int ListenerCount { get; }
Property Value¶
Renderer¶
The renderer that draws the UI, once there is one.
public UiRenderer? Renderer { get; }
Property Value¶
ScriptEnvironments¶
The scripting layer that runs the code in documents. Without it a <script> or an onclick is ignored, with a warning.
public IScriptEnvironments? ScriptEnvironments { get; set; }
Property Value¶
ScriptedDocuments¶
The number of documents that have scripts running (they have an environment of their own).
public int ScriptedDocuments { get; }
Property Value¶
Time¶
The seconds the UI has run: the sum of the
public double Time { get; }
Property Value¶
WantsKeyboard¶
True while a text field has the focus: typed text and keys are the UI's, not the game's.
public bool WantsKeyboard { get; }
Property Value¶
WantsMouse¶
True while the pointer is over an element of a document: the game should not also react to the mouse.
public bool WantsMouse { get; }
Property Value¶
Width¶
The width of the screen in pixels.
public int Width { get; }
Property Value¶
Methods¶
CreateDocument()¶
An empty document, with a body to put elements in, for a UI built in code.
public UiElement? CreateDocument()
Returns¶
Dispose()¶
Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
public void Dispose()
Key(ArKey, bool, int)¶
A key went down or up (
public bool Key(ArKey key, bool down, int modifiers = 0)
Parameters¶
key ArKey
down bool
modifiers int
Returns¶
LoadDocument(string)¶
Loads the RML document at path (res://ui/menu.rml). It is not shown until
public UiElement? LoadDocument(string path)
Parameters¶
path string
Returns¶
LoadDocumentText(string, string)¶
Loads a document from RML text; sourceUrl is what its relative paths (stylesheets, images) are relative to.
public UiElement? LoadDocumentText(string rml, string sourceUrl = "")
Parameters¶
rml string
sourceUrl string
Returns¶
LoadFont(string, string, bool, bool, bool)¶
Loads a font from the file at path for the family family (documents say font-family: Family). False when it is not a font.
public bool LoadFont(string path, string family, bool bold = false, bool italic = false, bool fallback = false)
Parameters¶
path string
family string
bold bool
italic bool
fallback bool
Returns¶
LoadFont(ReadOnlySpan<byte>, string, bool, bool, bool)¶
Loads a font from memory (RmlUi keeps its own copy).
public bool LoadFont(ReadOnlySpan<byte> data, string family, bool bold = false, bool italic = false, bool fallback = false)
Parameters¶
data ReadOnlySpan<byte>
family string
bold bool
italic bool
fallback bool
Returns¶
MouseButton(int, bool, int)¶
A button went down or up: 0 left, 1 right, 2 middle. False when the UI used it.
public bool MouseButton(int button, bool down, int modifiers = 0)
Parameters¶
button int
down bool
modifiers int
Returns¶
MouseLeave()¶
public bool MouseLeave()
Returns¶
MouseMove(int, int, int)¶
The pointer moved to (x, y) pixels. False when the UI used it.
public bool MouseMove(int x, int y, int modifiers = 0)
Parameters¶
x int
y int
modifiers int
Returns¶
MouseWheel(float, float, int)¶
public bool MouseWheel(float x, float y, int modifiers = 0)
Parameters¶
x float
y float
modifiers int
Returns¶
OnDestroyed()¶
protected override void OnDestroyed()
OnUpdate(ScriptFunction)¶
Calls handler with the frame's time step at the start of every
public long OnUpdate(ScriptFunction handler)
Parameters¶
handler ScriptFunction
Returns¶
OpenDataModel(string, ScriptTable)¶
Opens a data model called name over a table: its fields are what documents with data-model="name" show. Null when there is a model of that name already. Open it before the documents that use it load (a script in the document's head can).
public UiDataModel? OpenDataModel(string name, ScriptTable fields)
Parameters¶
name string
fields ScriptTable
Returns¶
RemoveUpdate(long)¶
public void RemoveUpdate(long id)
Parameters¶
id long
SetSize(int, int, float)¶
Tells the UI how big the screen is, in pixels, and how many pixels a density-independent one is (see
public void SetSize(int width, int height, float density = 0)
Parameters¶
width int
height int
density float
Text(string)¶
Typed text, as UTF-8 characters.
public bool Text(string text)
Parameters¶
text string
Returns¶
Unlisten(long)¶
Takes back a listener (the number
public bool Unlisten(long token)
Parameters¶
token long
Returns¶
Update(float)¶
Lays out what changed and runs animations, deltaSeconds after the last call. Returns whether anything changed.
public bool Update(float deltaSeconds)
Parameters¶
deltaSeconds float