Windowing owner api

[wieslawsoltes]

Windowing System PR Summary

Summary

This change set introduces a full windowing control surface for dock and floating windows while preserving all existing defaults. It adds explicit owner resolution modes, taskbar visibility control, host mode selection (managed vs native), and safe modal fallbacks. The changes span model interfaces, factories, settings, Avalonia hosting behavior, tests, docs, and a new ReactiveUI sample that exercises all cases.

Detailed Spec

Goals

• Add per-window owner resolution mode DockWindowOwnerMode.DockableWindow.
• Add per-window taskbar visibility via ShowInTaskbar.
• Add global owner policy (AlwaysOwned, NeverOwned, Default).
• Add host mode switch (Native, Managed, Default) at DockSettings and IRootDock.
• Add safe modal fallback when no owner can be resolved.
• Keep all defaults identical to current behavior.

Defaults (unchanged)

• DockSettings.UseOwnerForFloatingWindows = true.
• DockSettings.UseManagedWindows = false.
• DockSettings.FloatingWindowOwnerPolicy = Default (defers to UseOwnerForFloatingWindows).
• DockSettings.FloatingWindowHostMode = Default (defers to UseManagedWindows).
• IRootDock.FloatingWindowHostMode = Default.
• IDockWindow.ShowInTaskbar = null (do not override platform default).
• IDockWindow.IsModal = false.

Owner resolution order (HostWindow)

• OwnerMode.None => no owner.
• OwnerMode.ParentWindow => use ParentWindow.
• OwnerMode.DockableWindow => use ParentWindow if set (factory prepares this).
• OwnerMode.RootWindow => use root window from Owner or factory chain.
• OwnerMode.Default => use ParentWindow if set, otherwise follow global owner policy:
  • AlwaysOwned => use the visual root from the first DockControl.
  • NeverOwned => no owner.
  • Default => defer to UseOwnerForFloatingWindows.

DockableWindow owner preparation (Factory)

• When OwnerMode.DockableWindow is selected, the factory resolves the current host window of the source dockable before it is removed and assigns it to DockWindowOptions.ParentWindow.

Host mode selection

• Effective host mode resolution:
  • IRootDock.FloatingWindowHostMode (if not Default).
  • DockSettings.FloatingWindowHostMode (if not Default).
  • DockSettings.UseManagedWindows (legacy default).
• Managed => create ManagedHostWindow.
• Native => create HostWindow.

Taskbar visibility

• If IDockWindow.ShowInTaskbar is non-null, Avalonia HostWindow applies it to Window.ShowInTaskbar.

Modal safety fallback

• If IsModal = true and no owner can be resolved:
  • If ownership is forbidden (OwnerMode.None or global policy NeverOwned), show non-modally and emit diagnostic log.
  • Otherwise attempt a fallback owner (root window or visual root) and show modally.
  • If still unresolved, show non-modally and emit diagnostic log.

Changes Description

Core Model and Factory

• Added DockWindowOwnerMode.DockableWindow.
• Added DockFloatingWindowHostMode enum.
• Added DockWindowOptions (owner mode, parent window, modal, taskbar).
• Added ShowInTaskbar to IDockWindow and all model implementations.
• Added FloatingWindowHostMode to IRootDock and all model implementations.
• Added factory preparation step to resolve ParentWindow when OwnerMode.DockableWindow is used.
• Added fluent extensions for host mode and taskbar visibility.
• NavigateAdapter.ShowWindows now respects IsModal when presenting windows.

Settings

• Added DockFloatingWindowOwnerPolicy.
• Added global host mode selection in DockSettings.
• Added helper methods:
  • ResolveFloatingWindowHostMode(IRootDock? root)
  • IsManagedWindowHostingEnabled(IRootDock? root)
  • ShouldUseOwnerForFloatingWindows()
• Extended DockSettingsOptions and AppBuilderExtensions with host mode and owner policy configuration.

Avalonia Hosting

• Owner resolution extended to new modes and global owner policy.
• Modal safety fallback implemented in HostWindow.
• Taskbar visibility applied when specified.
• Managed window hosting detection centralized in DockHelpers and used across docking internals.

Serialization

• AvaloniaDockSerializer includes new FloatingWindowHostMode and ShowInTaskbar fields.

Sample

• New DockReactiveUIWindowRelationsSample showcases:
  • Dockable window ownership chain.
  • Taskbar visibility.
  • Modal/no-owner fallback.
  • Global owner policy and host mode toggles.

Documentation

• New Windowing section and articles:
  • windowing/overview.md
  • windowing/ownership.md
  • windowing/hosting.md
  • windowing/taskbar-and-modal.md
• Updated existing docs: dock-windows.md, dock-window-owner.md, dock-settings.md.

Tests

• Added unit tests for window options and defaults.
• Added headless tests for owner modes, modal fallback, and taskbar application.
• Added settings tests for host mode and owner policy resolution.

Usage Samples

Per-window owner mode and modal presentation

factory.FloatDockable(tool, new DockWindowOptions
{
    OwnerMode = DockWindowOwnerMode.ParentWindow,
    IsModal = true
});

DockableWindow owner mode (use current hosting window)

factory.FloatDockable(tool, new DockWindowOptions
{
    OwnerMode = DockWindowOwnerMode.DockableWindow
});

Taskbar visibility override

factory.FloatDockable(tool, new DockWindowOptions
{
    ShowInTaskbar = false
});

Global host mode selection

AppBuilder.Configure<App>()
    .UseFloatingWindowHostMode(DockFloatingWindowHostMode.Managed);

Per-root host mode override

root.FloatingWindowHostMode = DockFloatingWindowHostMode.Native;

Global owner policy

DockSettings.FloatingWindowOwnerPolicy = DockFloatingWindowOwnerPolicy.AlwaysOwned;