avalonia-property-system

Avalonia Property System

Overview

AvaloniaProperty is the foundation of Avalonia's data binding, styling, and animations. Three kinds:

• StyledProperty — full-featured; supports styling, animation, inheritance
• DirectProperty — lightweight, CLR-field-backed; no styling/animation support
• AttachedProperty — set on foreign controls (like Grid.Row)

StyledProperty

public static readonly StyledProperty<IBrush?> BackgroundProperty =
    AvaloniaProperty.Register<MyControl, IBrush?>(
        name: nameof(Background),
        defaultValue: null,
        inherits: false,
        defaultBindingMode: BindingMode.OneWay,
        validate: null,
        coerce: CoerceBackground);

public IBrush? Background
{
    get => GetValue(BackgroundProperty);
    set => SetValue(BackgroundProperty, value);
}

private static IBrush? CoerceBackground(AvaloniaObject instance, IBrush? value)
    => value ?? Brushes.Transparent;

Inherit/reuse from another class:

// Re-register an existing property as owner
public static readonly StyledProperty<IBrush?> BackgroundProperty =
    Border.BackgroundProperty.AddOwner<MyPanel>();

DirectProperty

Use for properties that back observable collections, streams, or are performance-sensitive:

public static readonly DirectProperty<MyControl, string> TextProperty =
    AvaloniaProperty.RegisterDirect<MyControl, string>(
        name: nameof(Text),
        getter: o => o.Text,
        setter: (o, v) => o.Text = v,
        defaultBindingMode: BindingMode.TwoWay,
        enableDataValidation: true);

private string _text = "";
public string Text
{
    get => _text;
    set => SetAndRaise(TextProperty, ref _text, value);
}

SetAndRaise performs equality check, updates field, raises PropertyChanged.

AttachedProperty

public static class Grid
{
    public static readonly AttachedProperty<int> RowProperty =
        AvaloniaProperty.RegisterAttached<Grid, Control, int>(
            name: "Row",
            defaultValue: 0,
            inherits: false);

    public static int GetRow(Control element) => element.GetValue(RowProperty);
    public static void SetRow(Control element, int value) => element.SetValue(RowProperty, value);
}