avalonia-visual-element

Rules and patterns for creating Avalonia UI visual elements (controls, dialogs, panels, windows). Use when creating or modifying XAML controls, dialogs, panels, or windows in this project.

SKILL.md

GitHub

Avalonia Visual Element Creation Rules

Follow these rules strictly when creating or modifying any visual element (control, dialog, panel, window) in this project.

Core Philosophy

  • Direct UI Access — no MVVM, no reactive patterns, no stored state between UI and model
  • Action-driven — everything happens by explicit user interaction
  • KISS — minimal working version first, no premature abstractions
  • TDD — write tests first, implement second

XAML Rules

  • Theme: Classic.Avalonia.Theme
  • Font size: Always {DynamicResource AppFontSize} — NEVER hardcode font sizes
  • Named elements: Use x:FieldModifier="internal" for code-behind access
  • Keep XAML simple — layout and structure only, no complex data bindings
  • ComboBox items: Use DataTemplate with ItemTemplate for displaying model objects

Dialog / Window Layout

Use this structure for all dialogs:

<Window ...
        Title="Edit [Element]"
        Width="450" Height="380"
        MinWidth="400" MinHeight="320"
        FontSize="{DynamicResource AppFontSize}"
        WindowStartupLocation="CenterOwner"
        CanResize="true">

    <ScrollViewer VerticalScrollBarVisibility="Auto" HorizontalScrollBarVisibility="Disabled">
        <StackPanel Margin="20" Spacing="10">

            <!-- Section header -->
            <TextBlock Text="Section Title" FontWeight="SemiBold"
                       FontSize="{DynamicResource AppFontSize}"/>

            <!-- Input grid: 100px label, * control -->
            <Grid ColumnDefinitions="100,*" RowDefinitions="Auto,Auto">
                <TextBlock Grid.Row="0" Grid.Column="0" Text="Label:"
                           VerticalAlignment="Center"
                           FontSize="{DynamicResource AppFontSize}"/>
                <controls:MeasurementControl Grid.Row="0" Grid.Column="1"
                           x:Name="Control1" x:FieldModifier="internal"
                           FontSize="{DynamicResource AppFontSize}"/>

                <!-- Subsequent rows get top margin -->
                <TextBlock Grid.Row="1" Grid.Column="0" Text="Label:"
                           VerticalAlignment="Center"
                           FontSize="{DynamicResource AppFontSize}"
                           Margin="0,8,0,0"/>
                <controls:MeasurementControl Grid.Row="1" Grid.Column="1"
                           x:Name="Control2" x:FieldModifier="internal"
                           FontSize="{DynamicResource AppFontSize}"
                           Margin="0,8,0,0"/>
            </Grid>

            <!-- Checkboxes align under controls, not labels -->
            <Grid ColumnDefinitions="100,*">
                <CheckBox Grid.Column="1" x:Name="SomeCheckBox"
                          x:FieldModifier="internal" Content="Option"
                          FontSize="{DynamicResource AppFontSize}"/>
            </Grid>

            <!-- Buttons: centered, horizontal, 10px spacing, 80px wide -->
            <StackPanel Orientation="Horizontal" HorizontalAlignment="Center"
                        Spacing="10" Margin="0,20,0,0">
                <Button Content="OK" Click="OnOK" Width="80"
                        FontSize="{DynamicResource AppFontSize}"/>
                <Button Content="Cancel" Click="OnCancel" Width="80"
                        FontSize="{DynamicResource AppFontSize}"/>
            </StackPanel>
        </StackPanel>
    </ScrollViewer>
</Window>

Dialog Layout Rules Summary

Rule Value
Label column width 100px
Control column * (fill remaining)
Row spacing Margin="0,8,0,0" on subsequent rows
Content margin Margin="20" on outer StackPanel
Content spacing Spacing="10" on outer StackPanel
Section headers FontWeight="SemiBold"
Button width 80px
Button spacing 10px
Button top margin Margin="0,20,0,0"
Checkbox alignment Under controls (Grid.Column="1"), not labels
Window startup CenterOwner
Resizable CanResize="true" with Min dimensions

Dialog Code-Behind Pattern

public partial class EditSomethingDialog : Window
{
    private readonly SomeElement _element;

    public EditSomethingDialog(SomeElement element)
    {
        _element = element ?? throw new ArgumentNullException(nameof(element));
        InitializeComponent();

        // Initialize controls
        Control1.UnitType = typeof(SomeUnit);
        PopulateFromElement();

        // Window state persistence
        Utilities.WindowStateManager.RestoreDialogSize(this, nameof(EditSomethingDialog));
        Closing += (s, e) => Utilities.WindowStateManager.SaveDialogSize(this, nameof(EditSomethingDialog));
    }

    private void PopulateFromElement()
    {
        Control1.SetValue(_element.SomeProperty);
    }

    public void Save()
    {
        var value = Control1.GetValue<SomeUnit>();
        if (value.HasValue) _element.SomeProperty = value.Value;
    }

    private void OnOK(object? sender, RoutedEventArgs e) { Save(); Close(); }
    private void OnCancel(object? sender, RoutedEventArgs e) { Close(); }
}

Control Design Rules

Architecture

  • Controller pattern: Pure C# logic in Controllers/, thin UI wrapper in Controls/
  • Controller has NO Avalonia dependencies — easy to unit test
  • Control calls controller methods (via reflection for generic types)

Behavior

  • No validation in controls — validate at application level
  • Min/Max for UI only — controls increment/decrement step, NOT input rejection
  • Precision transparency — store original values; if user hasn't changed the display, return the original precise value
  • Events over properties — raise Changed event, let the application decide what to do

Value Access Pattern (direct UI access)

// GET: always read from UI controls directly (no stored state)
public object? Value
{
    get => _controller.Value(NumericPart?.Text ?? "", unit, DecimalPoints, Culture);
    set
    {
        NumericPart.Text = text;
        SelectUnit(unit);
    }
}

// Events just notify — never update properties in handlers
NumericPart.TextChanged += (s, e) => Changed?.Invoke(this, EventArgs.Empty);

What NOT to Do

  • Do NOT use StyledProperty with TwoWay binding (causes circular notification loops)
  • Do NOT update property values inside event handlers
  • Do NOT use generic type parameters on UserControl (XAML doesn't support it) — use Type property + reflection instead
  • Do NOT add recursion guards — if you need them, the design is wrong

Controller Creation

Controllers are always created as part of a control — never standalone. They live in Controllers/ and contain ALL complex logic so the control code-behind stays thin.

Controller rules

  1. Zero Avalonia dependencies — no using Avalonia.* anywhere
  2. Must be independently testable — constructor takes no UI parameters
  3. Add [assembly: InternalsVisibleTo("ProjectName.Tests")] at top of file
  4. Namespace: ProjectName.Controllers
  5. Configuration via properties with sensible defaults, not constructor parameters

Standard controller API surface

Every input controller follows this method pattern (adapt names to your domain):

public class SomethingController  // or SomethingController<T> where T : Enum
{
    // Configuration properties with defaults
    public double Increment { get; set; } = 1.0;
    public double Minimum { get; set; } = -10000.0;
    public double Maximum { get; set; } = 10000.0;
    public int? DecimalPoints { get; set; } = null;

    // 1. Enumerate options (for ComboBox population)
    public IReadOnlyList<OptionType> GetOptions(out int defaultIndex) { }

    // 2. Parse text → typed value (returns null on invalid/empty input)
    public ValueType? Value(string text, ..., int? accuracy, CultureInfo? culture = null) { }

    // 3. Format typed value → text + selection state (out parameters)
    public void ParseValue(ValueType value, out string text, out OptionType option,
                           int? decimalPoints = null, CultureInfo? culture = null) { }

    // 4. Increment/decrement (clamps to Min/Max, rounds to DecimalPoints)
    public string IncrementValue(string currentText, bool increment,
                                 CultureInfo? culture = null) { }

    // 5. Character filter for real-time input validation
    public bool AllowKeyInEditor(string currentText, int caretIndex,
                                 int selectionLength, char character,
                                 CultureInfo? culture = null) { }
}

Not every controller needs all five methods. Omit what the control doesn't need:

  • Simple display controls may only need Value() and ParseValue()
  • Geometry controllers (e.g., WindDirectionController) have domain-specific methods instead

Culture handling

// Always accept optional culture, default to InvariantCulture
public ValueType? Value(string text, ..., CultureInfo? culture = null)
{
    culture ??= CultureInfo.InvariantCulture;
    // ...
}

Min/Max semantics in controllers

// IncrementValue clamps to Min/Max
newValue = Math.Max(Minimum, Math.Min(Maximum, newValue));

// Value() does NOT reject out-of-range input
// Comment this explicitly:
// Note: Min/Max are only used for increment/decrement, not validation

Generic controller + reflection bridge

When a controller is generic but XAML can't use generics:

Controller — generic, clean:

public class MeasurementController<T> where T : Enum
{
    public Measurement<T>? Value(string text, T unit, int? accuracy, CultureInfo? culture = null) { }
}

Control — non-generic, uses Type property + reflection:

public partial class MeasurementControl : UserControl
{
    private object? _controller;  // MeasurementController<T> via reflection
    private Type? _unitType;

    private void InitializeController()
    {
        var controllerType = typeof(MeasurementController<>).MakeGenericType(_unitType);
        _controller = Activator.CreateInstance(controllerType);
        SyncPropertiesToController();
    }

    // Call controller methods via reflection
    public object? Value
    {
        get
        {
            var valueMethod = _controller.GetType().GetMethod("Value");
            return valueMethod?.Invoke(_controller, new object?[] { text, unit, DecimalPoints, Culture });
        }
    }
}

Syncing StyledProperty changes to controller

this.PropertyChanged += (s, e) =>
{
    if (e.Property == IncrementProperty)
        _controller?.GetType().GetProperty("Increment")?.SetValue(_controller, (double)e.NewValue!);
    else if (e.Property == MinimumProperty)
        _controller?.GetType().GetProperty("Minimum")?.SetValue(_controller, (double)e.NewValue!);
    // ... etc
};

Event wiring pattern

private void WireEvents()
{
    this.GotFocus += (s, e) => NumericPart?.Focus();

    if (NumericPart != null)
    {
        NumericPart.KeyDown += NumericPart_KeyDown;
        NumericPart.AddHandler(TextInputEvent, NumericPart_TextInput, RoutingStrategies.Tunnel);
        NumericPart.TextChanged += (s, e) => Changed?.Invoke(this, EventArgs.Empty);
    }

    if (UnitPart != null)
    {
        UnitPart.SelectionChanged += (s, e) => Changed?.Invoke(this, EventArgs.Empty);
    }
}

Keyboard handling pattern

private void NumericPart_KeyDown(object? sender, KeyEventArgs e)
{
    if (e.Key == Key.Up)   { DoIncrement(true);  e.Handled = true; }
    if (e.Key == Key.Down) { DoIncrement(false); e.Handled = true; }
    if (e.Key == Key.Tab)  { UnitPart.Focus();   e.Handled = true; }
}

private void NumericPart_TextInput(object? sender, TextInputEventArgs e)
{
    // Delegate to controller.AllowKeyInEditor() — reject invalid chars
    var allowed = (bool)(allowKeyMethod?.Invoke(_controller, new object?[] {
        NumericPart.Text, NumericPart.CaretIndex,
        NumericPart.SelectionEnd - NumericPart.SelectionStart, c, Culture
    }) ?? false);

    if (!allowed) e.Handled = true;
}

Panel Design

Panels are desktop-only (not shared with mobile). They follow the same layout rules as dialogs but are embedded in the main window rather than standalone windows.

Panel Properties Pattern

public MeasurementSystem MeasurementSystem { get; set; }  // Switch units
public SomeDataType Data { get; set; }                     // Get/Set all values
public event EventHandler Changed;                          // Notify parent

File Organization

Controls/           → XAML + code-behind (thin UI layer)
Controllers/        → Pure C# logic (no UI dependencies)
Models/             → Data models (UnitItem, DragTableInfo, etc.)

Testing

  • TDD: Write tests FIRST using xUnit + Avalonia.Headless + AwesomeAssertions
  • Test controllers directly (pure logic, no UI needed)
  • Test controls with [AvaloniaFact] attribute
  • Use DebugApp for visual/exploratory testing after tests pass
  • Test with realistic ballistics domain values

App.axaml Pattern

<Application.Resources>
    <x:Double x:Key="AppFontSize">13</x:Double>
</Application.Resources>

<Application.Styles>
    <StyleInclude Source="avares://Classic.Avalonia.Theme/ClassicTheme.axaml"/>
    <Style Selector=":is(TemplatedControl)">
        <Setter Property="FontSize" Value="{DynamicResource AppFontSize}" />
    </Style>
</Application.Styles>