UiDocument

Remarks

⚠ The half of container queries that turns the other half on. ContainerScopes, ContainerConditions and ContainerQuery were built and tested a day before this and nothing called Enter, so every element of every live document sat at Root — where no query has an eligible container and all of them are false. That is this repository's commonest shape of missing feature, and the thing that distinguishes it from a bug is that a query which never matches is perfectly good CSS: nothing warns, nothing throws, the rule is in the rule set and simply never wins. Recontain is the caller that was owed.

⚠ It runs at the end of Arrange, which is what makes it answerable at all. A verdict is about a measured box, so style decides layout and layout decides style — and the only place in the frame where every box is final is after CalculateLayout. Reading container-type in Apply as doc 43 § D3 suggested would be reading the declaration in the one pass that cannot yet see the result of it; the declaration is read here instead, off the same Style that Apply just wrote.

⚠ The cycle closes in one extra pass, and the bound is SettlePasses rather than a new mechanism. Pass one cascades with every element at the root scope, lays out, and enters the scopes; the walk sees the scopes move and Invalidates, so Settle runs pass two, which cascades with the verdicts in hand and lays out again. For a container whose inline size is a pure function of its parent's — width: auto on a normal-flow block, which takes SizingMode.StretchFit and is sized with no child consulted — pass two measures the same box, so Enter interns to the same ids, nothing moves and the loop converges with Settled true and SettlingPasses equal to one. A container sized by its contents can flip on every pass instead; that does not hang, it exhausts the budget and reports Settled false, which is the visible failure doc 43 § D3 said it would be.

⚠ Which is why Settle no longer returns early when nothing is listening to LayoutFinished. It used to, and that early return was correct while a handler was the only thing that could dirty a document after a layout. This walk is a second such thing, and it is one no application registers for — so a document with a container query and no LayoutFinished handler would have entered its scopes, marked itself dirty, and gone home, showing the verdicts one whole frame late. A panel that resizes visibly a frame after it was dragged is exactly the defect the settle loop exists to prevent.

⚠ Nothing walks at all unless a sheet actually declared a @container, which is the same if that makes Remedia affordable and is worth as much here: no group means no query can be true whatever the scopes say, so the entire walk — and the cold cascade that follows a first assignment — is skipped for every document in this repository that does not use the feature.

Fields and properties (51)

• public IResponder? CommandResponder

  What answers a command id once the element walk has run out of parents.

• public IResponder? ApplicationCommandResponder

  What answers a command id last of all, after the document's own responder.

• public const int ContainerScopeCeiling

  How many chains may be interned before the table is rebuilt from scratch.

• public int ContainerScopesEntered

  How many extra chains the last Update interned, across all its passes.

• public UiCursor Cursor

  What the pointer should look like where it currently is.

• public UiDiagnostics Diagnostics

  What a debug overlay may read about this document.

• public IEditableDocument? HostedDocument

  The document this whole tree is showing, if the application set one.

• public DragSession? CurrentDrag

  The drag in progress, if one is.

• public EditingKeymap EditingKeymap

  Which editing chords the text controls in this document answer.

• public UiElement? Focused

  The element the keyboard is talking to.

• public UiElement? CommandFocus

  The element a command id resolves from — the focus, ignoring the surfaces that show commands.

• public UiElement? Hovered

  The deepest element the pointer is over, or null if it is over nothing.

• public bool KeyboardMode

  Whether the most recent input came from the keyboard.

• public ColorGamut Gamut

  What the primary surface can actually show, which decides @media (color-gamut: …).

• public ColorSchemePreference ColorScheme

  Whether the platform's appearance is light or dark, on the primary surface.

• public MediaPreferences Preferences

  The platform's accessibility settings, on the primary surface.

• public MediaContext Media

  The primary surface's context, as the cascade is evaluating it there.

• public int StylesResolved

  How many elements the last Update cascaded.

• public bool LastPassWasCold

  Whether the last pass had to resolve every element rather than a few.

• public IReadOnlyList<UiSurface> Surfaces

  Everywhere this document is shown, the primary one first.

• public UiSurface Primary

  The surface the document was created with.

• public UiSurface? KeySurface

  The surface the window manager says the user is in, or null if none is.

• public IUiClipboard? Clipboard

  The system clipboard, if this document's head installed one.

• public bool HasClipboard

  Whether cut, copy and paste can reach the operating system from this document.

• public float BaseFontSize

  The root font size this document was constructed with.

• public float RootFontSize

  The font size rem measures against, for every surface of this document.

• public StyleEngine Styles

  The cascade.

• public SystemPalette SystemColors

  What the CSS system colour keywords mean in this document, right now.

• public EffectScheduler Effects

  Where this document's bindings queue, and what a frame drains.

• public StyleUpdater Restyler

  What holds every element's computed style and keeps it that way.

• public LayoutTree Layout

  The flexbox engine.

• public LayoutStyleBuilder Builder

  The step between them.

• public DrawList Drawing

  The commands the last Draw produced.

• public bool Compositing

  Whether a translucent subtree is composited as a group rather than faded in place.

• public LengthContext Viewport

  The primary surface's size and root font size.

• public UiElement Root

  The element every other one descends from.

• public int StylesApplied

  How many elements had a layout style written on the last Update.

• public int StyleCompactions

  How many times the style store has been compacted.

• public const int SettlePasses

  How many times a pass will re-run for handlers that changed something.

• public bool Settled

  Whether the last Update reached a fixed point.

• public int SettlingPasses

  How many extra passes the last Update ran for its handlers.

• public TimeSpan Now

  The last time Tick was given.

• public GestureRecognizer Gestures

  Taps, long presses and drags read out of the pointer stream.

• public UiSurface? PointerSurface

  Which surface the last pointer event was dispatched into.

• public UiElement? Captured

  The element currently receiving every pointer event, if any.

• public FontRegistry Fonts

  The faces a font-family declaration can name.

• public ShapingCache Shaping

  The shaping every element's text goes through.

• public string Language

  What language this document is written in by default, as a BCP-47 tag.

• public IUiWindowHost? Windows

  What turns a surface of this document into a window, if anything can.

• public bool CanOpenWindows

  Whether a control may ask this document for a window of its own.

• public IUndoManager? UndoManager

  The document-wide undo stack, if anything installed one.

Events (8)

• public Action<UiDocument>? AccessibilityInvalidated

  Raised at most once a frame when anything in the accessibility tree may have changed.

• public Action<CloseRequestEvent>? CloseRequested

  Raised after the route, whether or not anything on it refused.

• public Action<UiDocument>? CommandsInvalidated

  Raised at most once a frame when anything a command surface shows may have changed.

• public Action<UiDocument, UiSurface>? KeySurfaceChanged

  Raised for each surface whose key status has just changed.

• public Action<UiDocument, UiSurface>? SurfaceAdded

  Raised when a surface is added or taken away.

• public Action<UiDocument, UiSurface>? SurfaceRemoved
• public Action<UiDocument>? LayoutFinished

  Raised when every box in the document is final for this frame.

• public Action<UiDocument, TimeSpan>? Ticked

  Raised on every Tick.

Methods (68)

• public void InvalidateAccessibility()

  Says that something a screen reader would announce may have changed.

• public bool InvokeAccessKey(char key)

  Activates whatever an access key names, if anything does.

• public void Provide<T>(T value) where T : notnull

  Makes a value available to the whole document.

• public bool Unprovide<T>()

  Takes a document-wide value back.

• public T? Inject<T>()

  The document-wide value of that type.

• public bool TryInject<T>(out T? value)

  The same, told apart from nothing.

• public bool RequestClose(UiCloseReason reason = Quit)

  Asks everything on the route whether the application may close.

• public void InvalidateCommands()

  Says that a command's enablement, name or check state may have changed.

• public UiCursor CursorOf(ComputedStyle style)

  What a computed style asks the pointer to look like.

• public DragSession BeginDrag(UiElement source, DataObject data, DropEffect allowed = Copy)

  Starts an in-app drag carrying a payload.

• public bool CancelDrag()

  Ends the drag with nothing dropped.

• public UiElement? Dispatch(DropEvent args)

  Sends a drop to whatever is under it.

• public UiElement? Dispatch(UiSurface surface, DropEvent args)

  Sends a drop to whatever is under it in one surface.

• public bool Focus(UiElement? element, bool force = false)

  Moves the focus.

• public bool MoveFocus(FocusDirection direction)

  Moves the focus one step round the tab order.

• public static List<UiElement> TabOrder(UiElement scope)

  The elements Tab visits inside a subtree, in the order it visits them.

• public UiElement? Dispatch(WheelEvent args)

  Sends a wheel event to whatever is under it.

• public UiElement? Dispatch(UiSurface surface, WheelEvent args)

  Sends a wheel event to whatever is under it in one surface.

• public UiElement? Dispatch(KeyEvent args)

  Sends a key event to whatever has the focus.

• public UiElement? Dispatch(UiSurface surface, KeyEvent args)

  Sends a key event that arrived at a particular window.

• public UiElement? Dispatch(TextInputEvent args)

  Sends typed text to whatever has the focus.

• public UiElement? Dispatch(UiSurface surface, TextInputEvent args)

  Sends typed text that arrived at a particular window.

• public UiElement? Dispatch(TextCompositionEvent args)

  Sends an input method's pre-edit to whatever has the focus.

• public UiElement? Dispatch(UiSurface surface, TextCompositionEvent args)

  Sends an input method's pre-edit that arrived at a particular window.

• public bool MoveFocus(NavigationDirection direction)

  Moves the focus to whatever lies in a direction.

• public UiElement? FindInDirection(UiElement origin, NavigationDirection direction)

  What lies in a direction from an element.

• public void Reparent(UiElement element, UiElement parent, int index = -1)

  Moves an element, and everything under it, to a different parent.

• public int PropertyId(string name)

  Interns a property name, so a control can read it without a dictionary probe per frame.

• public Color4? ColorOf(ComputedStyle style, int property)

  The colour a computed style gives a property, if it gives one.

• public float? LengthOf(ComputedStyle style, int property)

  The length in pixels a computed style gives a property, if it gives an absolute one.

• public float? NumberOf(ComputedStyle style, int property)

  The bare number a computed style gives a property, if it gives one.

• public string? KeywordOf(ComputedStyle style, int property)

  The keyword a computed style gives a property, if it gives a single one.

• public Vector2? PositionOf(ComputedStyle style, int property, float width, float height)

  The point a computed style's CSS <position> names, resolved in a box.

• public Color4 ForegroundOf(UiElement element)

  An element's color, which is what a control draws itself in.

• public float TextAlignShift(UiElement element, float slack)

  How far along the inline axis a line of text sits, given the room it has spare.

• public float ContentWidthOf(UiElement element)

  The width of an element's content box, which is what a line of its text is aligned in.

• public IReadOnlyList<string> Refusals()

  Everything the document's five diagnostic producers are holding, as text.

• public void ForgetPassRefusals()

  Forgets what the per-pass and per-frame producers have refused, and arranges for the next pass to refuse it all again.

• public UiSurface CreateSurface(float width, float height, float dpiScale = 1, UiElement? owner = null)

  Adds somewhere else to show part of this document.

• public bool RemoveSurface(UiSurface surface)

  Takes a surface, and everything still in it, out of the document.

• public void Resize(UiSurface surface, float width, float height, float dpiScale)

  Changes a surface's size, and the scale of the display it is on.

• public UiSurface? SurfaceOf(UiElement element)

  Which surface an element is shown in.

• public UiDocument(float width, float height, float rootFontSize = 16, ILogger? logger = null)

  Creates a document over a surface of a given size.

• public Component? ComponentAt(UiElement element)

  The component whose host this element is, if it is one.

• public int Load(string css, StyleOrigin origin = Author)

  Loads a stylesheet.

• public bool LoadOnce(object key, string css, StyleOrigin origin = Author)

  Loads a stylesheet once for a key, however many times it is asked for.

• public void ReloadStyles(int sheet, string css)

  Replaces a loaded stylesheet with new text.

• public void Resize(float width, float height)

  Changes the surface's size.

• public void Invalidate()

  Marks the document as needing a fresh pass over every element.

• public UiElement Create(string tag, UiElement? parent, string? id = null, params ReadOnlySpan<string> classNames)

  Creates an element.

• public T Create<T>(string? tag, UiElement? parent, string? id = null, params ReadOnlySpan<string> classNames) where T : UiElement, new()

  Creates an element of a particular type.

• public UiElement Adopt(UiElement element, string? tag, UiElement? parent, string? id = null, params ReadOnlySpan<string> classNames)

  Makes an element this document already has an instance of part of it.

• public void Move(UiElement element, int index)

  Moves an element to another position among its siblings.

• public void Remove(UiElement element)

  Removes an element and everything under it.

• public bool CompactStyles()

  Reclaims the style slots removal left behind.

• public bool Update()

  Runs the passes, if anything has changed since the last one.

• public void Tick(TimeSpan now)

  Lets time pass, for the things that happen because nothing happened.

• public bool Draw()

  Rebuilds the draw list from the current layout and styles.

• public bool Draw(UiSurface surface)

  Rebuilds one surface's draw list.

• public UiElement? HitTest(float x, float y)

  The element a pointer would land on.

• public UiElement? HitTest(UiSurface surface, float x, float y)

  The element a pointer would land on in one surface.

• public UiElement? Dispatch(PointerEvent args)

  Sends a pointer event to whatever is under it.

• public UiElement? Dispatch(UiSurface surface, PointerEvent args)

  Sends a pointer event to whatever is under it in one surface.

• public void CapturePointer(UiElement element)

  Sends every pointer event to one element until it is released.

• public void ReleasePointer()

  Stops sending every pointer event to one element.

• public void Dispose()
• public IUiWindow? WindowOf(UiSurface? surface)

  Which window a surface of this document is being shown in.

• public IUiWindow? WindowOf(UiElement element)

  Which window an element is being shown in.

Used by (525, showing 40)

• GalleryHelloUi
• HierarchyHelloUi
• HudTestsMmo.Ui.Tests
• ShellHelloUi
• StylesheetTestsMmo.Ui.Tests
• DocumentBenchmarksVixen.Benchmarks.Ui
• EditorShellBenchmarksVixen.Benchmarks.Ui
• EditorShellSceneVixen.Benchmarks.Ui
• SceneVixen.Benchmarks.Ui
• AccessKeyTestsVixen.Ui.Tests
• AccessibilityCoverageTestsVixen.Ui.Controls.Advanced.Tests
• AccessibilityCoverageTestsVixen.Ui.Controls.Tests
• AccessibilityNotificationTestsVixen.Ui.Controls.Advanced.Tests
• AccessibilityNotificationTestsVixen.Ui.Controls.Tests
• AccessibilityTestsVixen.Ui.Tests
• AccessibilityTreeTestsVixen.Ui.Controls.Tests
• AccessibilityTreeTestsVixen.Ui.Controls.Advanced.Tests
• AccessibilityTreeTestsVixen.Ui.Tests
• AccessibilityWiringTestsVixen.Platform.Ui.Tests
• AccessibleNameLocalisationTestsVixen.Ui.Controls.Advanced.Tests
• AccessibleNameLocalisationTestsVixen.Ui.Controls.Tests
• AdvancedFixtureVixen.Ui.Controls.Advanced.Tests
• AdvancedThemeVixen.Ui.Controls.Advanced
• AlertVixen.Ui.Controls
• AmbientAcrossDockingTestsVixen.Ui.Controls.Advanced.Tests
• AmbientValueTestsVixen.Ui.Controls.Tests
• AnimationTestsVixen.Ui.Tests
• ApplicationBarTestsVixen.Ui.Controls.Tests
• ApplyAtInstallTestsVixen.Ui.Styling.Utilities.Tests
• AsyncArrivalTestsVixen.Ui.Controls.Tests
• AttachmentSeamTestsVixen.Ui.Tests
• BackdropFilterTestsVixen.Ui.Controls.Tests
• BatchTestsVixen.Ui.Tests
• BidiDirectionTestsVixen.Ui.Tests
• BidiFallbackTestsVixen.Ui.Tests
• BidiMirroringTestsVixen.Ui.Tests
• BindReachTestsVixen.Ui.Controls.Tests
• BorderLonghandTestsVixen.Ui.Tests
• BorderStylePixelTestsVixen.Ui.Testing.Tests
• BorderStyleTestsVixen.Ui.Tests