Files
craft-libs/docs/ui-docking.md
T
aiongg c19abe8663 Dock a native window by dragging its title row
A floating dock group in its own OS window now moves through a window move
gesture the app runs, which reports Begin, Update, Commit and Cancel like a
layer's move, so the dock marks the target under the pointer and docks the
whole window on release.

- macOS (Caps::OS_MOVES_TRACKED): the OS moves the window (StartMove), and the
  app follows the system pointer, button and Cmd through SystemWindows, the
  running platform's WindowSystem in craft-window. The hand-off ends when the
  system reports the button up.
- X11 and Windows: the app moves the window with SetOuterPosition so the
  pressed point stays under the pointer; Escape puts it back.
- A drag started by a container shown in its own OS window follows that
  window's pointer, not its parent's.
- The runtime's end hook sets NSWindow.movable for every window; a window
  whose move the app runs is never moved by AppKit from its band.
2026-11-12 14:32:39 +00:00

10 KiB

Docking

Docking has three layers:

Layer Holds
craft_behavior::dock (craft-behavior) The model: Workspace, Layout, Node, Action, Permissions, WorkspaceSet. No egui; this is the saved data.
craft_ui::docking (craft-ui-panels) The parts: SplitArea, DockGroup, DockColumn, IconicColumn, Flyout, FloatingGroup, DockRoot, Splitter; drop resolution; the dock commands.
craft_ui::patterns::dock (craft-ui-patterns) The patterns an app shows: DockArea over a workspace, PaneArea for task panes, WorkspaceSwitcher.

An app with dockable panels shows a DockArea. The parts are for patterns that need one piece, such as a two-body split.

Model

A Workspace is a saved arrangement: its layout and the hidden panels with the place each one goes back to. A Layout is a docked tree (root: Option<Node<P>>) plus floating windows (floating: Vec<Floating<P>>). P is the app's panel key. Every panel occurs once.

Node has four forms:

  • Split: two children along an Axis, sized by a SplitSize.
  • Tabs: a group of panels with one active tab.
  • Stack: an accordion; each StackEntry keeps its open state and height when other panels move.
  • Dock: the dock on one window edge (DockEdge), with its Columns from the edge inwards. At most one per side.

The tree is in reading order: a split's first child is its start (or top) child. Under right-to-left the renderer maps rects with Flow::to_physical.

Edits are Actions: Move, Float, Close, Activate, Open, OpenAt, MoveFloating, ResizeSplit, ResizeWindowSplit and the rest. Workspace::apply and Workspace::apply_all apply them against each panel's Permissions and the lock, and refuse what the rules forbid with a DockError. Permissions::ALL allows everything. Permissions::PROTECTED is a document canvas: it stays docked and open, and takes neither tabs nor side splits.

To load a saved workspace:

  1. Deserialize it (Workspace implements serde).
  2. Check it with Workspace::validate. Keep a file that fails, or that comes from a newer Workspace::VERSION, on disk; do not overwrite it.
  3. Call Workspace::reconcile with the panels the app registers now and a default workspace.

WorkspaceSet holds the app's named workspaces (built-in and saved), the current one and Lock Workspace.

DockArea

let mut panels = Panels { document: &mut state.document };
let mut area = DockArea::new("Dock", Bind::bound(&mut state.workspace), &mut panels, DockConfig::default());
if let Some(panel) = state.maximized {
    area = area.maximized(panel);
}
for event in area.show(ui).events {
    if let DockEvent::ToggleMaximize { panel, .. } = event {
        state.maximized = if state.maximized == Some(panel) { None } else { Some(panel) };
    }
}

The host implements DockPanels<P>:

Method Does
spec The panel's PanelSpec, read every pass: label, icon, SizeLimits, DockHeights, float size, allow_native, window_kind, canvas.
permissions The panel's Permissions (default ALL).
body Shows the panel's body.
group_view Takes a whole group in place of its tab strip and body; a canvas group draws its document here. Default None.
group_header The host's controls in a group header, before the tab strip.
panel_rows The host's rows of a panel's menu, before the dock's own.

The binding decides who applies the edits. With Bind::bound the area writes every action to the workspace itself. With Bind::given it writes nothing, and the host applies DockAreaOutput::actions (or edit, the same changes as edit events) to its own copy. DockArea::read_only shows a layout locked.

Props: hide (HidePanels::None, All or Except), maximized, auto_collapse, locked, and flyout, which binds the open flyout to the host's value (the area keeps it otherwise). A hidden panel keeps its place for restore.

DockAreaOutput holds the actions taken, the events for the host, the focused and picked panels, edit, float_space, and error: an InvalidGeometry when the workspace fails validate, in which case the area draws nothing.

The host handles these DockEvents:

Event Host does
ToggleMaximize Sets or clears the panel it passes as maximized.
ToggleAutoCollapse Flips its preference and passes it back.
PanelCommand Carries out Move Panel To and Move Group To: asks for a destination and calls move_actions.
FlyoutChanged Nothing when the area or a write-through binding holds the flyout; applies the request when the binding is given.
FloatPlaced Reports for a host that anchors its own surfaces to the dock; DockAreaOutput::columns gives every column's rect each pass.

DockConfig

Field Default Effect
side_edge_zones off Picture-frame profile: deep side zones on groups, and the outer start and end edges add full-height columns.
drop_edges DockSides::ALL Which outer edges (and sides of a group that takes no tabs) take a drop.
new_dock_zones on The start and end edges of the docked area take a drop as a new dock.
close_others_item, maximize_item off Group menu items Close Other Panels in Group and Maximize Frame.
float_on_empty_drop on A release over no drop target floats what the drag carries. Off: it cancels the drag.
title_bar_docks on Dragging a floating window's title bar onto a target docks the whole window.
close_menu_items, close_button on Built-in Close items, and the close action on floating windows.
tab_close_buttons off Close buttons on tabs (middle click closes too), for tabs that act as documents.
native_windows on Floating windows open as OS windows where the window host opens them and reports their positions (not on Wayland) and PanelSpec::allow_native allows.

The theme's docking sizes (DockSizes) set the drop bands and zones. DockWords holds the words.

Rules

  • A tab drag carries a PanelDrag; a group or column drag carries a GroupDrag. Groups and columns register DockSpots in DockTargets, and resolve_drop maps the spot under the pointer to an Action.
  • Ctrl or Cmd held at the release floats the drop. A release over the dragged unit's own group leaves it where it is.
  • A drag ends without a change when another arrangement replaces the workspace it started on: it records the workspace's revision, which Workspace::replace and the WorkspaceSet switch and reset change. The dock's own edits keep the revision, so they keep the drag.
  • Split handles are Tab stops, and the arrow keys move them. A divider drag is one gesture in DockAreaOutput::edit.
  • A panel command (DockCommands) acts on the shown panel of the group that takes it. A menu row, a key and the command palette run the same code: actions turns the command into Actions.

Commands and workspaces

Set Commands Run with
DockCommands Float, move, close, step, minimize, collapse to icons, maximize The DockArea itself. A host that shows its own dock calls actions and Workspace::apply_all.
WorkspaceCommands Reset, New, Delete, Lock run_workspace, which returns a WorkspaceAsk when the host must ask for a name or a workspace. WorkspaceSet::select switches.
ArrangeCommands Arranging document windows arrange over DocumentWindows.

WorkspaceSwitcher is a select over the set's names with the workspace commands in its list.

Floating and native windows

A floating window is a Floating in the layout: its rect in logical points in the app's viewport, and native and monitor while it is an OS window. FloatingGroup shows it. With DockConfig::native_windows (on by default), every floating window opens in its own OS window (docking::native) where the window host opens OS windows and reports where they are (WindowHost::positions_reported; not on Wayland); a window never shown native yet opens over its place in the main window. Elsewhere, and for a panel with allow_native off, the window stays inside the main window. The OS close of a native window is its Close action: the window closes when every panel in it may close. Dragging a native window by its title row moves the whole window and docks it where it is released over a group of the main window, as a floating window inside the main window does: the window host runs that move (runtime::windows::keeps_app_drag). On macOS the OS moves the window and the app follows the system pointer and button (Caps::OS_MOVES_TRACKED); elsewhere the app moves it, and Escape puts it back. window_kind says whether an OS window is a document or a tool window. A tool window's title row is its only title bar, whatever frame the main window has (craft_window::policy::tool_frame).

SplitArea on its own

SplitArea::new(label, layout, rules) shows the docked tree of a Layout with handles between groups; FrameRules give each panel's limits. SplitArea::pair(label, axis, bodies, share, rules) is a two-body split with one divider. The host keeps the share and reads its edits from SplitAreaOutput::share; the timeline's track split works this way.

PaneArea

PaneArea shows task panes around a document, without a dock Layout. The app keeps which panes are open, where they are and how big:

  • PaneArea::new(label, panes, content).show(ui, centre): panes are the open panes in edge order, and centre fills what the docked panes leave.
  • PaneContent<P> gives each pane's PaneSpec, its PaneState (None shows the default), its body and its menu rows.
  • The output lists PaneRequests (Close, Place, FloatRect, Minimize, Resize, Focus, Before) in the order they happened. The app applies them in that order.
  • SidePolicy::Columns shows every pane on an edge side by side. SidePolicy::OneSlot shows one closable pane per edge.
  • PaneCommands (move to an edge, float, close) act on the pane that holds focus.

What stays in the app

  • The panel keys, the panel registry and the panel bodies.
  • Workspace files: where they live, their names and their size caps.
  • The answers to DockEvents and WorkspaceAsks.