Control class Core

One interactive part of the drawn UI — the atom of the control-tree concept (docs/control-baum-konzept.md). A control owns its capabilities INHERENTLY: bounds (set by layout — the one geometry source), state (hover/pressed/focus — written only by the ControlHost), behaviour (pointer/keys/text), rendering (reads its own state), spoken label and cursor shape. A pane COMPOSES controls; it no longer implements input, hover, focus or hit-testing itself — which is exactly why a new control cannot get those wrong.

public abstract class Control
Namespace
ArionUI.Presentation.Controls
Package
ArionUI.Presentation · dotnet add package ArionUI.Presentation --prerelease

Overview

Control is the base class of every drawn control: Label, Button, TextBox, CheckBox, Board and the rest. It carries what they have in common, so the identity (Id), style classes, live availability (EnabledWhen, VisibleWhen), tooltip, accessible name and validation state work the same on all of them.

For a control of your own, derive from it: Render is the one member you must implement, Measure the one you usually override.

Common members
using ArionUI.Presentation.Controls;   // Control and the drawn controls

var save = new Button
{
    Id = "save",                                   // targeted focus and tests
    Text = () => "Save",
    Click = Save,
    Classes = ["primary"],                         // what style sheet rules select
    EnabledWhen = () => customer.HasChanges,       // a live probe, not a flag to keep in sync
    Tooltip = () => customer.HasChanges ? "Save the changes" : "Nothing to save",
};

var name = new TextBox
{
    Id = "name",
    Spoken = () => "Customer name",
    VisibleWhen = () => !customer.IsArchived,
};

// On the UI thread: an invalid control is framed and offers the message as its tooltip.
name.Error = name.Text.Length == 0 ? "A name is required." : null;

Read more

Constructors

Control

protected Control();

Properties

AccessibleDescription

public virtual string? AccessibleDescription { get; }

What a reader says about this control after its name (a chart tile: its kind, series and ranges); its help text. Null for nothing.

AccessibleName

public Func<string>? AccessibleName { get; init; }

What assistive technology calls this control, asked each time; null leaves it to Control.SpokenLabel. On a board tile that holds several controls it names the tile's group and wins over the caption the tile opens with.

AccessibleRange

public virtual AccessibleRange? AccessibleRange { get; }

The range of a part that picks a value along one (a slider); null otherwise.

AccessibleValue

public virtual string? AccessibleValue { get; }

The text of a text part; null when the part carries no value.

Bounds

public LogRect Bounds { get; protected internal set; }

Where this control IS — written by Control.Arrange, read by rendering, hit-testing and the focus ring alike. One source, so they can never drift apart again.

CanTakeFocus

public bool CanTakeFocus { get; }

Focusable, enabled and Control.Shown: a button in a hidden panel is no tab stop.

CaretRect

public virtual LogRect? CaretRect { get; }

Where the caret of a text sink stands, absolute like Control.Bounds and as last drawn; null for a control without a caret or before it was drawn. The host anchors the input method's candidate window here.

ChildClip

public virtual LogRect? ChildClip { get; }

The box this control shows its children in (a scrolling panel's viewport); null when it does not clip them. Parts outside it are offscreen to a reader.

Children

public virtual IEnumerable<Control> Children { get; }

The controls inside this one, in tree order (visual order, tab order). A host keeps the tree it adopted: a control whose children change once it is adopted says so with Control.TreeChanged (on a shown board inside Board.Mutate), or its new children get no host and Tab, ticks and the wheel do not find them.

Classes

public IReadOnlyList<string> Classes { get; set; }

The control's style classes, which the rules of the style sheets select (Select.Type<Button>().Class("primary")) - CSS's class attribute. On a shown board change them inside Board.Mutate.

ClassesFrom

public Func<IReadOnlyList<string>>? ClassesFrom { get; init; }

Control.Classes read from the application's state - a chip that is selected while its option is the chosen one. Read when the control is built and again with every change of a shown board (Board.Mutate), so whatever the change touched, the classes follow; null: the classes are set.

ContextMenu

public Func<IReadOnlyList<MenuItem>>? ContextMenu { get; init; }

The entries of the control's context menu - opened by the right button or the menu key (Shift+F10) while it or a control inside it holds the focus; null for none. Asked when the menu opens, so the entries may depend on the state; build them without side effects. On a board the menu opens in the grid's pane stack.

Cursor

public virtual GridCursor Cursor { get; }

The pointer shape over this control: the arrow (GridCursor.Default) over buttons, options, tabs and everything else that is clicked, the I-beam (GridCursor.Text) over text that can be typed in, the hand only over a link - the Windows rule. A control with parts of different shapes answers Control.CursorAt.

DrawsOwnFocus

public virtual bool DrawsOwnFocus { get; }

The control shows its focus itself (accent border, hover row, ring parameter). False = the host draws the shared default ring around Control.Bounds.

Enabled

public bool Enabled { get; }

EnabledWhen

public Func<bool>? EnabledWhen { get; init; }

Live availability probe (a row whose command has nothing to do, an empty list). Null = always enabled.

Error

public string? Error { get; set; }

What is wrong with the value the control holds, as the application (or an ControlValidation binding to its model) says; null or empty when it is valid. An invalid control shows TileStates.Invalid (the theme frames it in red and marks it), offers the message as its tooltip and to assistive technology, and a reader hears it when it appears while the control holds the focus. Set it on the UI thread; it repaints only the control.

Focusable

public virtual bool Focusable { get; }

Can this KIND of control hold the keyboard focus? Combined with the live probes in Control.CanTakeFocus.

ForcedStates

public TileStates ForcedStates { get; set; }

States the control shows whatever the pointer and the focus do - the "force state" of a browser's developer tools, for a style guide that shows a button hovered and pressed side by side. Only the look follows; the control behaves as before. On a board the control's tile shows them too. Change it on the UI thread (inside Board.Mutate on a shown board).

Host

public ControlHost? Host { get; }

Id

public string Id { get; init; }

Identity for targeted focus, tests and (later) automation peers.

IsDragHandle

public bool IsDragHandle { get; init; }

A part of a movable board tile the user grabs to drag the tile, as by its frame (a panel's title): a press on it starts the board's move or docking. Mark the label of the title itself, not the container around it: only the control under the pointer is asked, so a button beside the label keeps its press.

IsFocused

public bool IsFocused { get; }

Derived, never stored — there cannot be two focused controls.

IsHovered

public bool IsHovered { get; }

IsHoveredWithin

public bool IsHoveredWithin { get; }

The pointer is over a part of this control (Control.TakesHoverOfParts): it is drawn hovered as if over itself. Written by the host.

IsPressed

public bool IsPressed { get; }

Armed: the pointer went down on this control and has not been released yet. Acting on release-over-the-same-control is the host's capture rule.

IsRegion

public bool IsRegion { get; init; }

A region of the window (a side bar, a header, a scene): F6 moves the keyboard from region to region, Shift+F6 back, as between the panes of a desktop window; Tab walks inside one. The keyboard lands where it last was in the region, else on its first tab stop. A tree with fewer than two regions leaves F6 to the window around it.

Role

public virtual ControlRole Role { get; }

What KIND of part this is for assistive technology — the automation peers translate it into their host's control type.

TakesHoverOfParts

protected internal virtual bool TakesHoverOfParts { get; }

Whether the control shows the hover of the controls inside it as its own - a chip stays hovered while the pointer is on one of its action buttons. False by default.

ToggleState

public virtual bool? ToggleState { get; }

The checked state of a toggle part; null when the part does not toggle.

Tooltip

public Func<string?>? Tooltip { get; init; }

The text shown after a moment over the control, through the grid's tooltip (the same delay and placement as a cell's); null for none. Asked on the UI thread each time the pointer comes to rest. An invalid control shows its Control.ValidationMessage instead.

ValidationMessage

public string? ValidationMessage { get; }

The message the control shows for its value: its own reading of the input first (InputError), else Control.Error; null while the value is valid.

Visible

public bool Visible { get; }

VisibleWhen

public Func<bool>? VisibleWhen { get; init; }

WantsText

public virtual bool WantsText { get; }

Is this control a text sink? The host routes typing to the focused text control, or — the Excel rule — jumps to the FIRST one in the tree.

WantsTick

public virtual bool WantsTick { get; }

The control animates and wants Control.Tick on every frame.

Methods

Announce

protected void Announce(string text);

Arrange

public virtual void Arrange(LogRect bounds);

CursorAt

public virtual GridCursor CursorAt(LogPoint p);

The pointer shape over the part of this control under p (absolute): the I-beam over a field's text, the arrow over its buttons. Default: Control.Cursor. A disabled control shows the arrow whatever it answers, and while a press is held the shape it began with stays (ControlHost.CursorAt).

ExplainStyle

public IReadOnlyList<StyleDeclaration> ExplainStyle(TileStates states);

Every declaration the cascade weighs for this control in states, under the sheets its look was resolved from (its board's chain, or the theme's alone) - what StyleSheet.ExplainControl tells, the Styles pane of a browser.

HitTest

public virtual Control? HitTest(LogPoint p);

The control under an ABSOLUTE point, or null. Containers recurse; leaves answer for themselves. Same bounds the render pass used.

Invalidate

protected void Invalidate();

This control's look changed: repaint its bounds (and the focus ring or glow around them). A host that only repaints whole is told to do that.

Invalidate

protected void Invalidate(LogRect area);

Repaint area (absolute, like Control.Bounds) - for a control whose look reaches beyond its own bounds.

Invoke

public virtual bool Invoke();

Act like a click on the part (a button fires, a checkbox flips, a menu row runs, a dropdown opens). False when the part has no action or is disabled.

Measure

public virtual LogSize Measure(LogSize available);

Desired size given the space available (layout containers sum this).

OnActivate

protected internal virtual void OnActivate();

A click: the pointer went down on this control and came up over it again. The host calls it after Control.OnPointerReleased - not after a drag, a cancelled gesture or a release elsewhere, and not while the control is disabled or hidden. The one place a control acts on a click.

OnAttached

protected internal virtual void OnAttached();

A host shows the tree this control is in: it joined a shown board, or the board's view was attached. UI thread, under the render gate; the render pass may be running on the UI thread, so ask for frames here (Control.RequestTick), not for a repaint.

OnDetached

protected internal virtual void OnDetached();

The control is no longer shown: it left the tree, or the host let the tree go. Release what only a shown control needs - GPU resources, subscriptions.

OnFocusChanged

public virtual void OnFocusChanged();

Focus arrived at or left this control (read Control.IsFocused). For side effects the host cannot know — a list syncing its hover row.

OnKey

public virtual bool OnKey(ArionKey key, ArionModifiers mods);

Keys while focused. Return false to let the pane's fallback see the key.

OnPointerLeft

public virtual void OnPointerLeft();

The pointer stopped hovering this control (moved on or left the pane).

OnPointerMoved

public virtual void OnPointerMoved(LogPoint p, bool buttonDown);

OnPointerPressed

public virtual void OnPointerPressed(LogPoint p, ArionModifiers mods, int clickCount);

OnPointerReleased

public virtual void OnPointerReleased(LogPoint p);

OnSidewaysWheel

public virtual bool OnSidewaysWheel(LogPoint p, double delta);

A sideways wheel step over this control (a tilted wheel, a touchpad pan to the side), in notches, positive towards the start. Return true when it scrolled.

OnText

public virtual void OnText(string text);

OnWheel

public virtual bool OnWheel(LogPoint p, double delta);

Render

public abstract void Render(IRenderSurface s, ControlFrame frame);

RequestTick

protected void RequestTick();

Asks the host for frame ticks: from the next one on, Control.WantsTick is asked again. For a control that starts animating outside an input the host delivers - data arriving, a timer. Any thread.

SetAccessibleRangeValue

public virtual bool SetAccessibleRangeValue(double value);

Set the value of a range part, as the user could. False when the part has no range or is disabled.

SetAccessibleValue

public virtual bool SetAccessibleValue(string value);

Replace the text of a text part. False when the part carries no value.

ShowsFocusRing

protected bool ShowsFocusRing(TileStates states);

Whether the control draws its focus ring in states: focused, and the focus came by the keyboard (ControlHost.FocusVisible) - or the control takes text, whose ring shows however it got the focus (:focus-visible).

SpokenLabel

public virtual string? SpokenLabel();

What a screen reader speaks when this control receives the focus. A control that cannot take the focus but answers here is READ: it becomes a text part.

StatesIn

protected TileStates StatesIn(ControlFrame frame);

The states the control is in for this frame: the pointer's, the focus while the frame holds the keyboard, disabled, and the Control.ForcedStates.

StyleIn

protected ComputedStyle StyleIn(TileStates states);

The control's style in states, resolved against the current theme - what a control draws its face with. A look-up, no cascade.

Tick

public virtual void Tick(double dtMs);

One frame of the animation. What it changes on screen it marks itself (Control.Invalidate): on a board only the marked area is drawn again.