Avalonia UI

The AvaloniaNameGeneratorBehavior setting changes how the generator interacts with your code-behind class:

1. InitializeComponent (Default): The generator creates an InitializeComponent method that performs the actual FindNameScope().Find<T>(...) calls to assign the controls to fields.

   • Warning: If you use this mode, do not manually define a method named InitializeComponent in your partial class, as it will hide the generated one. If you must have your own InitializeComponent, switch the behavior to OnlyProperties.

2. OnlyProperties: The generator creates get-only properties that call FindNameScope().Find<T>(...) every time they are accessed. This mode is useful if you prefer to manage the lifecycle/loading of your XAML manually.

Avalonia enforces a strict Messaging Only policy for cross-thread communication between the UI thread and the Wayland thread.

Rules for developers:

• No Cross-Thread Variable Access: UI thread objects must NEVER directly access fields of Wayland-thread objects. Conversely, Wayland thread objects must NEVER directly read fields of UI-thread objects (do not use volatile fields, locks, or shared state).
• Communication via Proxies: All communication from the UI thread to the Wayland thread must go through code-generated proxies. These proxies route calls via WaylandWorker.PostOob() or PostWithCommit() messages.
• Server Object Safety: Objects located in the Server/ directory should not have their internal state modified by the UI thread. The UI thread is only permitted to call Post or pass values into server object constructors.

To prevent memory leaks, all COM interface references returned from a call are assumed to have an incremented reference counter. The caller is responsible for calling Release on these references.

To avoid the ambiguity of the IFoo* GetFoo() pattern, all methods defined in avn.idl must use the HRESULT with an out-parameter pattern.

// WRONG — easy to leak or forget Release:
IFoo* GetFoo();

// CORRECT — use HRESULT + out-parameter:
HRESULT GetFoo(IFoo** ppv);

The wl_pointer protocol uses frame-based event delivery. To ensure correct input routing, follow these requirements:

• Dispatch Order: All events within a frame (enter, leave, motion, button, axis) must be dispatched in their exact arrival order. For example, if a frame contains a leave from Surface A followed by an enter on Surface B, they must be processed in that order to avoid routing errors.
• Axis Event Combination: Multiple wl_pointer.axis events within a single frame should be combined (e.g., horizontal and vertical scroll into a single vector), but the resulting event must be dispatched at the correct position in the original sequence.
• State Ownership: Frame state (focused sink, position, modifiers, and accumulated events) belongs to the wl_pointer instance, not the wl_seat. Each wl_pointer manages its own independent frame grouping.

Avalonia.Native uses COM (Component Object Model) for cross-boundary object lifetime management. COM types are typically prefixed with IAvn (interfaces) or Avn (implementations). All COM objects derive from IUnknown and use reference counting via AddRef and Release.

Critical Safety Rule: Never store raw COM pointers in class fields, instance variables, closures, or containers. Raw COM pointers are only permitted as function parameters or local variables within the scope of a single function call.

This documentation is intended for developers contributing to the Avalonia framework itself.

• To build Avalonia from source, follow the Building Avalonia guide.
• Before starting development, review the Contributing guidelines.

Note: If you are looking for documentation on how to use the Avalonia framework to build your own applications, please visit the official user documentation at https://docs.avaloniaui.net/.

Avalonia supports Visual Studio, Visual Studio Code, and Rider. You must use a version that supports at least .NET 10 (e.g., Visual Studio 2026 or Rider 2025.3).

When opening the project, choose one of two solution files:

1. Avalonia.slnx: Contains the full project (desktop, mobile, and web). Requires all relevant .NET workloads to be installed.
2. Avalonia.Desktop.slnf: A solution filter that opens only the desktop-related parts of Avalonia. This does not require extra workloads.

Build and run the ControlCatalog.Desktop project to see the sample application in action.

To verify your build, navigate to the desktop control catalog sample and run it:

cd samples\ControlCatalog.Desktop
dotnet restore
dotnet run