DOCSEARCHbyAlgolia
Submit Docs

Dock docking layout system

repository·master·Indexed 23 days ago

https://github.com/wieslawsoltes/dock

A specialized docking layout system for Avalonia UI applications that enables complex window management, document docking, and layout serialization. It supports multi-document interfaces (MDI), tool panes, floating windows, and split layouts. The library features a decoupled architecture with a model layer (Dock.Model) and a view layer (Dock.Avalonia), providing integrations for MVVM frameworks like ReactiveUI and Prism, as well as multiple serialization formats including JSON, XML, YAML, and Protobuf.

Tokens
129.1K
Snippets
305
Records
528
Agent score
80%

What's inside Dock

  1. Overview of Dock docking layout system

    master

    Dock is a docking layout system designed specifically for Avalonia applications. It provides advanced features for managing complex UI layouts, including document management, serialization, and floating windows.

    Key Capabilities:

    • Document Management: Bind collections directly to DocumentDock using ItemsSource for automatic management. Use DocumentTemplate for custom content rendering.
    • Performance Optimization: Supports optional document content caching via the CacheDocumentTabContent theme option and deferred content materialization to handle expensive UI work.
    • Layout Persistence: Comprehensive serialization support for saving and restoring layouts in JSON, XML, YAML, or Protobuf formats.
    • UI Flexibility: Supports floating windows (detaching documents/tools), rich theming (Fluent and Simple), and multiple MVVM frameworks (ReactiveUI, Prism, ReactiveProperty, or standard MVVM).
    • Integration: First-class support for .NET Dependency Injection containers.

  2. Overview of the Dock docking system

    master
    Dock is a docking layout system designed for Avalonia. It enables the creation of complex UI patterns including document and tool panes, floating windows, docking targets, and layout persistence. It supports both declarative XAML layouts and code-first factories, providing multiple model implementations to integrate with common MVVM frameworks.

  4. Understand Dock Model Control Interfaces

    master

    Dock uses a set of interfaces under Dock.Model.Controls to define the view models used for building layouts. These contracts describe how different parts of the UI (docks, documents, tools, and splitters) interact. The interfaces are implemented by the MVVM and ReactiveUI libraries provided in the project.

    To build a layout, you typically start with an IRootDock and compose it using IToolDock, IDocumentDock, and IProportionalDock instances. Documents and tools implement IDocument or ITool respectively, and can optionally use *Content interfaces to expose additional data.

  5. Available Dock UI patterns

    master

    You can use Dock to implement several common UI patterns:

    • Multi-document interfaces (MDI) with tabbed documents.
    • Tool panes that support auto-hiding, pinning, or floating.
    • Split layouts featuring proportional sizing and drag handles.
    • Floating windows with docking indicators.
    • Managed floating windows that are hosted within the main application window.
    • Persisted layouts that allow the UI state to be restored across user sessions.

  6. Choose a Dock.Model implementation

    master

    Dock provides several factory libraries that adapt the base model to different MVVM frameworks. Choose the one that matches your application's architecture:

    • Dock.Model.Avalonia: Plain Avalonia version with minimal dependencies.
    • Dock.Model.Mvvm: MVVM implementation with INotifyPropertyChanged helpers.
    • Dock.Model.CaliburMicro: Caliburn.Micro implementation using PropertyChangedBase.
    • Dock.Model.Inpc: Basic INotifyPropertyChanged implementation without MVVM commands (lightweight).
    • Dock.Model.ReactiveUI: ReactiveUI integration with observables and commands.
    • Dock.Model.ReactiveProperty: ReactiveProperty framework integration.
    • Dock.Model.Prism: Prism framework integration with commands and bindings.

  7. Choose a Dock serialization format

    master

    Dock provides several implementations of IDockSerializer to persist layouts. All serializers accept an optional list type for dockable collections; if not specified, they default to ObservableCollection<>.

    Available serializers:

    • Dock.Serializer.Newtonsoft: JSON serialization using Newtonsoft.Json.
    • Dock.Serializer.SystemTextJson: JSON serialization using System.Text.Json.
    • Dock.Serializer.Protobuf: Binary serialization using protobuf-net.
    • Dock.Serializer.Xml: XML serialization.
    • Dock.Serializer.Yaml: YAML serialization.

  8. How the Drag Offset Calculator works

    master

    The IDragOffsetCalculator interface determines how the drag preview window is positioned relative to the pointer during drag operations. This ensures the preview remains aligned with the item being moved.

    By default, DockControl uses a DefaultDragOffsetCalculator, which keeps the preview locked to the tab being dragged so the window appears in the same place when released.

  9. Configure Windowing Defaults

    master

    The behavior of floating windows is governed by DockSettings. The following default behaviors apply:

    • Ownership: Floating windows are owned by the main window if DockSettings.UseOwnerForFloatingWindows is set to true.
    • Host Mode: Floating windows use native OS windows by default if DockSettings.UseManagedWindows is set to false.
    • Modality: Modal windows require a resolved owner. If an owner cannot be found, the window will be shown non-modally, and diagnostic logging will be enabled.

  10. What DockableControl does and how it tracks state

    master

    The DockableControl is a lightweight wrapper used within Dock templates to track the visual state of an IDockable. It is responsible for registering controls in factory tracking dictionaries and recording bounds and pointer positions for drag operations.

    When its DataContext is an IDockable, it performs the following:

    • Registers itself in factory dictionaries (VisibleDockableControls, PinnedDockableControls, or TabDockableControls) and records the templated root in corresponding root dictionaries (VisibleRootControls, PinnedRootControls, or TabRootControls).
    • Stores bounds using SetVisibleBounds, SetPinnedBounds, or SetTabBounds.
    • Updates pointer positions (including screen coordinates) during pointer presses and moves.

    Warning: If you override templates for document content, tool content, tab items, or pinned items, you must keep DockableControl in place. Without it, factory tracking dictionaries remain empty, and Dock loses bounds and pointer history for that dockable.

  11. Use Managed Windows for floating docks

    master

    Managed hosting allows floating windows to be rendered inside the main window using an MDI (Multiple Document Interface) layout system instead of spawning native OS windows. This is useful for keeping all UI elements within a single application container.

    Enabling Managed Hosting

    You can enable managed hosting:

    1. Globally: Via DockSettings.FloatingWindowHostMode.
    2. Per Root: Via IRootDock.FloatingWindowHostMode.

    Implementation Requirements

    • If you override host window creation, you must return ManagedHostWindow when managed windows are enabled.
    • DockControl.EnableManagedWindowLayer must be set to true for managed windows to be visible.

  12. Manage Docking States with DockingWindowState

    master

    The IDockable.DockingState property uses DockingWindowState flags to track where an item is located.

    Primary Locations:

    • Docked: The item is part of a dock layout.
    • Pinned: The item is pinned to a layout edge.
    • Document: The item is in a document-style layout.

    Additional States:

    • Floating: Added when the dockable is in a floating window.
    • Hidden: Added when the dockable is moved to IRootDock.HiddenDockables.

    Common Combinations:

    • Docked | Floating
    • Pinned | Floating
    • Document | Floating | Hidden