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
dataWhat is dragged, and from where.
originWhere 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.