# Conflicts: # crates/ui-contract/src/contract/body/hooks.rs # crates/ui-shell/src/shell/app_shell.rs # crates/ui-shell/tests/it/shell/app_shell.rs
12 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 anAxis, sized by aSplitSize.Tabs: a group of panels with one active tab.Stack: an accordion; eachStackEntrykeeps its open state and height when other panels move.Dock: the dock on one window edge (DockEdge), with itsColumns 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:
- Deserialize it (
Workspaceimplementsserde). - Check it with
Workspace::validate. Keep a file that fails, or that comes from a newerWorkspace::VERSION, on disk; do not overwrite it. - Call
Workspace::reconcilewith 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 in the group's body, which the group insets by the panel padding (Pad::Regular). The group is the body's panel, so the body adds no Panel or padding of its own. A document panel's body (WindowKind::Document) is shown edge to edge. |
group_view |
Takes a whole group in place of its tab strip and body, in a Ui held to the group's rect; 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: the actions hold every change of the pass, divider sizes and window moves included. DockArea::read_only shows a layout locked.
A panel body, or code a body calls, changes the workspace during the pass with docking::request_actions(ctx, actions), never by writing the workspace the area shows. The running area takes them unapplied and returns them in DockAreaOutput::requested, in order, for the host to apply after actions in the same frame. With no area over that panel type running, request_actions hands the actions back for the caller to apply.
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 bodies' requested actions, the events for the host, the focused and picked panels, edit, float_space, columns, the OS windows the floating windows showed in (by a panel of each), window_files, 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 aGroupDrag. Groups and columns registerDockSpots inDockTargets, andresolve_dropmaps the spot under the pointer to anAction. - 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::replaceand theWorkspaceSetswitch and reset change. The dock's own edits keep the revision, so they keep the drag. - A dock column's last open group fills the column: it takes the height the other groups leave and asks for its
DockHeights::fill. The other groups keep the height the user gave them, or take theirDockHeights::default, which shrinks towardscompactbefore the filling group gets less than its fill. Groups that ask for no heights share the free height with the filling group. - 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:actionsturns the command intoActions.
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 row's press hands the move to the OS, the app follows the system pointer and button (Caps::OS_MOVES_TRACKED), and a press that ends within the click distance is a click, which docks nothing; elsewhere the app moves the window, and Escape puts it back. The app sends an OS window its place only when the app changes it (an undo, a reloaded layout); the OS's own moves and resizes are recorded and never sent 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).
A panel or group floated out of the dock (a drag, the Float command, a tab torn out of the window) opens at the width it had docked and at the height its group measures at in a floating window's room (Proposal::Size), at most size.float.height: content that fills its body opens at that height, other content at its own. A column opens at its docked size, at most that height. The area measures once, where the float starts: for a drag in the pass it starts, which adds the size to the drag's payload (runtime::drag::amend). A panel's own PanelSpec float size wins, and a window that already floats keeps its size.
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):panesare the open panes in edge order, andcentrefills what the docked panes leave.PaneContent<P>gives each pane'sPaneSpec, itsPaneState(Noneshows 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::Columnsshows every pane on an edge side by side.SidePolicy::OneSlotshows 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 andWorkspaceAsks.