ControlHost class Core

The one input router of a control tree (docs/control-baum-konzept.md): hit-testing over the same bounds the layout set, FOCUS FOLLOWS THE CLICK, exclusive hover with a pointer-left signal, capture from press to release, Tab traversal in tree order with announcement, keys to the focused control, typing to the focused text sink or — the Excel rule — to the first one, and the default focus ring for controls that do not draw their own.

public sealed class ControlHost
Namespace
ArionUI.Presentation.Controls
Package
ArionUI.Presentation · dotnet add package ArionUI.Presentation --prerelease

Constructors

ControlHost

public ControlHost();

Fields

DragDeadZone

public const double DragDeadZone = 4;

How far the pointer moves from a press before a drag of what was pressed begins: less is a shaky click.

Properties

Announce

public Action<string>? Announce { get; set; }

The spoken channel — the pane forwards its announcer here once.

AreaInvalidated

public Action<LogRect>? AreaInvalidated { get; set; }

Repaint sink for an AREA (absolute coordinates) - set by a host that repaints in parts (a board repaints the bands the area touches). Unset, every area request repaints whole through ControlHost.Invalidated.

CaretRect

public LogRect? CaretRect { get; }

The caret of the focused control where it stands now, absolute; null without one.

Clipboard

public IClipboardText? Clipboard { get; set; }

The clipboard the tree's text boxes copy to and paste from; null (the default) leaves Ctrl+C, Ctrl+X and Ctrl+V to the host.

DeviceScale

public double DeviceScale { get; set; }

Device pixels per logical unit, for layouts that snap to the pixel grid.

Drag

public DragData? Drag { get; }

The drag under way, or null.

DropTarget

public IDropTarget? DropTarget { get; }

The target that would take the drag where the pointer is now, or null.

Focused

public Control? Focused { get; }

FocusedId

public string? FocusedId { get; }

Focused control's Id — the observable seam for tests and peers.

FocusVisible

public bool FocusVisible { get; }

Whether the focus ring shows (:focus-visible): the last input in the window was a key, not a pointer. A press turns it off, a key (other than a modifier alone) on; focus given in code keeps what the last input said. A text field shows its ring either way (its caret is where the keys go), see Control.ShowsFocusRing. One state per outermost grid or surface (in practice one per window): a pane and the board it opened from share it, a board in a tile and the board around it too (ControlHost.Modality).

HasTextSink

public bool HasTextSink { get; }

Does the tree contain a text sink at all? Panes answer WantsTextInput with this instead of hard-coding it.

Invalidated

public Action? Invalidated { get; set; }

Repaint request sink — the pane forwards its Invalidated event here.

IsAttached

public bool IsAttached { get; }

Whether a host shows this tree now. While it does, every control of it that is shown - visible up its parents, not hidden by a breakpoint - has had Control.OnAttached; one that leaves the tree or is hidden, or the whole tree when the host lets it go, has Control.OnDetached.

KeepsCtrlTab

public bool KeepsCtrlTab { get; set; }

Whether Ctrl+Tab that no tab control in the tree takes stays here (a board in a grid; the default) or goes on to the host (a control surface sets false).

MeasureText

public Func<string, TextStyle, double>? MeasureText { get; set; }

The host's text measure, for controls that size themselves by their text (a label in an auto-sized board track). Null leaves them at their own measure or an estimate.

PresentRequested

public Action? PresentRequested { get; set; }

Only what is stamped at present changed (a ring, a tile's hover band): a frame, but nothing of the kept picture is repainted.

Root

public Control? Root { get; }

The root of the tree, or null before ControlHost.SetRoot.

WantsTick

public bool WantsTick { get; }

WrapsFocus

public bool WrapsFocus { get; set; }

True (the default): Tab after the last control starts again at the first - a modal pane keeps the keyboard. False: ControlHost.MoveFocus drops the focus and answers false after the last control, so the host's own tab order carries on.

Methods

AccessibleChildren

public IReadOnlyList<AccessiblePart> AccessibleChildren(string? groupId);

The shown parts directly inside the group groupId, in tree order; null asks for the parts at the top of the tree. Empty for a part that is no group.

AccessiblePartOf

public AccessiblePart? AccessiblePartOf(string id);

ONE part, read live — what an automation peer asks for every property it is questioned about.

It used to build the WHOLE list for each of those questions, and a peer is asked about ten: name, role, enabled, focused, bounds, offscreen, and the pattern tests. A screen reader stepping through a pane with twenty parts therefore walked the control tree two hundred times for one read, allocating a record per control each time. Now the walk happens once per tree SHAPE and the answer is a lookup.

AccessibleParts

public IReadOnlyList<AccessiblePart> AccessibleParts();

The tree's parts as assistive technology sees them, in tree order — what the hosts' automation peers are fed from: every visible focusable control (the tab stops a keyboard user can reach) and every control that is only READ (a label, a named drawing). A part scrolled out of a clipping container is marked AccessiblePart.Offscreen. Every part has an id of its own: a control without one gets it from its position ("text:3", "control:2"), a second control with the same id gets a suffix ("save~2"), stable while the tree keeps its shape.

On a board, a tile is a ControlRole.Group when it has a Control.AccessibleName and holds parts, or when it holds several parts and opens with a text: the text then names the group and is not listed a second time. The parts inside a group name it as their AccessiblePart.ParentId. This list holds the groups and their parts alike; ControlHost.AccessibleChildren walks it as a tree.

Arrange

public void Arrange(LogRect bounds);

BeginDrag

public bool BeginDrag(DragData data, LogPoint origin);

Starts dragging data - called by the control that holds the pressed pointer, usually from Control.OnPointerMoved once the pointer left a small dead zone. From then on the pointer's moves go to the drop targets under it (IDropTarget, the nearest that accepts among the control under the pointer and its parents) instead of the source; the source is drawn under the pointer as a ghost, over everything; near the edge of a scrolling panel the panel scrolls on its own; the release drops on the target that accepts, Escape or a lost capture cancels. Either way the source hears its release as one that lands nowhere, so a drag is never a click, and the control under the pointer is hovered again at once. False when no press is held or a drag is under way already.

Parameters

data

What is dragged, and from where.

origin

Where the pointer went down (absolute): the ghost keeps the offset the source had from it.

BeginDragPastDeadZone

public bool BeginDragPastDeadZone(Control source, LogPoint p, Func<DragData> data);

Starts a drag of source - the control that holds the pressed pointer - once the pointer at p is past the ControlHost.DragDeadZone from where it went down: the one dead zone of every control that drags. data is made only then. False while the pointer is within the dead zone, when another control holds the press or a drag is under way.

CancelDrag

public void CancelDrag();

Cancels the drag under way, as Escape does; the press stays held.

CancelPointer

public void CancelPointer();

The gesture was cancelled (Esc, capture lost): the captured control lets go without acting - its release lands nowhere.

ClearFocus

public void ClearFocus();

No control holds the focus any more (the keyboard left the tree).

CursorAt

public GridCursor CursorAt(LogPoint p);

The pointer shape at p (absolute): what the part of the control under it asks for (Control.CursorAt), the arrow over a disabled control and where no control is. While a press is held the shape it began with stays, wherever the pointer goes - a drag-select that leaves its text box keeps the I-beam, a spin button held while the pointer slides over the text keeps the arrow.

FindControl

public Control? FindControl(string id);

The VISIBLE control with this id, or null — the seam the automation peers act through (Invoke/Toggle/Value on a part). Filters like ControlHost.AccessibleParts on visibility, and the default empty id matches nothing: a hidden part is not an element, so it cannot be acted on either. A part's own id (a suffixed one too) finds the control behind it.

HasNextTabStop

public bool HasNextTabStop(bool reverse);

Whether Tab (Shift+Tab: reverse) has a control to go to without wrapping - the question a host asks before it claims the key.

Invalidate

public void Invalidate();

Invalidate

public void Invalidate(LogRect area);

Repaint area; the whole tree when the host repaints only whole.

Measure

public LogSize Measure(LogSize available);

MoveFocus

public bool MoveFocus(bool reverse);

Tab/Shift+Tab: next/previous focusable control in tree order, wrapping unless ControlHost.WrapsFocus is off. From "no focus" it enters at the first (or last). Announces the arrival. False when there is nothing to move to - with wrapping off also after the last control, whose focus is then dropped.

MoveFocus

public bool MoveFocus(bool reverse, bool wrap);

As ControlHost.MoveFocus, wrapping after the last control only with wrap - a host that hands the keyboard on to its own tab order steps without wrapping whatever the tree was made for.

MoveToNextRegion

public bool MoveToNextRegion(bool reverse);

Moves the keyboard to the next region of the tree (Control.IsRegion), or with reverse to the previous one, in tree order and around: to where it last was there, else to the region's first tab stop. False, moving nothing, when the tree has fewer than two regions that can take the keyboard.

OnAccessKey

public bool OnAccessKey(char letter);

An access key: Alt with letter (or the letter alone while the menu bar holds the keyboard) opens the menu of the menu bar whose caption marks that letter with an ampersand ("&File"). False when no menu answers to it.

OnKey

public bool OnKey(ArionKey key, ArionModifiers mods);

OnPointerLeft

public void OnPointerLeft();

The pointer left the tree: the hovered control loses its hover.

OnPointerMoved

public void OnPointerMoved(LogPoint p, bool buttonDown);

OnPointerPressed

public bool OnPointerPressed(LogPoint p, ArionModifiers mods, int clickCount = 1);

Press: hit-test, FOCUS FOLLOWS THE CLICK, capture, forward. This single method is why "click it, then use the arrows" works in every pane forever.

OnPointerReleased

public void OnPointerReleased(LogPoint p);

OnSidewaysWheel

public bool OnSidewaysWheel(LogPoint p, double delta);

A sideways wheel step, passed on as ControlHost.OnWheel passes an upright one.

OnText

public bool OnText(string text);

Typing goes to the focused text sink — or, the Excel rule, jumps to the FIRST text control of the tree and types there. False = no sink at all.

OnWheel

public bool OnWheel(LogPoint p, double delta);

The wheel goes to the control under the pointer and, when that one does not scroll, on to the controls around it - text inside a scrolling panel must scroll the panel, it cannot scroll itself.

OpenPane

public bool OpenPane(IOverlayContent pane, LogRect anchor, object ownerKey, OverlayPlacement placement = default, Action? onClosed = null);

Opens pane (a dropdown list, a menu) under anchor (absolute, like Control.Bounds) in the pane stack of the tree - the grid's that shows the board, or the surface's own. onClosed runs once it is gone, however it closed. False when the tree has no stack.

Render

public void Render(IRenderSurface s, ControlFrame frame);

RequestPresent

public void RequestPresent();

Asks for a frame that only presents again (ControlHost.PresentRequested).

SetFocus

public bool SetFocus(string id);

Put the focus on a specific control (a pane that opens with its search box active). No announcement — this is programmatic, not a user move.

SetRoot

public void SetRoot(Control newRoot);

Make newRoot the tree - also to announce that the SAME root changed its shape (controls added or removed): every control is adopted again, the automation index is rebuilt, and a focus, hover or capture on a control that left the tree is dropped.

TabStops

public IReadOnlyList<string> TabStops();

The ids of the controls Tab visits, in tree order - what a host walks when it hands Tab on to its own tab order after the last one. Readable parts are no tab stops.

Tick

public void Tick(double dtMs);

Moves every control that animates (Control.WantsTick) on by dtMs. A control at rest is not ticked: the frames a host draws for another reason - a fade elsewhere, the repaint flash - must not repaint it.

Events

FocusChanged

public event Action? FocusChanged;

PartsChanged

public event Action? PartsChanged;

The parts changed their shape without the root changing: controls joined or left (the cards of a feed near the view). A host's automation peers ask for the children again.

PartStateChanged

public event Action<Control>? PartStateChanged;

A part's selected, checked or expanded state changed, or its value: the hosts' automation peers raise the property event (SelectionItem, Toggle, ExpandCollapse, Value). Raised by the control on the UI thread.