Class UIContext

Namespace
Forma
Assembly
Forma.dll

Owns a UI tree's input state, focus and rendering. Add it to a Game's update/draw loop, or use UIComponent for the usual game component integration.

public sealed class UIContext : IDisposable
Inheritance
UIContext
Implements
Inherited Members

Constructors

UIContext() 

public UIContext()

UIContext(IClipboard)

Creates a context with a host-owned clipboard without probing native platform libraries.

public UIContext(IClipboard clipboard)

Parameters

clipboard IClipboard

Properties

ApplicationCulture

Application locale used by controls with ApplicationLocale.

public CultureInfo ApplicationCulture { get; set; }

Property Value

CultureInfo

Clipboard

Clipboard capability used by copy, cut, and paste commands in retained text controls.

public IClipboard Clipboard { get; set; }

Property Value

IClipboard

CurrentKeyboardState

Keyboard state for the input frame currently being dispatched, including modifier keys used by controls such as Tree.

public KeyboardState CurrentKeyboardState { get; }

Property Value

KeyboardState

CurrentTime

Game time for the input frame currently being dispatched, used by retained multi-click gestures.

public TimeSpan CurrentTime { get; }

Property Value

TimeSpan

DisplayFontResolver

Optionally resolves a denser font atlas for the supplied logical font and display scale.

public Func<SpriteFont, float, SpriteFont> DisplayFontResolver { get; set; }

Property Value

Func<SpriteFont, float, SpriteFont>

DisplayScale

Physical display pixels per logical UI coordinate. Input is mapped back to logical coordinates and drawing is scaled to physical pixels.

public float DisplayScale { get; set; }

Property Value

float

DragData

Payload supplied by the active retained drag source, or null when not dragging.

public object DragData { get; }

Property Value

object

DynamicGlyphDiagnostics

Read-only diagnostics for this context's device-scoped dynamic glyph cache.

public DynamicGlyphCacheDiagnostics DynamicGlyphDiagnostics { get; }

Property Value

DynamicGlyphCacheDiagnostics

EffectiveCursor

Resolves the captured or hit-tested pointer cursor in logical UI coordinates, not keyboard focus.

public Cursor EffectiveCursor { get; }

Property Value

Cursor

FocusedControl 

public Control FocusedControl { get; }

Property Value

Control

InputModality 

public InputModality InputModality { get; set; }

Property Value

InputModality

IsDragging

Whether a retained drag-and-drop operation is currently active.

public bool IsDragging { get; }

Property Value

bool

IsSettled

Whether the UI has stopped moving: every control has had its layout pass and no frame-boundary work is outstanding.

This is what removes fixed frame counts from tests. Advancing "enough" frames and hoping is the single most common source of flakiness in UI tests — too few and the assertion races the layout, too many and every test pays for the slowest case. 

public bool IsSettled { get; }

Property Value

bool

IsTooltipVisible 

public bool IsTooltipVisible { get; }

Property Value

bool

PointerPosition

Most recently dispatched pointer position, available to retained controls that coordinate transient surfaces.

public Point PointerPosition { get; }

Property Value

Point

Resources 

public ResourceDictionary Resources { get; }

Property Value

ResourceDictionary

RootLayoutDirection

Fallback layout direction for root controls whose direction is inherited.

public LayoutDirection RootLayoutDirection { get; set; }

Property Value

LayoutDirection

Roots 

public IReadOnlyList<Control> Roots { get; }

Property Value

IReadOnlyList<Control>

SuppressPolledInput

Whether Update(GameTime, MouseState, KeyboardState) ignores the mouse and keyboard it is handed. Off by default; turn it on when a host drives this context purely through the Inject methods, so the polled pass cannot overwrite what was injected.

public bool SuppressPolledInput { get; set; }

Property Value

bool

SvgRasterDiagnostics

Read-only diagnostics for this context's device-scoped SVG raster cache.

public SvgRasterCacheDiagnostics SvgRasterDiagnostics { get; }

Property Value

SvgRasterCacheDiagnostics

SystemCulture

System locale used by controls with SystemLocale.

public CultureInfo SystemCulture { get; set; }

Property Value

CultureInfo

TextLayoutEngine 

public TextLayoutEngine TextLayoutEngine { get; }

Property Value

TextLayoutEngine

Theme 

public Theme Theme { get; set; }

Property Value

Theme

ThemeIconDiagnostics

Current default icon-atlas resource and lookup counters.

public ThemeIconDiagnostics ThemeIconDiagnostics { get; }

Property Value

ThemeIconDiagnostics

ThemeIconRenderingPolicy 

public ThemeIconRenderingPolicy ThemeIconRenderingPolicy { get; set; }

Property Value

ThemeIconRenderingPolicy

ThemeVariant 

public ThemeVariant ThemeVariant { get; set; }

Property Value

ThemeVariant

TooltipDelay

Delay before hover help becomes visible. Defaults to Godot-like delayed presentation.

public TimeSpan TooltipDelay { get; set; }

Property Value

TimeSpan

TooltipFont

Font used when drawing tooltip text. Assign the same font used by the application UI.

public SpriteFont TooltipFont { get; set; }

Property Value

SpriteFont

TooltipOffset 

public Vector2 TooltipOffset { get; set; }

Property Value

Vector2

TooltipOwner 

public Control TooltipOwner { get; }

Property Value

Control

TooltipPadding 

public Thickness TooltipPadding { get; set; }

Property Value

Thickness

TooltipText 

public string TooltipText { get; }

Property Value

string

TooltipUIFont 

public UIFont TooltipUIFont { get; set; }

Property Value

UIFont

TouchscreenAvailable

Whether retained touch-style interactions should be enabled for pointer input.

public bool TouchscreenAvailable { get; set; }

Property Value

bool

ViewportSize

Available viewport extent in logical UI coordinates, before DisplayScale.

public Vector2 ViewportSize { get; set; }

Property Value

Vector2

Methods

Add(Control) 

public void Add(Control control)

Parameters

control Control

ClearDynamicGlyphCache()

Clears device-scoped dynamic glyph pages between draw calls. Cumulative counters remain available.

public void ClearDynamicGlyphCache()

ClearSvgRasterCache()

Clears device-scoped SVG documents, rasters, and pages between draw calls.

public void ClearSvgRasterCache()

DescribeLayout()

The laid-out UI as indented text with every control's bounds.

public string DescribeLayout()

Returns

string

Remarks

The box model, for working out why something is the wrong size. ToText() omits bounds so golden files do not churn with window size; this is the other half of that trade, and belongs in assertions as well as in diagnosis because it needs no window.

Dispose() 

public void Dispose()

Draw(GraphicsDevice) 

public void Draw(GraphicsDevice graphicsDevice)

Parameters

graphicsDevice GraphicsDevice

GetDynamicGlyphAtlasPages()

Returns immutable grayscale snapshots of currently allocated glyph-atlas pages.

public IReadOnlyList<DynamicGlyphAtlasPageSnapshot> GetDynamicGlyphAtlasPages()

Returns

IReadOnlyList<DynamicGlyphAtlasPageSnapshot>

GetSvgRasterAtlasPages()

Returns immutable RGBA snapshots of currently allocated SVG-atlas pages.

public IReadOnlyList<SvgRasterAtlasPageSnapshot> GetSvgRasterAtlasPages()

Returns

IReadOnlyList<SvgRasterAtlasPageSnapshot>

HitTest(Point) 

public Control HitTest(Point point)

Parameters

point Point

Returns

Control

InjectKeyPress(Keys, params Keys[])

Delivers a key press to the focused control, including shortcut routing, as though it arrived this frame.

Distinct from handing a Microsoft.Xna.Framework.Input.KeyboardState to Update: that replaces the whole keyboard, so it cannot express a chord arriving mid-frame and forces a caller to model key state it does not own. Modifiers travel with the press instead.

Call on the update thread, between frames — the same contract the pointer injection methods follow. Dispatch runs synchronously and reaches handlers that expect to be on the thread that owns the tree. 

public void InjectKeyPress(Keys key, params Keys[] modifiers)

Parameters

key Keys
modifiers Keys[]

InjectKeyRelease(Keys)

Delivers a key release to the focused control. See InjectKeyPress(Keys, params Keys[]).

public void InjectKeyRelease(Keys key)

Parameters

key Keys

InjectPointerMove(Point)

Moves the pointer using physical back-buffer pixels without changing the polled mouse state.

public void InjectPointerMove(Point physicalPosition)

Parameters

physicalPosition Point

InjectPointerPress(Point, PointerButton)

Presses a pointer button at a position expressed in physical back-buffer pixels.

public void InjectPointerPress(Point physicalPosition, PointerButton button = PointerButton.Left)

Parameters

physicalPosition Point
button PointerButton

InjectPointerRelease(Point, PointerButton)

Releases a pointer button at a position expressed in physical back-buffer pixels.

public void InjectPointerRelease(Point physicalPosition, PointerButton button = PointerButton.Left)

Parameters

physicalPosition Point
button PointerButton

InjectPointerWheel(Point, int, Control)

Routes a wheel delta at a position expressed in physical back-buffer pixels.

public bool InjectPointerWheel(Point physicalPosition, int delta, Control fallbackTarget = null)

Parameters

physicalPosition Point
delta int
fallbackTarget Control

Returns

bool

InjectText(string)

Delivers committed text to the focused control, as a completed composition rather than a preedit. This is the text-entry counterpart of InjectKeyPress(Keys, params Keys[]); typing a character through key injection alone would not produce text, because a key is not a character until the platform's input method says so.

public void InjectText(string text)

Parameters

text string

Layout() 

public void Layout()

PrewarmSvg(SvgImageSource, Vector2)

Queues an SVG raster variant for creation before the next UI draw.

public void PrewarmSvg(SvgImageSource source, Vector2 logicalSize)

Parameters

source SvgImageSource
logicalSize Vector2

RegisterFrameBoundaryCallback(Action<GameTime>) 

public IDisposable RegisterFrameBoundaryCallback(Action<GameTime> callback)

Parameters

callback Action<GameTime>

Returns

IDisposable

Remove(Control) 

public bool Remove(Control control)

Parameters

control Control

Returns

bool

SetFocus(Control) 

public void SetFocus(Control control)

Parameters

control Control

TextComposition(string, int, int)

Forwards platform IME preedit text and its selected range to the focused control.

public void TextComposition(string text, int selectionStart = 0, int selectionLength = 0)

Parameters

text string
selectionStart int
selectionLength int

TextInput(char)

Forwards one platform text-input character to the focused retained control.

public void TextInput(char character)

Parameters

character char

TextInput(string)

Forwards one complete platform text commit; LineEdit records it as one edit.

public void TextInput(string text)

Parameters

text string

ToPhysicalPointerPosition(Point)

Converts a logical position -- the space Bounds is reported in -- into the physical one the Inject methods take.

public Point ToPhysicalPointerPosition(Point logicalPosition)

Parameters

logicalPosition Point

Returns

Point

Remarks

The two spaces coincide at DisplayScale 1, which is every headless test, so a test that feeds a control's own Bounds straight to InjectPointerPress passes in CI and then misses the control entirely on a Retina display. Nothing warns you: the click lands somewhere, just not there. Anything deriving a pointer position from a control's geometry should go through this.

Update(GameTime) 

public void Update(GameTime gameTime)

Parameters

gameTime GameTime

Update(GameTime, MouseState, KeyboardState)

Updates the tree from supplied states; this overload makes UI input deterministic in tests.

public void Update(GameTime gameTime, MouseState mouse, KeyboardState keyboard)

Parameters

gameTime GameTime
mouse MouseState
keyboard KeyboardState

WaitForSettled(int)

Runs layout passes until the UI settles, returning whether it did within maxPasses.

Bounded by passes rather than wall-clock time, deliberately: a time budget makes a test behave differently on a loaded machine, which is exactly the flakiness this is meant to remove. Layout converges in a handful of passes or it is not going to. 

public bool WaitForSettled(int maxPasses = 16)

Parameters

maxPasses int

Returns

bool

Events

AdaptiveEnvironmentChanged 

public event EventHandler AdaptiveEnvironmentChanged

Event Type

EventHandler
Edit this page