Board class Core

A grid of tracks that places controls in cells - the positioning grid of the drawn UI, like XAML's Grid or CSS grid. Columns and rows are sized Track.Px, Track.Auto or Track.Star; columns may also repeat as many times as fit (Track.AutoFit). A tile sits in given cells (Board.Add) or is placed by the board in reading order (Board.Flow); it may span several rows and columns; gaps and padding keep the rhythm. A board is a Control, so boards nest (a form inside a dashboard); the top-level one is shown and virtualized by a BoardView.

Measuring follows XAML: auto columns from their tiles, then star columns share the width, then auto rows are measured at the width of their tiles, then star rows share the height. Where the height is unbounded (a scrolling board, an auto row of a parent) star rows take their content size. Tiles on rows or columns beyond the declared tracks get implicit auto tracks.

Tiles are styled like CSS: each carries classes, the rules of the style sheets (Board.StyleSheet, inherited by nested boards) select them by class and state (hover, focus within, pressed, disabled), and a change of state blends over the rule's ArionTransition. A raised tile (ArionStyle.Lift) is drawn over its neighbours. The same sheets style the controls on the board (Select.Type<Button>()).

Like CSS media queries, breakpoints (Board.When) change tracks, gaps, placement and style rules with the board's width. They are weighed again only when the width crosses one of their thresholds.

Once shown, the board changes on the UI thread only. Its own changes - tiles, properties, a nested board's too - take the render gate and re-lay it out by themselves; what the tiles DRAW (the application's values and texts) changes inside Board.Mutate, so the render thread never reads a half-made change. A board of more than Board.ExactLayoutLimit tiles measures a changed tile out of view when it comes into view, not with the change.

public sealed class Board : Control
Namespace
ArionUI.Presentation.Controls
Package
ArionUI.Presentation · dotnet add package ArionUI.Presentation --prerelease
Inherits
Control

Overview

Board is the layout control of the drawn UI: tracks for columns and rows as in a CSS grid, tiles placed into cells, gaps and padding. Tracks can be fixed, sized to their content or share the rest by weight.

Breakpoints added with When re-arrange the board by its own width, like a container query. A board is itself a Control, so boards nest, and BoardView shows the top-level one in any grid control.

Dashboard.cs
using ArionUI.Core;                  // Track
using ArionUI.Presentation;          // BoardView
using ArionUI.Presentation.Controls; // Board, Label, Button, TileAlign

var board = new Board
{
    Columns = [Track.Px(220), Track.Star()],
    Rows = [Track.Auto, Track.Star()],
    ColumnGap = 16,
    RowGap = 16,
    Padding = 24,
};

board.Add(new Label { Text = () => "Orders" }, row: 0, col: 0, colSpan: 2, classes: "card")
     .Add(new Button { Text = () => "Refresh", Click = Refresh }, row: 1, col: 0, vAlign: TileAlign.Start)
     .Add(new Label { Text = () => status, MaxLines = 3 }, row: 1, col: 1, classes: "card")
     .When(minWidth: 1200, wide => wide.Padding = 40);

// ArionGrid on Avalonia or WPF, ArionGridControl on WinForms
grid.MainView = new BoardView(board);

// Later, on the UI thread: what the tiles read changes inside Mutate.
board.Mutate(() => status = "Up to date");

Read more

Constructors

Board

public Board();

Properties

Breakpoints

public IReadOnlyList<BoardBreakpoint> Breakpoints { get; }

The breakpoints in the order they were added.

CanTakeSplit

public bool CanTakeSplit { get; }

Whether the board can take a split tree (Board.Split): it is no feed and has neither breakpoints nor repeating columns.

Children

public override IEnumerable<Control> Children { get; }

Reading order (row, then column): the order Tab walks.

ColumnGap

public double ColumnGap { get; set; }

Space between neighbouring columns.

ColumnOverrides

public IReadOnlyDictionary<int, TrackSize> ColumnOverrides { get; }

The track sizes the user set (or Board.OverrideColumn), by column index; they replace the declared rules of those columns.

Columns

public IReadOnlyList<TrackSize> Columns { get; set; }

The size rules of the columns; tiles beyond them get auto columns. At most one rule may repeat (Track.AutoFit, Track.AutoFill). An active breakpoint may replace them; this is the board's own.

Docking

public bool Docking { get; set; }

Whether a tile dragged by its frame may dock beside another tile or at an edge of the board, as well as swap places with it: a new column or row opens there and the dragged tile takes it. Applies to tiles in given cells (not to tiles the board places itself) on a board whose columns do not repeat; needs Board.MovableTiles. Default: false.

ExactLayoutLimit

public int ExactLayoutLimit { get; set; }

Up to this many tiles (the default 500), every change of the shown board measures every tile again, near the view or not; above it only the tiles near the view that changed (see Board.Mutate), so a change costs the same on a board of any size. Above it a resize, too, measures only the tiles near the view; the others keep what they needed and are measured when they come into view. Read on the top-level board.

FeedStats

public FeedStats? FeedStats { get; }

What the feed knows about its heights, and its cards; null for a board of tiles.

History

public EditJournal History { get; }

The history of what the user arranged on this board - splitter drags and moved tiles. Ctrl+Z and Ctrl+Y on the board undo and redo it; an application may show it as an Undo button. Changes through the API are not recorded.

MinTrackSize

public double MinTrackSize { get; set; }

The smallest size a splitter leaves a track, where the track's own minimum is smaller. Default 40.

Mode

public BoardMode Mode { get; set; }

How a top-level board uses the window's height; a nested board fills the height its tile gives it.

MovableTiles

public bool MovableTiles { get; set; }

Whether the user may drag tiles by their frame (the padding between a tile's edge and its control). Dropped on a tile the board places itself, a flowing tile takes its place in reading order before or after it; dropped on a tile in given cells, the two tiles swap their cells. Default: false.

Padding

public Insets Padding { get; set; }

Space between the board's edge and its tracks (the board's own; an active breakpoint may replace it).

RowGap

public double RowGap { get; set; }

Space between neighbouring rows.

RowOverrides

public IReadOnlyDictionary<int, TrackSize> RowOverrides { get; }

The track sizes the user set (or Board.OverrideRow), by row index.

Rows

public IReadOnlyList<TrackSize> Rows { get; set; }

The size rules of the rows; tiles beyond them get auto rows. Rows do not repeat.

Split

public SplitNode? Split { get; set; }

Places the tiles by a split tree instead of the tracks the code declared, as Visual Studio arranges its windows: each branch divides its area among its children, each group fills one area. The board turns the tree into star columns and rows at every edge of an area, so a board with a tree lays out, draws, scrolls and saves like any other; Board.Columns and Board.Rows then show those tracks (Board.TracksArranged). The splitters (Board.Splitters) move the boundaries between the children of a branch. Tiles the tree leaves out join it in an area at the end; a tile added later does too, and a removed one leaves it. Setting Board.Columns, Board.Rows or null ends the tree; the tiles keep the cells it gave them. Null by default.

Exceptions

ArgumentException

The tree names a control that has no tile here, or one twice, holds an empty group or branch, or a share that is not positive.

InvalidOperationException

The board is a feed, has breakpoints or repeating columns.

Splitters

public BoardSplitters Splitters { get; set; }

Which track boundaries the user may drag with the mouse. A splitter shows where no tile spans across the boundary and neither track sizes by its content (Track.Auto); between two star tracks it shares their weight anew (the other tracks keep their size), elsewhere the two tracks take fixed sizes that add up to what they had. A double-click gives both tracks back their declared rules. Columns with a repeating rule (Track.AutoFit) have no splitters. Default: none.

StyleSheet

public StyleSheet? StyleSheet { get; set; }

The board's own style rules, laid over the sheets of the boards around it (and all of them over the theme's StyleSheet.Default); the boards inside its tiles inherit them. Null adds no rules.

Tiles

public IReadOnlyList<BoardTile> Tiles { get; }

The tiles in the order they were added (later ones draw on top).

TracksArranged

public bool TracksArranged { get; }

Whether docking changed the board's columns or rows (Board.Columns, Board.Rows): a saved layout then keeps them. Setting either from code clears it.

WantsTick

public override bool WantsTick { get; }

True while a tile blends into a new look.

Methods

Add

public Board Add(Control control, int row, int col, int rowSpan = 1, int colSpan = 1, TileAlign hAlign = default, TileAlign vAlign = default, Insets margin = default, string? classes = null, ArionStyle? style = null);

Places control in the cell at row, col, spanning rowSpan rows and colSpan columns. Returns the board, so tiles chain.

Parameters

control

What the tile shows.

row

First row, from 0.

col

First column, from 0.

rowSpan

Rows covered, at least 1.

colSpan

Columns covered, at least 1.

hAlign

Where the tile sits across its cell area.

vAlign

Where the tile sits along its cell area.

margin

Space between the cell area and the tile.

classes

The tile's style classes, space-separated ("card kpi").

style

The tile's own style, over every rule; null for none.

Arrange

public override void Arrange(LogRect bounds);

Lays the tracks out in bounds - star rows fill its height - and places the tiles.

ArrangeTracks

public void ArrangeTracks(IReadOnlyList<TrackSize> columnRules, IReadOnlyList<TrackSize> rowRules);

Puts back columns and rows that docking arranged (a saved layout): they replace Board.Columns and Board.Rows and count as arranged, so the next saved layout keeps them. The user's track sizes are cleared; the layout sets its own after.

ClearOverrides

public void ClearOverrides();

Gives every track back its declared rule.

CursorAt

public override 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).

DockTile

public bool DockTile(Control control, Control? target, DockSide side);

Docks the tile of control beside the tile of target (or at the board's edge when target is null): the target splits in the middle of its whole span (across a middle track that splits in two where it spans an odd number of them), and the tile takes the half at side; at the board's edge a track of a quarter of the board opens. With a Board.Split tree the area of the target splits likewise in the tree, and the areas the tile leaves close. Tracks the tile leaves empty go; its old cells go to the tiles beside them. DockSide.Center swaps the two tiles; in a split tree it makes the tile a tab of the target's group, shown (swap there with Board.SwapTiles). False when a tile is missing, any tile of the board flows, the board cannot dock (its columns repeat, it has breakpoints, or it is a feed), or the tile would leave a hole it cannot fill (spans that turn like a pinwheel). Once the board was laid out (and up to Board.ExactLayoutLimit tiles) also false when a tile would end narrower or lower than Board.DockMinSize (unless it was before); a board that fits its view may overflow it then and scroll. Cells the app leaves empty on purpose stay empty, and a dock that would open another one beside them is refused.

Explain

public IReadOnlyList<StyleDeclaration> Explain(Control control);

What the cascade weighed for the tile of control in its states of the moment: every declaration of every rule that picks it, property by property, the winner first and the ones it overrides after it - the Styles pane of a browser's developer tools (StyleSheet.ExplainTile). Empty when the control has no tile.

Flow

public Board Flow(Control control, int rowSpan = 1, int colSpan = 1, TileAlign hAlign = default, TileAlign vAlign = default, Insets margin = default, string? classes = null, ArionStyle? style = null);

Adds control as a tile the board places itself: in reading order, into the first free cells after the tile before it - CSS auto-placement. With repeating columns (Track.AutoFit) such tiles wrap onto more rows as the board gets narrower. The parameters are those of Board.Add without the cell. Returns the board, so tiles chain.

Parameters

control

What the tile shows.

rowSpan

Rows covered, at least 1.

colSpan

Columns covered, at least 1 and at most as many as the board has.

hAlign

Where the tile sits across its cell area.

vAlign

Where the tile sits along its cell area.

margin

Space between the cell area and the tile.

classes

The tile's style classes, space-separated ("card kpi").

style

The tile's own style, over every rule; null for none.

HitTest

public override Control? HitTest(LogPoint p);

The topmost tile under the point answers; the board itself is transparent.

ItemsChanged

public void ItemsChanged(int index, int count = 1);

What count items from index show changed: their cards are bound and measured again. UI thread.

ItemsFrom

public Board ItemsFrom<T, TCard>(IReadOnlyList<T> items, Func<TCard> create, Action<TCard, T> bind, string? classes = null, ArionStyle? style = null) where TCard : Control;

Makes this board a feed of items: one card per item, flowing into the board's columns in reading order (one column: one item per row), each row as tall as its tallest card, like Board.Flow with auto rows.

var feed = new Board { Columns = [Track.AutoFit(min: 320)], ColumnGap = 12, RowGap = 12, Padding = 16 }
    .ItemsFrom(posts, () => new PostCard(), (card, post) => card.Show(post), classes: "card");
grid.MainView = new BoardView(feed);

Only the cards near the view exist: create makes one when an item comes near and the pool has none, bind gives it the item, and a card that leaves goes back to the pool for the next item. Only those items are measured; the others count as the mean of the measured ones, and positions come from a Fenwick tree in O(log n). When an item above the view is measured and needs other room, the view moves with it and the picture on screen stays as it was; when the width changes, the measurements go and the feed is estimated anew.

The board does not watch the list: every change is told to it - Board.ItemsInserted, Board.ItemsRemoved, Board.ItemsChanged - on the UI thread, also a change of what an item shows while it is out of view. Several changes inside one Board.Mutate are taken together: whole rows of items arriving at the top or the end then cost no layout and no full frame. For an ObservableCollection the board listens itself (Board.ItemsFrom). The view stays on the item the user reads.

Tab walks the cards that exist, those near the view; a screen reader hears each card with its place in the feed ("… 3 of 10,000"). A feed board holds no other tiles and is the top-level board of a BoardView; make it a feed before it is shown.

Type parameters

T

The item type.

TCard

The control that shows one item.

Parameters

items

The items, in reading order; the board reads it on the UI thread, the application changes it.

create

Makes an empty card.

bind

Shows an item on a card - a new one or one from the pool.

classes

The style classes of every card's tile, space-separated.

style

The inline style of every card's tile; null for none.

ItemsFrom

public Board ItemsFrom<T, TCard>(ObservableCollection<T> items, Func<TCard> create, Action<TCard, T> bind, string? classes = null, ArionStyle? style = null) where TCard : Control;

Board.ItemsFrom over a collection the board watches: an add, a removal, a replacement or a reset becomes Board.ItemsInserted, Board.ItemsRemoved or Board.ItemsChanged, and an item that raises PropertyChanged is bound and measured again. A change made on another thread is taken on the UI thread with the next frame tick; the collection itself must not change while the UI thread reads it.

Type parameters

T

The item type.

TCard

The control that shows one item.

Parameters

items

The items, in reading order.

create

Makes an empty card.

bind

Shows an item on a card.

classes

The style classes of every card's tile, space-separated.

style

The inline style of every card's tile; null for none.

ItemsInserted

public void ItemsInserted(int index, int count);

count items were inserted into the feed's list at index. The view stays on the item the user reads - at the top of the feed it stays at the top and shows the new items. UI thread.

ItemsRemoved

public void ItemsRemoved(int index, int count);

count items were removed from the feed's list at index; a card that held the focus gives it up. UI thread.

LinkScroll

public ScrollAxis LinkScroll(ScrollDirection direction, params Control[] tiles);

Links the scroll of tiles in direction: they share one ScrollAxis, so a scroll in any of them - wheel, keyboard, scroll bar, drag, a glide - shows in all of them in the same frame, at the same position. The first tile brings its position. Returns the axis, which a further tile can join.

Measure

public override LogSize Measure(LogSize available);

What the board needs: padding plus its solved tracks. A width it is given is shared by its star columns; without a height limit star rows take their content.

MoveTile

public bool MoveTile(Control control, int row, int col, int rowSpan = 1, int colSpan = 1);

Puts the tile of control into the given cells; a tile the board placed itself then stays there. False when the control has no tile.

Mutate

public void Mutate(Action change);

Runs change so the render thread cannot read through the middle of it, then repaints what it changed - the way to change what a shown board draws (a value, a text, a visibility). Before the board is shown it just runs.

What changed is found by comparing each tile near the view before and after (its drawing and what shapes its layout). A board of at most Board.ExactLayoutLimit tiles then measures every tile again and lays itself out anew when a tile needs other room. A larger board measures only the tiles near the view that changed; a tile out of view is measured when it scrolls into view, and the board is laid out again then if it needs other room. To have a tile out of view measured at once, change it with Board.Mutate.

UI thread only, like every change of a shown board: from another thread it throws InvalidOperationException. Data arriving on a worker thread is handed to the UI thread first (the host's dispatcher, a scene's UiThread).

Mutate

public void Mutate(Control control, Action change);

Board.Mutate for a change of what control (a tile's control or a control inside a tile) draws: that tile is measured again at once, wherever it lies, and the board is laid out anew when it needs other room.

Parameters

control

The control that changes, on this board or a board inside it.

change

The change.

OnAttached

protected internal override 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 override 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.

Remarks

Shown again elsewhere, the board registers anew: what it stamped here goes.

OnPointerLeft

public override void OnPointerLeft();

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

OnPointerMoved

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

OnPointerPressed

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

OnPointerReleased

public override void OnPointerReleased(LogPoint p);

OverrideColumn

public void OverrideColumn(int index, TrackSize? size);

Replaces the rule of column index by size; null gives it back its declared rule. Ignored while the columns repeat.

OverrideRow

public void OverrideRow(int index, TrackSize? size);

Replaces the rule of row index by size; null gives it back its declared rule.

Remove

public bool Remove(Control control);

Takes the tile of control off the board; false when it has none.

Render

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

Draws every tile, raised ones last - a nested board draws whole; the top-level one is drawn band by band by its view.

ReorderTile

public bool ReorderTile(Control control, int index);

Moves the tile of control to index in Board.Tiles: for a tile the board places itself, its place in reading order among the others that flow; for any tile, the order in which tiles are drawn. False when the control has no tile.

ResetArrangedTracks

public void ResetArrangedTracks();

Gives the board back the columns and rows its code declared, where docking replaced them (a saved layout without arranged tracks, a reset). The tiles keep their cells.

ResizeTracks

public bool ResizeTracks(BoardAxis axis, int splitter, double delta);

Moves the boundary after track splitter (between it and the next one) by delta - what dragging that splitter does, for the keyboard or a script. Keeps Board.MinTrackSize and the tracks' own bounds. False when the board has not been laid out, or the boundary is no splitter.

SetClasses

public bool SetClasses(Control control, string? classes);

Gives the tile of control new style classes (space-separated) - the way to mark a tile selected, active or in error. The tile blends into its new look over the transition of that look. False when the control has no tile.

SetOffset

public void SetOffset(Control control, double x, double y = 0);

Draws the tile of control moved by (x, y) inside its own box and cut at the box: its content slides under the box's edge - a side panel sliding away, a card sliding in. Nothing is measured or laid out; only the box is repainted, and a view tile inside draws its kept picture again without preparing a frame. Step it from a timer or a frame tick for a slide; the tile leaves the layout (or enters it) once, before or after.

The tile keeps its place: the pointer and the focus ring stay at the box, so an offset is meant for a moment, not as a place. (0, 0) puts the tile back. A control that is no tile of this board is ignored. UI thread.

Parameters

control

A tile's control.

x

Rightward shift, in logical units.

y

Downward shift, in logical units.

SetStyle

public bool SetStyle(Control control, ArionStyle? style);

Gives the tile of control a new inline style (null for none) - CSS's style attribute, over every rule. The tile blends into its new look over the transition of that look. False when the control has no tile.

SwapTiles

public bool SwapTiles(Control first, Control second);

Swaps the places of two tiles: two tiles in given cells swap their cells, two tiles the board places itself swap their places in reading order. False when either control has no tile, or one flows and the other does not.

TakeTileCounts

public (long, long) TakeTileCounts();

Diagnostics: the tiles of this board drawn since the last call - onto a surface (the screen, a page drawn ahead, either path), and into a fingerprint, the board's comparison of before and after a change, which draws them without pixels. What the board's scaling costs, counted rather than guessed (the scene "Board under load" shows it). Any thread.

Remarks

Public because an application reads it: the zone guard keeps the internals of the open zone from every application, the demos included.

Tick

public override void Tick(double dtMs);

Moves the blending tiles on by dtMs and repaints them.

TryConvertToSplit

public bool TryConvertToSplit();

Gives the board a split tree (Board.Split) that places its tiles where their cells are: the board is cut along the track boundaries no tile crosses, rows before columns, and each part again, each part's share as wide or high as its tracks were last laid out. True when the board has a tree afterwards; false, changing nothing, where the cells cannot be cut apart like that (spans that turn like a pinwheel, empty cells), a tile flows, or the board cannot have a tree.

When

public Board When(double minWidth, Action<BoardBreakpoint> configure);

Adds a breakpoint - CSS's @media (min-width: …), measured on this board's own width (for the top-level board, the window's; for a nested one, its tile's, like a container query). While the board is at least minWidth wide, what configure sets applies: other tracks, gaps or padding, tiles placed elsewhere or hidden, a style sheet of its own. Breakpoints apply in the order they were added, a later one over an earlier (mobile first: start narrow, add wider).

board.When(minWidth: 900, wide =>
{
    wide.Columns = [Track.Px(240), Track.Star()];
    wide.Place(sidebar, row: 0, col: 0, rowSpan: 2);
    wide.StyleSheet = new StyleSheet { { Select.Class("card"), new ArionStyle { Padding = 24 } } };
});

The width is compared at every layout; the breakpoints are applied again only when it crosses a threshold. Returns the board, so calls chain.

When

public Board When(double minWidth, double maxWidth, Action<BoardBreakpoint> configure);

A breakpoint for widths from minWidth up to, not including, maxWidth - see Board.When.

Events

ArrangementChanged

public event Action? ArrangementChanged;

Raised after the arrangement changed: a splitter or a tile was let go, a step of Board.History was undone or redone, or the API changed track sizes or tile places - the moment to save the layout.