DOCSEARCHbyAlgolia
Submit Docs

Avalonia UI Documentation

repository·main·Indexed 40 days ago

https://github.com/avaloniaui/avalonia-docs

Official documentation for Avalonia UI, including API references for version 12.0.0-rc1 and 12.0.0-beta1. Covers core framework components such as AppBuilder for application initialization, TreeDataGrid selection models, and internal framework exceptions.

Tokens
148.2K
Snippets
605
Records
842
Agent score
50%

What's inside Avalonia UI

  1. Overview of Avalonia Packages

    main

    Avalonia is a cross-platform UI framework for .NET. The ecosystem is divided into several specialized packages to support different platforms, rendering engines, and UI controls.

    Core and Platform Packages

    • Avalonia: The main cross-platform UI framework.
    • Avalonia.Desktop: Support for desktop environments.
    • Avalonia.Android: Support for Android.
    • Avalonia.Browser: Support for WebAssembly/Browser.
    • Avalonia.LinuxFramebuffer: Support for Linux framebuffer.
    • Avalonia.Skia: Rendering via the Skia graphics library.
    • Avalonia.X11 / Avalonia.FreeDesktop: Linux-specific windowing and desktop integration.

    Specialized Controls and Features

    • Avalonia.Controls.TreeDataGrid: A control for displaying hierarchical and tabular data in a single view (combines TreeView and DataGrid).
    • Avalonia.Controls.Markdown: For rendering Markdown content.
    • Avalonia.Controls.MediaPlayer: Enables native video and audio playback across Windows, macOS, and Linux.
    • Avalonia.Controls.WebView: For embedding web content (dashboards, documentation, etc.).
    • Avalonia.Controls.ColorPicker: A control for selecting colors.

    Testing and Diagnostics

    • Avalonia.Headless.NUnit / Avalonia.Headless.XUnit: Headless testing support for NUnit and xUnit.
    • Avalonia.Headless.Vnc: Headless testing via VNC.
    • AvaloniaUI.DiagnosticsSupport: Provides a connection bridge between the user application and the AvaloniaUI Developer Tools process.

  2. Explore Avalonia.Media types

    main

    The Avalonia.Media namespace contains the core types for 2D graphics, painting, and media playback in Avalonia. Key categories include:

    • Brushes: Used to paint areas (e.g., SolidColorBrush, LinearGradientBrush, ImageBrush, VisualBrush).
    • Geometry: Defines shapes (e.g., EllipseGeometry, RectangleGeometry, PathGeometry, StreamGeometry).
    • Transforms: Manipulate visuals (e.g., RotateTransform, ScaleTransform, TranslateTransform, MatrixTransform).
    • Text Rendering: Controls how text is displayed (e.g., FontFamily, FormattedText, TextAlignment, TextTrimming).
    • Media: Handles playback (e.g., MediaPlayer, MediaSource).
    • Effects: Visual enhancements (e.g., BlurEffect, DropShadowEffect).

  3. Explore the Avalonia.Rendering namespace

    main

    The Avalonia.Rendering namespace contains the core types and interfaces responsible for the application's rendering lifecycle, hit-testing, and the render loop. Key components include:

    • Render Loops & Timers: Interfaces like IRenderLoop and IRenderTimer manage how and when frames are rendered. Implementations include UiThreadRenderTimer (ticks on the UI thread), DefaultRenderTimer (uses a standard timer), and SleepLoopRenderTimer.
    • Host & Visual Tree: IPresentationSource represents the host of the visual tree (typically a native window on desktop).
    • Hit-Testing: ICustomHitTest allows for custom logic when determining which elements are interacted with.
    • Diagnostics & Debugging: RendererDiagnostics and RendererDebugOverlays provide tools for managing and displaying renderer-specific diagnostic information and overlays.

  4. Understand the Cloudflare Worker for Redirects

    main

    The docs-redirects Cloudflare Worker manages server-side redirects and path normalization for docs.avaloniaui.net. It performs four primary functions:

    1. KV redirects: Performs a lookup in the DOCS_REDIRECTS KV namespace. If a match is found, it returns a 301 redirect to the target URL.
    2. Trailing-slash rewrite: To avoid unnecessary 302 redirects from S3-compatible storage, the Worker internally rewrites requests for paths without file extensions to include a trailing slash (e.g., /docs/welcome becomes /docs/welcome/).
    3. Edge caching: HTML pages are cached at the Cloudflare edge for 7 days (cacheTtl: 604800, cacheEverything: true), while browsers are instructed to cache them for 5 minutes (Cache-Control: public, max-age=300).
    4. Static asset bypass: Requests for static assets (e.g., .js, .css, .png) or paths under /assets/* bypass KV lookups and edge caching to pass directly to the origin.

  5. Use the Design class for design-time support

    main

    The Design class in the Avalonia.Controls namespace provides attached properties and helper methods specifically designed to enable design-time support in Avalonia applications. This allows developers to configure how controls appear or behave when being viewed in a designer or previewer, without affecting the runtime behavior of the application.

    using Avalonia.Controls;

// The Design class provides design-time helpers
// via attached properties and methods.
public class Design
{
    // Access via the Avalonia.Controls namespace
}

  6. Understand the Avalonia.Rendering namespace

    main
    The Avalonia.Rendering namespace contains the core abstractions and types responsible for the application's rendering lifecycle, hit-testing, and the render loop. It provides interfaces for managing how the visual tree is presented and how the application handles frame updates (render timers) and diagnostic overlays.

  7. What is AvaloniaList<T> and how does it differ from ObservableCollection<T>?

    main

    AvaloniaList<T> is a notifying list in the Avalonia.Collections namespace, similar to System.Collections.ObjectModel.ObservableCollection<T>. It is designed to work with Avalonia's notification system and includes two key advantages:

    1. Configurable Reset Behavior: You can configure the CollectionChanged event to notify using a Remove action instead of a Reset action when the list is cleared. This is achieved by setting the ResetBehavior property to Avalonia.Collections.ResetBehavior.Remove.
    2. Item Validation: You can use the Validate function to validate each item before it is inserted into the list.

    It implements several interfaces including INotifyCollectionChanged, IList<T>, and IReadOnlyList<T>.

    using Avalonia.Collections;

// Example of configuring reset behavior
var list = new AvaloniaList<string>();
list.ResetBehavior = ResetBehavior.Remove;

  8. Display collections with ItemsControl and ListBox

    main

    To display a collection of items, use the following controls:

    • ItemsControl: The base control for displaying a collection of items.
    • ListBox: A specialized ItemsControl where individual items can be selected.
    • ListBoxItem: The selectable container for an item within a ListBox.
    • ItemCollection: Holds the actual list of items within an ItemsControl.
    • ItemsSourceView<T>: Provides a standardized view of interactions between an items collection and its control.

  9. Configure Keyboard Navigation for Containers

    main
    You can control how users navigate through child controls using keyboard input (like Tab or arrow keys) by using the KeyboardNavigation class. This class defines attached properties that allow you to set the KeyboardNavigationMode (e.g., how traversal behaves within a container).

  10. Understand the AvaloniaObject class

    main

    AvaloniaObject is the base class for objects that support AvaloniaProperty (Avalonia's property system). It is the Avalonia equivalent of WPF's DependencyObject. Most core Avalonia types, such as Application, Styles, Geometry, and various controls, derive from AvaloniaObject to enable advanced features like data binding, styling, and animation.

    Key Details:

    • Namespace: Avalonia
    • Assembly: Avalonia.Base
    • Implements: IAvaloniaObjectDebug, INotifyPropertyChanged
    • Inheritance: object -> AvaloniaObject
    public class AvaloniaObject

  11. Use BrowserAppBuilder to initialize Avalonia in a browser

    main

    The BrowserAppBuilder class in the Avalonia.Browser namespace is used to configure and start an Avalonia application within a web browser environment. It handles loading necessary JavaScript modules and configuring the browser backend.

    Depending on your needs, you can use one of two primary initialization flows:

    1. Full Initialization: Use StartBrowserAppAsync to configure the backend, load JS modules, and automatically create a single view lifetime tied to a specific HTML element.
    2. Manual View Management: Use SetupBrowserAppAsync to configure the backend and load JS modules without creating views. This is useful if you want to manually manage view lifecycles by creating Avalonia.Browser.AvaloniaView objects yourself.
    // Example of the two main initialization patterns

// Pattern 1: Automatic view creation tied to an HTML element ID
await BrowserAppBuilder.StartBrowserAppAsync(builder, "main-div-id", options);

// Pattern 2: Manual setup for custom view management
await BrowserAppBuilder.SetupBrowserAppAsync(builder, options);
// Then manually create AvaloniaView objects as needed

  12. Handle Clipboard and Drag-and-Drop with DataFormat

    main

    When working with clipboard operations or drag-and-drop, use Avalonia.Input.DataFormat to represent the data types being transferred.

    Note: The legacy Avalonia.Input.DataFormats class is deprecated. You should use Avalonia.Input.DataFormat instead. Similarly, Avalonia.Input.DataObject is deprecated; use Avalonia.Input.DataTransfer for mutable implementations of data transfer.