Docking Drag-Drop System

The drag-and-drop pipeline for Beep docking — ghost windows, diamond guide overlay, target resolution, and drag session management

Table of Contents

Overview

The drag-drop subsystem provides the Visual-Studio-like docking experience when users drag panels or tab headers. It consists of 7 classes in the Runtime/DragDrop/ directory:

Drag Pipeline

  1. Initiation — User starts dragging a tab header or panel caption
  2. DockDragSession created — tracks source panel, start position, current state
  3. DockDragGhost shown — semi-transparent window following the mouse
  4. DockingGuideOverlay shown — 5-diamond guide overlay on the host form
  5. DockTargetResolver evaluates valid drop positions
  6. DockGuideController manages guide diamond highlighting
  7. Completion — Panel moved to resolved position; layout recalculated

DockDragGhost

A Form subclass rendered as a semi-transparent rectangle during drag. Size matches the source panel/tab. Color is theme-aware.

DockingGuideOverlay

A transparent always-on-top Form centered on the host form showing 5 directional diamonds:

  • Left/Right/Top/Bottom — Dock to that edge
  • Center (Fill) — Dock to fill remaining space
  • Hovered diamond is highlighted in blue
  • Directional SVG icons from SvgsUIcons rendered inside each diamond
  • ActiveTarget property exposes the currently hovered DockPosition?

DockDragController

Orchestrates the complete drag operation:

  • Starts/stops the drag session
  • Updates ghost position on mouse move
  • Shows/hides the guide overlay
  • Resolves drop targets
  • Commits the panel repositioning
  • Fires DoDragDropEnd / DoDragDropQuit events on the manager

DockTargetResolver

Determines valid drop positions based on:

  • Current mouse position relative to host form and dockspaces
  • Panel's AllowedAreas (bitmask gate)
  • Panel's capability flags (CanFloat, CanAutoHide)
  • Current layout constraints (max groups, max split depth)
  • Tab strip hit testing for in-place reordering

Examples

// Subscribe to drag events
manager.DoDragDropEnd += (s, e) =>
    Console.WriteLine("Drag completed");

manager.DoDragDropQuit += (s, e) =>
    Console.WriteLine("Drag cancelled (Escape)");

// During drag, guide overlay shows 5 diamonds:
//   ┌───┐
//   │ ▲ │   ← Top
//   ├───┤
//   │◀ ◉ ▶│  ◀Left  ◉Fill  ▶Right
//   ├───┤
//   │ ▼ │   → Bottom
//   └───┘