Tree Page View Model

Overview

TreePageViewModel<TContext,TSubPage> is an abstract class that powers tree‑structured pages in Asv.Avalonia. It builds on top of PageViewModel and adds:

A hierarchical menu tree (TreeView) that can be navigated.
Management of selected nodes and the corresponding subpage (SelectedPage).
Breadcrumb navigation (BreadCrumb).
Commands to show/hide the side menu.
Proper disposal of dynamically created resources.

Typical use cases include settings panels or any UI where a left‑hand tree selects a detail view on the right.

The subpages displayed on the right are implemented using TreeSubpage.

Core Components

User selects a node → SelectedNode changes.
SelectedNodeChanged skips null and internal navigations, rebuilds the breadcrumb from the node's path to the root, and calls Navigate(node.Base.NavigateTo).
Navigate either creates a new subpage through the DI container (CreateSubPage) or builds a default page (CreateDefaultPage).
The new subpage becomes the SelectedPage; the old subpage (if any) is disposed.

Tree Structure

Nodes is a flat collection of ITreePageMenuItem: root items and nested items alike are added straight into it. The hierarchy is not expressed by nesting — TreeView derives it from each item's Id and ParentId, treating NavId.Empty as the root.

The breadcrumb automatically updates based on the selected node, showing the path from the root to the current selection.

You can show or hide the side menu using ShowMenuCommand and HideMenuCommand. The IsMenuVisible property reflects the current state.

Layout Management

The tree page automatically saves and restores its state through the Layout controller. In AfterLoadExtensions it registers two layout values:

the selected node, stored as the node key string under nameof(SelectedNode);
IsMenuVisible, stored under nameof(IsMenuVisible).

Both are saved whenever they change, and loaded once the page is attached to the shell — so when the page is reopened, it restores the previously selected node and the menu state.

Default Page

If no specific subpage is found for a navigation ID, the CreateDefaultPage() method is called. By default, it creates a GroupTreePageItemViewModel which displays all child nodes of the selected tree node as clickable cards.

Example

A typical usage example is a Settings page. It consists of a tree structure where nodes correspond to subpages with concrete settings (e.g., shortcuts, units, etc.).

First, create an ISettingsPage interface for the settings page. ITreePageViewModel already supplies the Nodes collection, so the interface only has to name the page:

public interface ISettingsPage : ITreePageViewModel;

Next, create the SettingsPageViewModel:

public class SettingsPageViewModel
    : TreePageViewModel<ISettingsPage, ISettingsSubPage>,
        ISettingsPage
{
    public const string PageId = "settings";

    public SettingsPageViewModel(
        IPageContext context,
        IServiceProvider host,
        ILoggerFactory loggerFactory,
        IDialogService dialogService,
        IExtensionService ext
    )
        : base(PageId, context, host, loggerFactory, dialogService, ext)
    {
        Header = "Settings";
        Icon = MaterialIconKind.Settings;
    }
}

To add nodes to the tree view, use extensions. The DefaultSettingsExtension resolves all ITreePageMenuItem services keyed by the parent page ID and adds them to the tree:

public class DefaultSettingsExtension(
    [FromKeyedServices(SettingsPageViewModel.PageId)] IEnumerable<ITreePageMenuItem> items
) : IExtensionFor<ISettingsPage>
{
    public const string StaticId = "ext.settings.tree";

    string Asv.Modeling.ISupportId<string>.Id => StaticId;

    public void Extend(ISettingsPage context, CompositeDisposable contextDispose)
    {
        foreach (var treePageMenuItem in items)
        {
            context.Nodes.Add(treePageMenuItem);
            treePageMenuItem.DisposeItWith(contextDispose);
        }
    }
}

Tree menu nodes are registered as keyed services in the DI container (keyed by the parent page ID), so the extension automatically picks them up.

Registration

All components must be registered in the builder chain. A typical registration for a tree page:

// Register the tree page itself
builder.Shell.Pages.Register<SettingsPageViewModel, TreePageView>(SettingsPageViewModel.PageId);

// Register the extension that adds a button to the home page
builder.Extensions.Register<IHomePage, HomePageSettingsExtension>();

A subpage needs its view model, its view, and its tree menu node. The first two are registered together by the TreePage builder, which wires up the keyed view model (with its tree subpage context) and the view locator entry:

// Register the subpage view model and its view
builder.TreePage.Register<
    ISettingsPage,
    ISettingsSubPage,
    SettingsAppearanceViewModel,
    SettingsAppearanceView
>(SettingsAppearanceViewModel.PageId);

// Register the tree menu node (keyed by the parent page ID)
builder.Services.AddKeyedTransient<ITreePageMenuItem, AppearanceSettingTreePageMenu>(
    SettingsPageViewModel.PageId);

In practice, the registration builder SettingsPageRegistrations.Builder wraps both calls into a single one:

builder.AddSubPage<
    SettingsAppearanceViewModel,
    SettingsAppearanceView,
    AppearanceSettingTreePageMenu
>(SettingsAppearanceViewModel.PageId);

For information on how to create subpages that are displayed when tree nodes are selected, see TreeSubpage.

API

ITreePageViewModel

Property	Type	Description
`Nodes`	`ObservableList<ITreePageMenuItem>`	Gets the flat collection of all menu items. The hierarchy is built from each item's `Id`/`ParentId`, not from nesting in this list.