Carbon.Avalonia.Desktop 0.2.0

Carbon.Avalonia.Desktop

A comprehensive, reusable Avalonia UI control library featuring modern navigation, docking, ribbon, editors, 2D canvas, calendar/schedule, and service-based components for desktop applications.

Features

• Navigation System — Sidebar navigation with header/footer items, horizontal/vertical orientation, and async page lifecycle
• Docking System — Tabbed docking panels with drag-and-drop, split containers, and serialisable layout model
• Ribbon Controls — Ribbon tabs, groups, buttons, toggle buttons, and drop-down menus
• Editor Controls — Typed editors for all .NET numeric types, text, Base64, hexadecimal, and byte arrays with built-in validation
• 2D Canvas (Displayer2D) — Zoomable/pannable 2D drawing surface with shape primitives, images, text, and pluggable interaction handlers
• Calendar & Schedule — Month and week views with drag-to-move, resize, mini-calendar sidebar, and event callbacks
• Service-Based Components — ContentDialog, Overlay, InfoBar, File/Folder dialogs via injectable services
• Settings Controls — SettingsCard and SettingsCardExpander for configuration UIs
• Dark/Light Theme Support — Complete theming system with dynamic resource switching
• Compiled Bindings — Performance-optimized with compiled bindings by default
• Host Integration — Works with Microsoft.Extensions.Hosting for clean service lifetime and IHostedService support

Requirements

• .NET 10.0 or later
• Avalonia 11.3+
• CommunityToolkit.Mvvm 8.4+ (for ViewModels in your application)

Controls

Navigation

Docking

Layout model classes for serialisation: DockPaneModel, DockTabGroupModel, DockSplitModel.

Ribbon

Editors

All editors inherit from BaseEditor and support Title, Unit, ActionContent, SelectAllTextOnFocus (default true), HasValidationError, and ValidationErrorMessage.

Numeric Editors (with Value, Minimum, Maximum, Increment, FormatString):

Text Editors:

Specialized Editors:

Displayer2D (2D Canvas)

Calendar & Schedule

Events: ItemMoved, ItemResized with CalendarScheduleItemChangedEventArgs.

Dialogs & Overlays

Settings

Services

Page ViewModels can implement INavigationViewModel for lifecycle hooks:

• OnDisappearingAsync() — called before navigating away; return false to cancel
• OnAppearingAsync() — called after the page becomes active

Installation

1. Add Package Reference

dotnet add package CarbonAvaloniaDesktop

2. Include Theme Resources

In your App.axaml, include the Carbon theme resources:

<Application xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             x:Class="YourApp.App">
  <Application.Styles>
    <FluentTheme />
    <StyleInclude Source="avares://Carbon.Avalonia.Desktop/Themes/Fluent.axaml" />
  </Application.Styles>
</Application>

3. Set Up Hosting and Services

Carbon uses Microsoft.Extensions.Hosting for clean service lifetime management. Configure the host in Program.cs:

using Avalonia;
using Microsoft.Extensions.Hosting;

namespace YourApp;

sealed class Program
{
    internal static IHost? AppHost { get; private set; }

    [STAThread]
    public static void Main(string[] args)
    {
        AppHost = Host.CreateDefaultBuilder(args)
            .ConfigureServices((_, services) =>
            {
                services.AddHostedServices();   // your IHostedService registrations
                services.AddCarbonServices();   // Carbon service singletons
                services.AddPagesAndViewModels(); // views (Transient) + view models (Singleton)
            })
            .Build();

        AppHost.Start();

        BuildAvaloniaApp().StartWithClassicDesktopLifetime(args);

        // Clean shutdown after the window closes
        AppHost.StopAsync().GetAwaiter().GetResult();
        AppHost.Dispose();
    }

    public static AppBuilder BuildAvaloniaApp()
        => AppBuilder.Configure<App>()
            .UsePlatformDetect()
            .WithInterFont()
            .LogToTrace();
}

Organise your registrations with extension methods:

using Carbon.Avalonia.Desktop.Services;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace YourApp;

public static class ServiceCollectionExtensions
{
    extension(IServiceCollection services)
    {
        public void AddHostedServices()
        {
            // Register your IHostedService implementations here
            _ = services.AddHostedService<ApiHostedService>();
        }

        public void AddCarbonServices()
        {
            _ = services.AddSingleton<INavigationService, NavigationService>();
            _ = services.AddSingleton<IContentDialogService, ContentDialogService>();
            _ = services.AddSingleton<IInfoBarService, InfoBarService>();
            _ = services.AddSingleton<IOverlayService, OverlayService>();
            _ = services.AddSingleton<IFileDialogService, FileDialogService>();
            _ = services.AddSingleton<IFolderDialogService, FolderDialogService>();
        }

        public void AddPagesAndViewModels()
        {
            _ = services.AddSingleton<MainWindow>();
            _ = services.AddSingleton<MainWindowViewModel>();

            // Views are Transient so each navigation creates a fresh instance
            _ = services.AddTransient<HomePageView>();
            _ = services.AddTransient<SettingsPageView>();

            // ViewModels are Singleton to preserve state across navigations
            _ = services.AddSingleton<HomePageViewModel>();
            _ = services.AddSingleton<SettingsPageViewModel>();
        }
    }
}

4. Configure App.axaml.cs

Resolve services from the host and register Carbon host controls:

using Avalonia;
using Avalonia.Controls.ApplicationLifetimes;
using Avalonia.Markup.Xaml;
using Carbon.Avalonia.Desktop.Services;
using Microsoft.Extensions.DependencyInjection;

namespace YourApp;

public partial class App : Application
{
    public override void Initialize()
    {
        AvaloniaXamlLoader.Load(this);
    }

    public override void OnFrameworkInitializationCompleted()
    {
        var services = Program.AppHost?.Services ?? BuildDesignerServices();

        if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
        {
            var mainWindow = services.GetRequiredService<MainWindow>();
            var vm = services.GetRequiredService<MainWindowViewModel>();
            mainWindow.DataContext = vm;

            // Register service hosts
            services.GetRequiredService<IContentDialogService>().RegisterHost(mainWindow.HostDialog);
            services.GetRequiredService<IOverlayService>().RegisterHost(mainWindow.HostOverlay);
            services.GetRequiredService<IInfoBarService>().RegisterHost(mainWindow.HostInfoBar);
            services.GetRequiredService<IFileDialogService>().SetStorageProvider(mainWindow.StorageProvider);
            services.GetRequiredService<IFolderDialogService>().SetStorageProvider(mainWindow.StorageProvider);

            desktop.MainWindow = mainWindow;
        }

        base.OnFrameworkInitializationCompleted();
    }

    /// <summary>
    /// Fallback for the Avalonia Designer, which bypasses Program.Main().
    /// </summary>
    private static IServiceProvider BuildDesignerServices()
    {
        var collection = new ServiceCollection();
        collection.AddCarbonServices();
        collection.AddPagesAndViewModels();
        return collection.BuildServiceProvider();
    }
}

5. Set Up Host Controls in MainWindow

For ContentDialog, Overlay, and InfoBar services, add host controls as siblings in your MainWindow.axaml:

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:controls="using:Carbon.Avalonia.Desktop.Controls"
        x:Class="YourApp.MainWindow">

  <Panel>
    
    <ContentControl Content="{Binding CurrentPage}" />

    
    <controls:ContentDialog x:Name="HostDialog" />
    <controls:Overlay x:Name="HostOverlay" />
    <controls:InfoBar x:Name="HostInfoBar" />
  </Panel>
</Window>

Adding an IHostedService

The hosting setup makes it easy to run background services alongside your Avalonia app. Here is the ApiHostedService from the tester application, which spins up a Minimal API web server:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;

namespace YourApp;

public class ApiHostedService(IConfiguration configuration) : IHostedService
{
    private WebApplication? _app;

    public async Task StartAsync(CancellationToken cancellationToken)
    {
        var port = configuration.GetValue("Api:Port", 5100);
        var title = configuration.GetValue("Api:Title", "My App API");

        var builder = WebApplication.CreateSlimBuilder();
        builder.WebHost.UseUrls($"http://localhost:{port}");

        _app = builder.Build();

        _app.MapGet("/", () => Results.Ok(new { Title = title, Status = "Running" }));
        _app.MapGet("/api/info", () => Results.Ok(new
        {
            Title = title,
            Port = port,
            Environment.MachineName,
            StartedAt = DateTime.UtcNow
        }));

        await _app.StartAsync(cancellationToken);
    }

    public async Task StopAsync(CancellationToken cancellationToken)
    {
        if (_app is not null)
        {
            await _app.StopAsync(cancellationToken);
            await _app.DisposeAsync();
        }
    }
}

Register it in your AddHostedServices() method:

public void AddHostedServices()
{
    _ = services.AddHostedService<ApiHostedService>();
}

Configure port and title via appsettings.json:

{
  "Api": {
    "Port": 5100,
    "Title": "My App API"
  }
}

The host starts before the Avalonia window opens and shuts down cleanly after it closes, so hosted services run for the entire application lifetime.

Usage Examples

Navigation Service

public class MainWindowViewModel : ViewModelBase
{
    private readonly INavigationService _navigationService;

    public MainWindowViewModel(INavigationService navigationService)
    {
        _navigationService = navigationService;

        _navigationService.Items.Add(new NavigationItem
        {
            Header = "Home",
            IconData = IconService.CreateGeometry(Icon.House, IconType.regular),
            PageType = typeof(HomePageView),
            PageViewModelType = typeof(HomePageViewModel)
        });
    }
}

ContentDialog Service

var result = await _dialogService.ShowMessageAsync(
    title: "Confirm Action",
    content: "Are you sure you want to proceed?",
    primaryButtonText: "Yes",
    closeButtonText: "No"
);

if (result == DialogResult.Primary)
{
    // User clicked Yes
}

InfoBar Service

await _infoBarService.ShowAsync(bar =>
{
    bar.Title = "Success";
    bar.Message = "Operation completed successfully.";
    bar.Severity = InfoBarSeverity.Success;
});

Overlay Service

await _overlayService.ShowAsync(new LoadingView());

// Later...
await _overlayService.HideAsync();

File Dialog Service

var files = await _fileDialogService.ShowOpenFileDialogAsync(
    title: "Open File",
    allowMultiple: false,
    filter: new[] { new FilePickerFileType("Text Files") { Patterns = new[] { "*.txt" } } }
);

Folder Dialog Service

var folders = await _folderDialogService.ShowOpenFolderDialogAsync(
    title: "Select Folder",
    allowMultiple: false
);

Editor Controls

<editors:IntEditor Title="Port"
                   Unit="TCP"
                   Value="{Binding Port}"
                   Minimum="1"
                   Maximum="65535"
                   HasValidationError="{Binding HasPortError}"
                   ValidationErrorMessage="{Binding PortErrorMessage}" />

Project Structure

Carbon.Avalonia.Desktop/
├── Controls/
│   ├── Navigation/          # NavigationView, NavigationItem
│   ├── Docking/             # DockingHost, DockPane, DockTabGroup, DockSplitContainer
│   ├── Ribbon/              # Ribbon, RibbonTab, RibbonGroup, RibbonButton, etc.
│   ├── Editors/             # BaseEditor, typed editors (Int, Double, Text, Base64, etc.)
│   ├── CalendarSchedule/    # CalendarSchedule, CalendarScheduleItem, CalendarViewMode, ScheduleInteractionMode, ScheduleDragSession, CalendarScheduleItemChangedEventArgs
│   ├── ContentDialog/       # ContentDialog, DefaultButton, DialogResult
│   ├── InfoBar/             # InfoBar, InfoBarSeverity
│   ├── Displayer2D/
│   │   ├── Groups/          # LineMovingObjectGroup, RectangleRoiGroup
│   │   └── Shapes/          # Shape primitives + MovedEventArgs
│   ├── Overlay.cs           # Overlay host control
│   ├── SettingsCard.cs      # Static settings row
│   └── SettingsCardExpander.cs  # Expandable settings card
├── Services/
│   ├── NavigationService.cs
│   ├── ContentDialogService.cs
│   ├── InfoBarService.cs
│   ├── OverlayService.cs
│   ├── FileDialogService.cs
│   └── FolderDialogService.cs
└── Themes/
    ├── Fluent.axaml          # Main theme include
    ├── Colors.axaml          # Color definitions (Dark/Light variants)
    └── Brushes.axaml         # Brush resources

Key Patterns

• TemplatedControls — All custom controls use TemplatedControl, not UserControl
• ViewLocator — Automatic view resolution by replacing "ViewModel" with "View" in type names
• Service Host Pattern — Dialog/overlay/infobar services require host controls registered at startup
• Two-Way Bindings — Use {Binding ..., RelativeSource={RelativeSource TemplatedParent}, Mode=TwoWay} in templates ({TemplateBinding} is one-way only)
• Theme Resources — Use {DynamicResource} for theme-reactive styling
• Hosting — Microsoft.Extensions.Hosting manages the app lifecycle; IHostedService implementations run alongside the Avalonia window

Theme System

Access theme colors and brushes using dynamic resources:

<Border Background="{DynamicResource CarbonSurfacePrimaryBrush}"
        BorderBrush="{DynamicResource CarbonBorderPrimaryBrush}" />

Available resource prefixes:

• CarbonBackground* — Background colors
• CarbonSurface* — Surface/card backgrounds
• CarbonBorder* — Border colors
• CarbonForeground* — Text colors
• CarbonAccent* — Accent colors
• CarbonSuccess*, CarbonWarning*, CarbonError* — Semantic colors

Development

Build

dotnet build

Run Tester Application

dotnet run --project CarbonAvaloniaDesktopTester

The tester application (CarbonAvaloniaDesktopTester) provides live examples and a testing playground for all controls.