DOCSEARCHbyAlgolia
Submit Docs

AvalonDock Documentation

repository·master·Indexed 23 days ago

https://github.com/dirkster99/avalondock

A WPF docking framework for arranging documents and tool windows in layouts similar to professional IDEs. It supports MVVM, dependency injection, and modular package architectures. Key components include DockingManager and ToggleDockingManager, along with specialized base classes for dockable view models and integration with CommunityToolkit.Mvvm.

Tokens
44.3K
Snippets
115
Records
189
Agent score
82%

What's inside AvalonDock

  1. Overview of AvalonDock API namespaces

    master

    AvalonDock is organized into several namespaces that separate the layout model, UI controls, and serialization logic:

    • AvalonDock: The root namespace containing the central DockingManager and core types.
    • AvalonDock.Layout: Contains the layout model classes such as LayoutRoot, LayoutPanel, and LayoutDocument.
    • AvalonDock.Controls: Contains the WPF control implementations used to render the docking UI.
    • AvalonDock.Themes: Contains theme base classes like Theme, GenericTheme, and DictionaryTheme.
    • AvalonDock.Commands: Contains command implementations for docking operations.
    • AvalonDock.Converters: Contains WPF value converters used within theme templates.
    • AvalonDock.Core: Contains UI-agnostic interfaces and models.
    • AvalonDock.Core.Serialization: Contains serialization contracts and base classes.
    • AvalonDock.Mvvm: Contains MVVM base classes and services.
    • AvalonDock.DependencyInjection: Contains dependency injection extension methods.
    • AvalonDock.Serializer.Xml: Provides the XML layout serializer.
    • AvalonDock.Serializer.Json: Provides the JSON layout serializer.

  3. Understand what is and isn't persisted in a layout

    master

    Layout serialization only captures the structural arrangement of the docking manager. It does not capture application state or the internal data of your documents.

    ✅ Serialized (Layout State)

    • Panel positions and orientations (horizontal/vertical splits)
    • Panel sizes and widths
    • Tab order
    • Floating window positions and sizes
    • Auto-hide state
    • Active/selected state
    • ContentId and Title of items

    ❌ Not Serialized (Application State)

    • Document text content: Must be saved separately (files/database).
    • View model property values: Must be serialized independently.
    • Event handlers: Must be re-attached during the LayoutSerializationCallback.
    • Runtime UI state: Must be rebuilt in the callback.

  4. Choose between DockingManager and ToggleDockingManager

    master

    AvalonDock provides two primary control types for managing layouts:

    1. DockingManager: The standard control that provides a blank canvas for custom layouts. It is ideal for applications requiring full control over docking behavior and UI.
    2. ToggleDockingManager: A modern control that includes a built-in sidebar. This sidebar automatically populates with registered tool windows (anchorable view models), providing an out-of-the-box experience similar to VS Code or JetBrains IDEs.

  5. Understand ToggleDockingManager Dock Zones

    master

    Unlike the classic DockingManager which uses four sides, ToggleDockingManager organizes panels into six specific zones to allow for more granular control over sidebar and bottom panel placement.

    The available DockZone values are:

    • LeftTop: Left sidebar, top section
    • LeftBottom: Left sidebar, bottom section
    • RightTop: Right sidebar, top section
    • RightBottom: Right sidebar, bottom section
    • BottomLeft: Bottom panel, left section
    • BottomRight: Bottom panel, right section

  6. Understand the AvalonDock layered architecture

    master

    AvalonDock v5.0.0 uses a layered architecture designed to separate the layout model from the visual UI and extensibility layers.

    • Layout Model: The core representation of the UI, consisting of a tree of objects like LayoutRoot, LayoutPanel, and LayoutContent. This model drives the UI, meaning WPF controls are generated from the model rather than the model being derived from the controls.
    • Visual Controls: The WPF-based UI layer that renders the layout model.
    • Serializers: Specialized components for saving and loading layouts using XML or JSON.
    • Themes: XAML-based resource dictionaries that provide visual styling.
    • AvalonDock.Core: The foundation containing UI-agnostic interfaces, models, and contracts with no WPF dependency.

  7. How the AvalonDock v5 MVVM Architecture works

    master

    AvalonDock v5 uses a first-class MVVM and Dependency Injection architecture where the layout is controlled entirely via ViewModels rather than code-behind.

    The Workflow

    1. Composition Root: Use AddDockLayoutService in your App.xaml.cs to configure the layout tree, register toolboxes, and configure the ToggleDockingManager.
    2. Main ViewModel: Your main application ViewModel receives IDockLayoutService via DI. It exposes the IRootDock (the layout tree) which is bound to the ToggleDockingManager.DockLayout in XAML.
    3. Layout Control: Instead of manipulating UI elements, the ViewModel uses IDockLayoutService to open/close documents or access toolboxes.
    4. Rendering: The ToggleDockingManager in XAML uses DataTemplates to render the specific ViewModels (Toolboxes or Documents) and a StyleSelector to handle visual properties like titles and icons.

  8. AvalonDock solution structure

    master

    The source/ directory contains the main solution and various component projects. The core logic is split into specialized NuGet package projects:

    • AvalonDock/: Core docking library
    • AvalonDock.Core/: UI-agnostic interfaces & models
    • AvalonDock.Mvvm/: MVVM base classes
    • AvalonDock.DependencyInjection/: DI extensions
    • AvalonDock.Serializer.Xml/: XML serializer
    • AvalonDock.Serializer.Json/: JSON serializer
    • AvalonDock.Themes.*: Theme packages

    Other directories include automation tests, demo applications (TestApp, MVVMTestApp, etc.), and integration demos (MLib, Caliburn.Micro, WinForms).

  9. Understand the AvalonDock layout model hierarchy

    master

    The layout model is the backbone of AvalonDock and resides in the AvalonDock.Layout namespace. The hierarchy is built around ILayoutElement and follows a tree structure where elements can be containers (groups/panels), content (documents/anchorables), or floating windows.

    Core Hierarchy:

    • ILayoutElement (Base)
      • LayoutElement (Abstract base)
        • LayoutContent (Abstract base for items with UI content)
          • LayoutDocument (Tabbed documents)
          • LayoutAnchorable (Tool windows)
        • LayoutGroup<T> (Abstract containers for splitting views)
          • LayoutPanel (Primary structural element)
          • LayoutDocumentPane (Container for documents)
          • LayoutAnchorablePane (Container for anchorables)
          • LayoutRoot (The top-level entry point)
        • LayoutFloatingWindow (Abstract base for windows outside the main dock area)
          • LayoutAnchorableFloatingWindow
          • `LayoutDocumentFloatingWindow"
    ILayoutElement
├── LayoutElement (abstract base)
│   ├── LayoutContent (abstract)
│   │   ├── LayoutDocument
│   │   └── LayoutAnchorable
│   ├── LayoutGroup<T> (abstract)
│   │   ├── LayoutPanel
│   │   ├── LayoutDocumentPane
│   │   ├── LayoutDocumentPaneGroup
│   │   ├── LayoutAnchorablePane
│   │   ├── LayoutAnchorablePaneGroup
│   │   ├── LayoutAnchorSide
│   │   ├── LayoutAnchorGroup
│   │   └── LayoutRoot
│   └── LayoutFloatingWindow (abstract)
│       ├── LayoutAnchorableFloatingWindow
│       └── LayoutDocumentFloatingWindow

  10. Understand the Layout Serialization Flow

    master

    Layout persistence in AvalonDock follows a specific serialization and restoration lifecycle.

    Saving a Layout:

    1. The DockingManager triggers the serializer (e.g., XmlLayoutSerializer.Serialize()).
    2. The serializer walks the LayoutRoot tree.
    3. It writes the position, size, state, and ContentId for each element.
    4. A layout file (e.g., layout.xml) is produced.

    Restoring a Layout:

    1. The layout file is read by the serializer (e.g., XmlLayoutSerializer.Deserialize()).
    2. The serializer parses the layout tree.
    3. For each content item, it calls a LayoutSerializationCallback.
    4. You must provide the actual content (a ViewModel or UI control) that matches the ContentId found in the file.
    5. The DockingManager rebuilds the visual tree using the provided content.

  11. Difference between Documents and Anchorables

    master

    AvalonDock uses two distinct types of dockable content to organize layouts:

    1. Documents (LayoutDocument): Used for primary content like file editors or viewers. They live in a LayoutDocumentPane, appear as tabs in a document well, and are closable by default. They cannot be hidden or auto-hidden.

    2. Anchorables (LayoutAnchorable): Used for supporting tool windows like Solution Explorer or Properties panels. They live in a LayoutAnchorablePane or an auto-hide LayoutAnchorGroup. They are hideable and can be auto-hidden to side tabs by default, but are not closable by default.

    FeatureLayoutDocumentLayoutAnchorable
    Typical useFile editors, viewersTool windows, panels
    Closable by default✅ Yes❌ No
    Hideable by default❌ No✅ Yes
    Can auto-hide❌ No✅ Yes
    Can float✅ Yes✅ Yes
    IDE equivalentEditor tabsSolution Explorer, Properties, Output

  12. Compare v4 (Legacy) vs v5 Patterns

    master

    When migrating or building new applications, note the following architectural shifts in v5:

    Featurev4 / Legacy Patternv5 Pattern
    AccessStatic Workspace.This singletonIDockLayoutService via constructor injection
    BindingManual DocumentsSource / AnchorablesSourceDockLayout property binds the entire layout tree
    PlacementILayoutUpdateStrategyDockZone enum on each ToolboxBase
    TrackingActiveDocumentConverterIDockLayoutService.ActiveDockable
    ManagementManual ObservableCollection managementOpenOrActivateDocument() / CloseDocument()
    UIDockingManager with manual layoutToggleDockingManager with sidebar toggles