` holds an optional root `Node
` and a list of `Floating` windows. | Node | Holds | |---|---| | `Tabs` | A tab group: panels and the active index. | | `Split` | Two children, horizontal or vertical, with a ratio. A fixed first or second size from a saved layout is drawn at that size until the divider moves; a moved divider stores a ratio. | | `Stack` | Accordion entries, each open or closed, with an optional height. | | `Dock` | A side and its columns. A `Column` has `Group`s, a width, and `iconic`. | A `Floating` window has one or more stacked groups, a rect, and an optional native-window rect. `Floating::single` makes a window with one group; `panels()` and `contains()` read it. `P` is the app's panel id: stable, not localized, `Clone + Eq + Hash`. The renderer also needs `Debug + Send + Sync + 'static`. A panel occurs at most once in a layout. Change a layout only through `Action`s: ```rust use craft_ui::docking::{Action, Floating, Layout, Node, Placement}; let mut layout = Layout { root: Some(Node::Tabs { panels: vec!["layers", "properties"], active: 0 }), floating: vec![Floating::single(vec!["brushes"], 0, [40.0, 80.0, 240.0, 300.0])], }; layout.apply(Action::Move { panel: "brushes", anchor: "layers", placement: Placement::Tab { before: Some("properties") }, })?; # Ok::<(), craft_ui::docking::DockError>(()) ``` - `Move`, `MovePanel`, `Float` and `Close` act on one panel. `MoveGroup`, `MoveColumn` and `MoveWindow` move a group, a dock column or a floating window, named by any panel in it. - A `Target` is `At { anchor, placement }`, `Float { rect }` or `NewDock { side }`. - A `Placement` is a tab position, a split zone, a new group above or below (with an optional preferred `height`), a new column, or a new frame on an outer edge. - Containers take different placements: a dock column takes groups and columns, not splits. `Placement::for_zone(layout, anchor, zone, right_to_left)` maps a left, right, top, bottom or center zone onto what the anchor's container takes: a split in the frame tree, a new column on that side or a new group above or below in a dock, a group above or below in a floating window. - A side split zone puts what moves in a new half-size split of the anchor's frame, and no other frame changes size. The new split has its own divider, and the drop preview shows the half the new frame takes. - Other actions select, minimize, collapse to icons, resize splits, columns and groups, and move a floating window to its own OS window (`SetNative`, feature `native-windows`). Every action checks the whole result before it commits. A bad target, a duplicate id, a stale split path or invalid geometry returns a `DockError` and leaves the layout unchanged. The source panel is never lost. `apply`, `apply_with_permissions` and `apply_all` return the panels the actions closed, so the app can release their state; `closed_by` lists them before applying. `Permissions` limit what may happen to a panel: `movable`, `floatable`, `closable`, `accepts_tabs` and `accepts_splits`. `apply_with_permissions` enforces them for every action, whoever issues it. `Permissions::PROTECTED` keeps a canvas docked and open and takes neither tabs nor side splits; a group dropped on it floats there. An app that opens panels beside its canvas uses `Permissions { accepts_splits: true, ..Permissions::PROTECTED }`. ## Workspace `Workspace
` is what an app saves: the layout, the hidden panels with where each one goes back, an optional saved arrangement for Reset, and `locked`. | Method | Does | |---|---| | `apply`, `apply_all` | Apply actions all or none, with the app's permissions. Closed panels are recorded in `hidden`. While `locked`, moving, floating and closing are refused. | | `set_visible(panel, visible, fallback, permissions)` | Hide a panel that may close, or show it at its recorded place, else beside `fallback`. | | `reconcile(registered, permissions, default)` | Fit a loaded workspace to the panels the app has now. Unknown panels move to `hidden`, so they come back when registered again. A registered panel that cannot close, such as the canvas, is always shown. | | `reset(default)` | Return to the saved arrangement, or to `default` for a built-in workspace. | | `validate` | Check a loaded workspace before use. | With the `serde` feature, `Workspace`, `Layout` and `Action` serialize. Files without a version are v1 and load unchanged. craft-ui does not choose where files go; the app does. ## Rendering `DockArea::new(id).show_content(ui, &layout, &style, &mut content)` draws a layout snapshot and returns a `DockOutput`. It does not change the layout. The app applies `output.actions` through its own command path, so pointer, keyboard and control commands share one path. `DockContent
` is the app's adapter. It draws each panel body and gives its label, icon, permissions, size limits, preferred floating size, panel menu and group header. The group header sits at the end of the tab strip; `group_header_width` gets the strip width, so a header that draws its own tabs can size them to the room left. An icon is an image (`icon`), or drawn in code by `paint_icon`, which gets a painter, the icon rect and the tint color and returns true when it painted. Panel bodies keep a stable egui id when they move, so widget memory survives. `DockOutput` also has: - `focused`: the panel the user focused this frame: a clicked tab, a drop, or a press of any pointer button in a panel body (protected panels included) or in the group header, which focuses the group's shown panel. Commands, `raise_panel` and workspace resets never set it; a host that tracks the last focused panel clears it when a reset or command hides, closes or moves that panel. - `events`: requests outside the layout, such as `DockEvent::ToggleMaximize` (`maximize_item`) and `DockEvent::ToggleAutoCollapse` and `DockEvent::FlyoutChanged { panel }` (docks): the flyout opened, switched or closed (`None`). It comes once per change, whatever made it: an icon, Escape, a press outside, a raised panel, `open_flyout` or `close_flyout`. - `error`: a rejected gesture. Builder options on `DockArea`: | Option | Use | |---|---| | `maximized(panel)` | Maximize Frame: that frame fills the area. | | `hide_panels(HidePanels)` | Hide panels for Tab and Shift+Tab. Protected panels stay. | | `auto_collapse_iconic(on)` | Close a flyout on Escape or a click outside (default on). | | `raise_panel(panel)` | Raise a panel's floating window, or open its flyout, this frame. It moves no keyboard focus and does not set `DockOutput::focused`. | | `blocked_rects(rects)` | App overlays that docking gestures must ignore. | | `float_bounds(rect)` | Where floating windows, flyouts and drag ghosts may go (default: the whole viewport). Pass the viewport below a title bar drawn under a transparent OS title bar, so no floating window sits where a press moves the app window. | `DockStyle::close_menu_items` and `DockStyle::close_button` hide the built-in Close menu items and the floating window ×. They hide controls only: a panel that stays `closable` still closes by the app's own Close items and commands. `DockArea::chrome_has_focus` tells whether keyboard focus is on docking chrome (any control a `Hit` names) rather than on a panel body. Focus follows only the user's input: a tab keeps keyboard focus until a command or a workspace reset hides, closes or moves its panel, and then gives it up. A divider or a floating window's resize grip holds focus only while the pointer drags it, so the app's shortcuts and canvas arrow keys work right after; one reached with Tab or F6 keeps its focus, and arrow keys resize it. Hovering focuses nothing. `begin_drag` hands a drag that started in the app's own chrome to the area. `docking::chrome` has the floating frame, the title bar and `drop_preview` (the drop preview docking and `craft_ui::panes` both draw) for apps that draw their own windows. ## Tab strips Every shown tab carries its panel's full name. Tabs that do not fit go to the "…" button at the end of the strip, whose menu lists the hidden panels; choosing one makes it active. The active tab is always shown, in its logical place: when it lies past the tabs that fit, it takes the place of the last of them. Only an active tab wider than the room beside the "…" button, or a lone tab wider than the strip, is cut with "…", and its tooltip names it in full. The drag bar always keeps its reserved width: tabs go to the overflow menu before it narrows, and only a strip narrower than the bar itself shrinks it. A tab dropped on the "…" button goes to the end of the group. ## Floating size A panel or group floated by a drag, a menu or a command without a rect takes its content height: the title bar, the tab strip and the height the active panel's content used when it was last drawn (the content ui's `min_rect`), at least 120 points. The most it takes is the height of `DockContent::floating_size`, or 320 points for a panel leaving a dock or frame and a group leaving a dock. A short panel therefore floats as a short window. Content that reaches the bottom of its body (a panel that allocates its whole rect) has no height of its own: it floats at the `floating_size` height, else at 320 points. A panel's width is its `floating_size` width, else its docked width; a group keeps its docked width. A flyout fits its content the same way, without the title bar. - A panel the area has not drawn floats at the `floating_size` height, else the docked height capped at 320, or at a `FloatSpace::with_panel_size` size for commands. - A group from a frame without a `floating_size` keeps its frame size. A dock column of several groups floats at the tallest `floating_size` height, else its column height capped at 320. - A rect from a command and a window the user resized keep their size; floating windows are not refitted while open. - Docked layout does not change: a column's last group still fills the column. ## Gestures - A tab drags one panel. A group's drag bar (the space beside its tabs) or its top border drags the whole group. A column bar drags a column. A floating window's title bar drags the window. - A movable floating window resizes from every edge and corner. The top edge and corners are a 4 pt band above the title bar (`chrome::RESIZE_BAND`), so they take no moves and no clicks on the title bar's buttons. A resize keeps the opposite edges in place and stays within the size limits and the screen. A focused resize handle moves its edge 8 pt per arrow key. - Over a frame, the tab strip and the middle join its tabs, and the nearest side splits it. The side zones are trapezoids along the four edges, like a picture frame: a quarter of the frame deep, at least 32 pt and at most half the frame. A split that would leave either half without `DockStyle::min_pane` joins the frame's tabs instead. The gap between two frames is no target. - The outer edge band (`DockStyle::edge_band`) takes a drop as a new frame across the whole window side: top and bottom, and left and right with `side_edge_zones`. It takes a quarter of the window and is offered only when every frame keeps its minimum. Past the band, a frame's own side zones apply. - A divider resizes only the frames that touch it; every other frame keeps its size. It stops when a frame touching it reaches its minimum. Where a divider ends on another divider, a four-way handle (`Divider::Intersection`) moves both. - Every frame has the same minimum, `DockStyle::min_pane` (plus its tab strip), unless its panels ask for more through `PanelLimits::min`. Frames have no maximum unless every panel in them asks for one through `PanelLimits::max`: a panel without a maximum lifts the maximum of the panels it joins. - Drop previews show the destination: an outline for tabs, a line for a new group, column or dock, a filled half for a split. Escape or losing window focus cancels a drag. - Ctrl (⌘ on macOS) held at the drop floats it wherever it lands. With `command_press_floats`, the key held when a tab drag of a frame starts is enough. With `float_hint`, a hint under the pointer names the modifier while a drag offers a docking target: `float_hint_label`, where `{key}` becomes ⌘ or Ctrl. - Double-click a tab or drag bar to minimize a group to its strip. - Right-click a tab for its menu, or a drag bar for the group menu; Enter or Space on a focused drag bar opens it too. A left click on the drag bar only focuses it. - With `DockStyle::wheel_selects_tabs`, the mouse wheel over a tab strip selects the next or previous tab. With `middle_click_closes_tabs`, a middle click on a closable panel's tab closes it. - A column's »/« button collapses it to icons, one icon per panel with a separator between groups. Widen an iconic column to show panel names. Click an icon to open its group as a flyout on the canvas side. Drag an icon to move its panel, or an icon group's top edge (the separator line above it) to move the group. ## Commands With the `serde` feature, `DockCommand
` is the shared control vocabulary. The app puts the
command id under `"command"` in the params and deserializes them. craft-ui has no `serde_json`
dependency.
```rust,ignore
let mut params = params.clone();
params["command"] = json!(id);
let command: DockCommand