NAME

zeughaus-keys - keys, pointer gestures and palette commands of the zeughaus editor

DESCRIPTION

The editor, zeughaus, has few keys of its own. Changes of structure (splitting a pane, attaching a job's terminal, holding a runner, choosing a theme, adding a node) are entries of the command palette; tabs, groups and panes move by dragging. KEYS lists every binding by where it acts, PALETTE COMMANDS every palette entry as the palette names it.

Where a macOS key is given it is what macOS binds. There Ctrl+Space, Ctrl+S, Ctrl+O and the terminal's Ctrl+Shift chords work as well, and the terminal's Cmd chords also take Shift. The graph canvas takes Cmd only: its keys use iced's command modifier, which is Ctrl elsewhere. The browser editor has no file dialog, no runner and no terminals; its graph keys differ where noted.

The command palette

Ctrl+Space opens the palette, on macOS also Cmd+Shift+P, because the system uses Ctrl+Space there to switch the input source by default. The palette acts on the whole window, not on one pane: tabs, panes, terminals and the graph. It is drawn over everything below the titlebar, the tab in front and, when the tab bar sits at the left edge, the bar.

While it is open the palette holds the keyboard. Its search field has the focus, no terminal pane takes keys, and a key the field takes does not reach the graph beneath. Typing filters by a fuzzy match over each entry's name and description, best match first. Enter runs the highlighted entry, which is the first match after every keystroke and otherwise follows the pointer; no key moves it. Escape, Ctrl+Space again, the x button or a click beside the list closes the palette.

The entry list is rebuilt when the palette opens and not while it is open, so a runner's workspace changing during a search does not move the entry Enter runs. It holds the editor's own entries first, then what the connected runners offer, then the themes, then one entry per node type.

Keyboard focus and the terminal lease

A terminal pane has the keyboard while its pane is focused and neither the palette nor a tab or group name field is open. A click in a pane focuses it; the palette's pane commands and new nodes go to the focused pane as well. With the keyboard, a terminal takes every key it has a meaning for; Ctrl+Space (and Cmd+Shift+P on macOS) never reaches the shell, and on macOS no key held with Cmd does.

Keys reach the child only through the lease. Any editor may view a terminal; exactly one client holds its lease and may type, paste, resize it and send mouse reports. The first client that types into a terminal nobody holds acquires it; Ctrl+Shift+T (Cmd+T on macOS) takes it from whoever holds it. A lease held by an earlier editor process of the same identity counts as this editor's own. Without the lease a pane is a viewer: it selects, copies and scrolls locally, and its keystrokes are dropped, not queued.

The keyboard goes back to the editor when another pane is clicked, the palette opens or a tab or group rename starts. The terminal widget treats Ctrl+Shift+Escape (Cmd+Escape on macOS) as the way out: it swallows the key and reports the pane as giving up the keyboard. The editor acts only on a pane gaining focus and leaves the focus where it is, so the pane keeps the keyboard.

The window keys (Ctrl+Space, Ctrl+S, Ctrl+O, Escape, Enter) are read from every key press in the window, whichever widget took it: Ctrl+S typed into a shell reaches the shell and opens the save dialog as well.

Dragging tabs, groups and panes

A press on a tab, a group header or a pane grip becomes a drag once the pointer has moved 4 logical pixels with the button held; a release before that is a click. During a drag a label at the pointer names what is dragged, and a marker in the bar or a lit pane edge shows where it would land. A release where nothing accepts the drop changes nothing, and Escape cancels the drag.

Every drop is a command to the section's runner, which changes its workspace and sends the result to every attached editor. Tabs never move between sections, the Local and Not running sections take no drops, and a locked group, such as the runner's Triggered group, neither takes nor gives up a tab.

A drop on a pane lands on the pane's edge nearest the pointer, when the pointer is within 30 % of the pane's width or height from that edge; the middle of a pane takes no drop.

Where the bindings live

zeughaus/src/app/mod.rs: the window keys (subscription, is_palette_shortcut), the titlebar, the tab bar and the graph canvas wiring.
zeughaus/src/palette.rs: every palette entry.
zeughaus/src/workspace.rs: drag, drop and rename rules.
iced_tabs/src/lib.rs: the tab bar's presses, double-clicks and halves.
iced_terminal/src/input.rs, iced_terminal/src/widget.rs: terminal keys, mouse and selection.
iced_nodegraph 0.5, Keymap::default: the graph canvas keys and gestures.
iced_palette: the palette's search and list.

KEYS

Palette

Ctrl+Space macOS Cmd+Shift+P: Open the command palette over the window, or close it. Works from anywhere, a terminal with the keyboard included, and never reaches the shell. Ctrl+Space is bound on macOS too, where the system uses it to switch the input source by default.
Typing: Filter the entries by a fuzzy match over each entry's name and description, best match first. The highlight returns to the first match.
Enter: Run the highlighted entry and close the palette.
Pointer over an entry: Highlight it. No key moves the highlight.
Click an entry: Run it and close the palette.
Escape: Close the palette without running anything.
Click beside the list: Close the palette. So does its x button.

Window

Ctrl+S macOS Cmd+S: Save the document this window holds, every graph with its nodes, settings and wires, as JSON to a .zgh or .json file picked in a dialog. Read from every key press in the window, so it also fires while a terminal has the keyboard. Native editor only; refused with a hint in headless mode.
Ctrl+O macOS Cmd+O: Load a .zgh or .json graph document picked in a dialog. It replaces the document this window shows. Native editor only; refused with a hint in headless mode.
Escape: Close the palette, abandon a node, tab or group rename in progress and cancel a tab or pane drag.
Double-click titlebar: Maximize the window, or restore it.
Drag titlebar: Move the window. The move starts once the pointer has left the press point by 4 logical pixels, so a double-click never moves the window.
Drag window edge: Resize the window. Native windows that are not maximized.
Click titlebar corner button: Move the tab bar between the top edge, where it sits in the titlebar, and the left edge, where it is a sidebar. Remembered in <state-dir>/editor.toml.

Tab bar

Click tab: Bring the tab to the front. A click is a press released before the pointer moved 4 logical pixels.
Double-click tab: Rename the tab in place. Enter commits, Escape abandons; an empty or unchanged name changes nothing. A tab that shows one graph renames the graph, in every editor.
Double-click group name: Rename the group in place. Enter commits, Escape abandons; an empty name changes nothing.
Click tab close button: Close the tab and kill its terminals. A job's terminal in a normal tab is detached instead and stays attachable from the palette; in a locked group it is killed too. A top-level graph the tab shows is deleted.
Click section or group arrow: Collapse or expand it, in this window only.
Click + Shell: Open a new terminal tab on the section's runner.
Click + Graph: Create a graph that the section's runner executes and bring it to the front. In the Local section, a scratch graph.
Click + Group: Add an empty group, Group <n>, at the end of the section.
Click group colour dot: Give the group the next of eight colours. Not on a locked group.
Click group close button: Dissolve the group; its tabs stay where it was. Not on a locked group.
Drag tab onto tab: Move the tab before or after that tab, by the half under the pointer: left or right with the bar on top, upper or lower in the sidebar.
Drag tab onto group header: Move the tab into the group, as its last tab.
Drag tab to a section's end: Move the tab to the end of the section's top level: the zone after its last item, or the bar's empty rest for the last section.
Drag group header: Move the group within its section's top level. Dropped on another group's header it lands before that group; groups do not nest.
Escape: Cancel the drag in progress, or abandon the rename.

Panes

Click pane: Focus it. The pane commands, new nodes and the keyboard follow the focused pane.
Drag split divider: Resize the split. The ratio reaches the runner at most every 100 ms, and the last one of a drag always does.
Drag tab onto pane edge: Split that pane and put the dragged tab's panes beside it, on the edge nearest the pointer. The dragged tab goes away.
Drag pane grip into tab bar: Take the pane out of its tab into a tab of its own at the drop position; onto a group header, as the group's last tab. A tab with more than one pane shows a grip on each, outside the Local and Not running sections.
Drag pane grip onto pane edge: Move the pane beside that pane, on the edge nearest the pointer.

Graph canvas

Ctrl+A macOS Cmd+A: Select every node of the graph.
Escape: Clear the selection.
Ctrl+D macOS Cmd+D: Clone the selected nodes, offset by 30 on both axes; a container's contents come with it. The browser editor binds Alt+D instead, since browsers take Ctrl+D.
Delete or Backspace: Delete the selected nodes and their wires; a container takes its contents with it. The browser editor binds Delete only.
Home: Fit the view to every node.
F: Fit the view to the selection.
Click node: Select it alone. Keys reach the canvas after the nodes, so a text field in a node that has the keyboard gets them first.
Shift+Click node: Add it to the selection, or take it out.
Drag node: Move it, or the whole selection when it is selected. Every editor sees the move when the drag ends.
Drag on empty canvas: Select the nodes the box touches, replacing the selection. A click on empty canvas clears it.
Shift+Drag on empty canvas: Add the nodes the box touches to the selection.
Right-drag: Pan the view. Every pane showing the graph shares its camera.
Wheel: Zoom at the pointer.
Drag from pin: Draw a wire; it connects when it snaps onto a pin that accepts it. A refused wire says why in the status line.
Drag connected pin: Unplug that end of its wire. It disconnects once the pointer leaves the pin, and can be plugged into another pin.
Shift+Drag connected pin: Draw an additional wire from the pin and leave the existing ones.
Ctrl+Click wire macOS Cmd+Click wire: Cut the wire.
Ctrl+Drag on empty canvas macOS Cmd+Drag on empty canvas: Cut every wire that the straight line from the press to the pointer crosses, on release.
Drag Display corner: Resize a Display node (transform.display) by its bottom-right corner. No other node resizes.

Nodes

Click header pencil: Rename the node in its header. Enter or the pencil again commits, Escape abandons; an empty name restores the catalog name.
Click header close button: Delete this node alone, not the selection.
Click Trigger: Press a Button node (flow.button). The press goes to the runner that executes its graph, from any editor.
Click open: Open a container's contents in a tab: in its runner's workspace, shared with every editor, or in this window when no runner executes it.

Terminal

Ctrl+Shift+T macOS Cmd+T: Take the lease: this editor becomes the terminal's controller, revoking whoever held it.
Ctrl+Shift+C macOS Cmd+C: Copy the selection to the clipboard. Works without the lease.
Ctrl+Shift+V macOS Cmd+V: Paste the clipboard into the child as one paste. Needs the lease.
Ctrl+Shift+Escape macOS Cmd+Escape: Swallowed, not sent to the child, and reported to the editor as the pane giving up the keyboard. The editor acts only on a pane gaining focus, so the pane keeps the keyboard; click another pane or open the palette to move it.
Ctrl+Space macOS Cmd+Shift+P: Reserved for the palette: never reaches the shell.
Shift+PageUp: Scroll one screen back into the scrollback. Works without the lease.
Shift+PageDown: Scroll one screen forward. Works without the lease.
Wheel: Scroll three lines per notch. While the child reads the mouse and this editor holds the lease, the wheel goes to the child instead.
Drag: Select text. A double-click selects a word, a triple-click a line; a click that does not move clears the selection. While the child reads the mouse and this editor holds the lease, presses, moves and releases go to the child instead.
Ctrl+Click link: Show the hyperlink the runner attached to the cell in the status line. Nothing is opened.
Alt+key macOS Left Option+key: Sent with Alt held, a terminal's Meta. On macOS the left Option sends the key's unmodified character with Alt.
AltGr+key macOS Right Option+key: Types the character the layout composes, without Alt: right Option+L types @ on a German layout.
Other keys: With the keyboard and the lease, sent to the child as the key and its modifiers; the runner encodes them for the terminal's modes (application cursor keys, modifyOtherKeys, bracketed paste). Input method compositions arrive as text. Without the lease they are dropped. On macOS no key held with Cmd reaches the child.

PALETTE COMMANDS

Entries as the editor's palette lists them. On this site Ctrl+Space opens the manual's own palette, which finds these entries too.

Session / Copy Session ID: Copy the session token, host:port/database as join takes it on another machine, to the clipboard; the status line shows it. Always listed. Without a store the status line says there is no session; the browser editor does nothing.
Graph / Auto Layout: Arrange the nodes of the focused pane's graph in columns by depth. Every editor sees the move. Always listed.
Pane / Split Horizontal: Put a new terminal beside the focused pane. Listed while the focused pane belongs to a runner whose workspace is attached.
Pane / Split Vertical: Put a new terminal below the focused pane. Listed while the focused pane belongs to a runner whose workspace is attached.
Pane / Close: Close the focused pane and kill its child; a job's terminal is only detached. A top-level graph the pane shows is deleted. Listed while the focused pane belongs to a runner whose workspace is attached.
Terminal / Attach <runner> / <title>: Show that terminal of the runner's in a new tab. One entry per terminal a connected runner owns and no pane shows (a job's), from that runner's last workspace snapshot. runner is the runner's section label, its host and the first eight hex digits of its fingerprint; title is the terminal's title, or terminal <id> when it has none.
Terminal / Close <runner> / <title>: Kill that terminal of the runner's and forget it. Listed next to each Terminal / Attach entry.
Runner / Hold <runner>: Start no new runs and let the live ones finish. The status line reports how many runs are still live. One entry per runner this editor is connected to.
Runner / Release <runner>: Start runs again. The status line reports how many runs are live. One entry per runner this editor is connected to.
Theme / <name>: Draw the editor, the graph and the terminals with this theme. The choice is remembered in <state-dir>/editor.toml. One entry per theme: the 22 bundled themes, iced's built-in themes paired with the WezTerm scheme of the same name, then every WezTerm scheme in <state-dir>/themes/*.toml by file stem, sorted by name. The browser editor lists the bundled ones only.
<Category> / <Name>: Add a node of that type to the focused pane's graph, at the point the middle of the window shows through that graph's camera. For example Output / Display. One entry per node type in the catalog, sorted by category, then by name. Each carries its type id as the description, so typing transform.display finds it. With no graph pane focused the status line says focus a graph pane to add nodes.