drawnui/drawnui.net/drawnui-fluent

DrawnUI Fluent Extensions — C# Code-Behind

Containers — use semantic aliases

Compose with alias containers, not raw SkiaLayout { Type = LayoutType.X }: SkiaStack (vertical, Fill), SkiaRow (horizontal), SkiaLayer (absolute overlay, Fill), SkiaWrap (Fill), SkiaMasonry (Fill, 2 columns), SkiaGrid (Fill). Aliases preset Type AND HorizontalOptions=Fill (except SkiaRow) — raw SkiaLayout defaults to Type=Absolute with NO fill, so it aligns differently. SkiaFrame = SkiaShape rectangle, not a layout.

Constructor shorthand is the documented idiom for text controls: new SkiaLabel("text"), new SkiaRichLabel("**md**"), new SkiaButton("Caption").

Row does NOT distribute Fill children (device-verified 2026-08-15): two HorizontalOptions=Fill children inside a SkiaRow each take full width and overflow the screen — a Row is not a star-grid. For proportional button rows use SkiaGrid + .WithColumnDefinitions("2*,3*") + .SetGrid(col, 0) per child. Same for HorizontalFillRatio inside a Row — not a substitute for grid columns. A child that is not Fill does get what is left, as in a SkiaStack vertically: a wrapping label after a title wraps in the remaining width, and an End child sits at the row's end. Pick containers in the order SkiaLayer (alignment + Margin), SkiaStack, SkiaRow, SkiaWrap, and SkiaGrid last (drawnui skill, "Choosing a container").

Composition Style — MANDATORY

Never declare a local variable for a control and then reference it in a children list. Always construct inline inside the collection initializer. Use .Assign(out _field) when a field reference is needed — it returns the control so chaining continues.

Do not spam `AddSubView(...)` while building a known static scene or container subtree. When the children are known at composition time, declare them together inside Children = new List<SkiaControl> { ... }. Reserve AddSubView() for dynamic/runtime operations such as pooled controls, generated rows, incremental updates, or add/remove flows that happen after the initial tree is built.

Critical: Static vs Runtime Children Mutation

Before layout is ready (static composition in constructor):

// ✅ CORRECT — initial tree building
Children = new List<SkiaControl>
{
    new SkiaLabel { Text = "A" },
    new SkiaLabel { Text = "B" },
};

After layout is ready (runtime mutation, e.g. in RefreshFriendsList):

// ✅ CORRECT — runtime mutation
layout.ClearChildren();
layout.AddSubView(new SkiaLabel { Text = "New" });
layout.RemoveSubView(existingChild);
 
// ✅ also works on the control's own (default) Children collection: it is observed,
// Add / Insert / Remove / Move / Replace / Clear change what is drawn
layout.Children.Add(child);
layout.Children.RemoveAt(0);
 
// ❌ WRONG — after `Children = new List<SkiaControl> { ... }` the collection is that plain list,
// which nobody observes: later Add / Clear on it are invisible to the engine
layout.Children.Add(child);     // ignored when Children was assigned a List

Build the full list first and assign once (verified 2026-09-16: popup wrappers built as Children = new List<SkiaControl>() followed by Children.Add(x) never rendered and their ScaleToAsync never completed). The collection-initializer form Children = { a, b } (no new List) adds to the control's own observed collection.

Rule of thumb: Use Children = new List<...> only during initial construction. Once LayoutIsReady has fired or the control is in the visual tree, use ClearChildren(), AddSubView(), RemoveSubView(): they work whatever collection Children holds.

WRONG — never do this:

var label = new SkiaLabel { Text = "hi" };
Children = new List<SkiaControl> { label };

RIGHT — always inline:

Children = new List<SkiaControl>
{
    new SkiaLabel { Text = "hi" }.Assign(out _label),
};

Nested layout:

Children = new List<SkiaControl>()
{
    new SkiaStack()
    {
        Spacing = 8,
        Children = new List<SkiaControl>()
        {
            new SkiaLabel() { Text = "hi" }.Assign(out _label),
        }
    },
};

Children = { ... } (bare collection initializer) and .WithChildren(a, b, c) are equivalent inline forms — fine too. .WithContent(child) sets the single child of IWithContent containers (e.g. SkiaScroll, ContentLayout). .AssignParent(parent) adds the control to a parent mid-chain.

WRONG for static composition:

AddSubView(new SkiaLabel { Text = "A" });
AddSubView(new SkiaLabel { Text = "B" });
AddSubView(new SkiaLabel { Text = "C" });

RIGHT for static composition:

Children = new List<SkiaControl>
{
    new SkiaLabel { Text = "A" },
    new SkiaLabel { Text = "B" },
    new SkiaLabel { Text = "C" },
};

Chain after .Assign() — it returns the control:

new SkiaLabel() { ... }
    .ObserveProperty(source, nameof(Score), me => { me.Text = $"{source.Score}"; })
    .Assign(out LabelScore)
    .OnTapped(me => { ... })

Omit redundant default assignments like Left = 0, Top = 0. Keep explicit zeros only in reset/pooling paths where prior state may still be present.

Layout shortcuts: .Center() / .CenterX() / .CenterY() (control inside parent), .Fill() / .FillX() / .FillY(), .StartX() / .StartY() / .EndX() / .EndY(). Text alignment inside a SkiaLabel (NOT the label's own position): .CenterText() / .CenterTextX() / .CenterTextY() — set HorizontalTextAlignment / VerticalTextAlignment to Center.

Property shortcuts (all chainable): .WithHeight(n) / .WithWidth(n), .WithMargin(all) / (h,v) / (l,t,r,b) / (Thickness), .WithPadding(...), .WithCache(SkiaCacheType.X), .WithBackgroundColor(c), .WithHorizontalOptions(...) / .WithVerticalOptions(...), .WithVisibility(bool), .WithTag("name"); shape: .Shape(ShapeType.Circle); image: .WithAspect(TransformAspect.X); label: .WithFontSize(n), .WithTextColor(c), .WithHorizontalTextAlignment(...).

Grid placement helpers

Definitions are set on the grid itself (string form, chainable), placement on each child:

new SkiaGrid()
{
    DefaultRowDefinition = new RowDefinition(GridLength.Star),   // avoids repeating N identical rows
    Children = new List<SkiaControl>()
    {
        new SkiaSvg() { ... }.SetGrid(0, 0, 1, 2),   // COLUMN first, then row, then colspan, rowspan
        new SkiaLabel() { ... }.SetGrid(1, 0),
        new SkiaLabel() { ... }.WithColumn(2).WithRow(0).WithRowSpan(2),
    }
}
.WithColumnDefinitions("32,*,40")
.WithRowDefinitions("Auto,Auto")

SetGrid(column, row) / SetGrid(column, row, columnSpan, rowSpan) — column comes first, opposite of the usual "row, column" convention (the XML doc comment on the 4-arg overload in FluentExtensions.Maui.cs / FluentExtensions.NonMaui.cs lists them backwards — trust the signature). WithColumnDefinitions / WithRowDefinitions return SkiaLayout, so put them last in the chain (after .Assign(...)). Individual: .WithRow(n), .WithColumn(n), .WithRowSpan(n), .WithColumnSpan(n). Also DefaultColumnDefinition.

.Initialize vs .Adapt

.Adapt(me => ...) runs setup on the control itself mid-chain. Do NOT access OTHER .Assign'd references from Adapt — they may not exist yet. Post-build wiring that touches assigned refs goes in .Initialize(me => ...) on the OUTERMOST control — it runs after the whole chain is constructed.

.Initialize fires once, when the control gets its parent (added to Children/Content or to the canvas), independent of IsVisible, measuring or virtualization (since 1.10.6.16; before it fired at first measure, so an IsVisible=false control never ran it). Never attached → runs at first measure. Superview may still be null inside; tree-ready work goes in LayoutIsReady / Initialized. Trap: a child gets its parent INSIDE the parent's object initializer, before the parent's own .Assign(out ...) runs, so an .Initialize on a child that reads a sibling/parent field sees null. The lazy-target observers (ObserveProperty(() => x, ...), ObserveProperties(() => x, ...), Observe(() => x, ...)) therefore resolve their target at the control's FIRST MEASURE, not on attach (attach-time resolution left every SkiaSlider style thumb unsized, 2026-09-23).

Event / Gesture Wiring — MANDATORY

Always use fluent extension methods — never += events or commands wired outside the initializer.

Keyboard: .OnKeyDown / .OnKeyUp both take (control, InputKey key) — InputKey.ArrowLeft/ArrowRight/ArrowUp/ArrowDown, Space, Enter, KeyD… Attach them to the ROOT control of the tree, not to the focused child. Verified on the Fiddle WASM build 2026-08-30.

OnKeyDown repeats at the OS key-repeat rate — with a delay before the first repeat and gaps between them — so driving a value directly from it produces stepped, laggy movement. For anything held (a game paddle, a camera pan), keep a direction flag instead and move per frame:

var keyDir = 0;
 
// in the per-frame animator: FPS-independent, no repeat delay
if (keyDir != 0) targetX = Math.Clamp(targetX + keyDir * speed * dt, min, max);
 
root.OnKeyDown((me, key) =>
     {
         if (key == InputKey.ArrowLeft) keyDir = -1;
         else if (key == InputKey.ArrowRight) keyDir = 1;
     })
    .OnKeyUp((me, key) =>
     {
         if (key == InputKey.ArrowLeft && keyDir < 0) keyDir = 0;
         else if (key == InputKey.ArrowRight && keyDir > 0) keyDir = 0;
     });

On Blazor the key event is not preventDefaulted, so Space also scrolls the hosting page while the canvas has focus.

`.WhenPaint` draws BEFORE the control paints its own background (verified 2026-08-30, DrawnUI Fiddle WASM). A control that has BackgroundColor set will cover everything the hook drew — silently, no error, blank result. Put the background on a parent (e.g. a SkiaShape frame) and attach .WhenPaint to a transparent child filling it: