NE.Standard.UI.Graph

The canvas

The canvas

// On the controller: the effects further down address the canvas by its component id.
public const string CanvasId = "sheet";

// In the view
new NodesComponent(Controller.CanvasId)
    .SetCatalog(typeof(OperationNode), typeof(NumberNode), typeof(ResultNode))
    .SetCanvasHeight(34)
    .BindValue(nameof(Controller.Sheet))
    .OnSave(nameof(Controller.Save));

Value is the whole document — the nodes, the edges and the groups — bound two-way; SetCatalog sets a static catalogue at compile time, or BindCatalog binds a runtime UINodeCatalog on the controller so plugin node kinds can join or leave live. Nothing reaches the server until a save: Ctrl+S, or the menu's Save, commits the document and then raises graph-save (GraphEvents.Save), the canvas's own, so the command sees what the viewer built. A reload shows the saved sheet, and unsaved work is lost as it is in any editor. graph-save is raised by every commit — Ctrl+S, the menu's Save, an edit saved as it is made (AutoSave), the run panel's Run and Run all, a SaveDocumentEffect — and its key is the save's reason (UIGraphArguments.Reason), empty for the viewer's own. OnSave(command, arguments) names its arguments, and OnSaveLiteral(command, …) passes literal values — which document of several a save is for.

Every document carries a Key — what the application calls it: a build's id, a file's name. The canvas sends it back as it was given, so an application that puts one document after another on one canvas (a tab a document) knows which one a save was made on, even when the save arrives after the viewer moved on. WithKey(key) names it; every other With… keeps it.

The canvas itself: SetGridSize(step) for the grid behind it, SetSnapToGrid(false) to let go of the grid — it holds unless told otherwise, taking an added or moved node, a group's frame's size, and on the node canvas a node's size, to the grid's step as the pointer lets go; on the node canvas a node let go within half a step of where one of its wires runs straight stands there instead, so a straight wire can always be set again by hand — SetZoomRange(min, max) for how far it zooms out and in, and SetEdgeShape(...) for how an edge is drawn — stepped unless told otherwise, curved or straight on request. A stepped edge turns half way along its own run, and edges whose uprights would meet turn in lanes around that place instead of on one line, standing in the order that crosses least — so moving a node moves only the turns near it. On the node canvas, Arrange lays the sheet out as a layered graph is laid out, from left to right, lining up each wire's two pins so it runs straight, and leaves a gap after each column as wide as the lanes of the edges leaving it need; a layered graph keeps its own gaps. The canvas keeps each viewer's pan and zoom in the browser, under the component's id; a viewer it has kept none for, or whose kept view shows none of the sheet, sees the sheet whole, fitted as Arrange leaves it. A fit the viewer has not panned, zoomed or centred since is fitted again whenever the canvas takes another size — a window widened, a phone turned, a page opened on a phone after a visit on a desktop — while a view they moved stays where they left it. Fit leaves 48 px around the sheet, a twelfth of the width on a narrower canvas, and keeps the sheet clear of the canvas's own chrome along its top — the corner menu's panel, open or folded, a folded side panel, the node canvas's run line and run panel — beside a corner's box or under it, whichever leaves the larger zoom. On a layered graph a card sets the edges of one side apart along it, in the order their other ends lie, so each edge leaves and enters at a point of its own and keeps a lane of its own; a circle's edges meet at its middle — under its name where the layers run up or down, so no edge crosses the name — and edges that share a point share its lane, a fork reading as a fork. An edge's caption stands half way along it, or near there clear of the nodes and of the captions placed before it; two short edges side by side set their captions side by side.

SetCanvasHeight(rem) is the least height the canvas stands at, and a canvas given a height of its own — SetHeight(Fill) in a page's row — grows past it. A container's star row shrinks to what the page has left and does not hold its child's floor, so a canvas in one gives the row the same floor — UIGridUnit.Star(min: 24 * 16) beside SetCanvasHeight(24) — or on a short screen the canvas runs over the rows under it; with the floor, the page scrolls instead.

What the viewer can do

Pan and zoom with the wheel — by how far it turns, so a trackpad and a mouse zoom alike — and a drag on the background; on a touch screen two fingers pinch the sheet, zooming around their midpoint and panning with it, within the wheel's zoom range, and the finger left down pans on; double-click the background for the picker; drag from a pin to wire, and pull an edge off an input to move or drop it — a new wire let go on the empty sheet opens the picker there, and the kind chosen takes the wire into its first input that accepts it, or stands unwired if none does; the picker's categories nest by their paths and fold behind a chevron until one is chosen, and one chosen shows what stands under it too; double-click an edge to add a reroute point; click, Ctrl+click or Ctrl+drag a band to choose; Delete removes; Ctrl+C and Ctrl+V copy and paste with the inner connections on the node canvas, and Ctrl+D duplicates what is chosen (EditStructure on a layered or production canvas, resources only on the latter) — a step off, chosen, the clipboard left as it was; Ctrl+Z and Ctrl+Y undo and redo, across saves, until the server sends another sheet; Ctrl+A chooses everything; right-click opens a menu for what it lands on. A node's fold and pin marks answer Enter and Space as they answer a press. The sheet's keys act from the sheet and from the canvas's own buttons — the zoom bar, the run panel, the corner menu's and the side panels' switches, the log's strip — so Fit then Delete still deletes; a key pressed on what a panel holds — a field, a parameter's or a log line's node name, a corner menu's entry — is the panel's, and a press on such a name keeps the keyboard on it; Ctrl+S saves from anywhere in the canvas. A key a field keeps — typing, its caret, its own Ctrl+C, Ctrl+V, Ctrl+A and Ctrl+Z — is the field's, never the sheet's. Enter or Escape in a node's field leaves the field and the sheet takes the keyboard back; in a side panel's field, the panel takes it. Escape on the sheet lets go of what is chosen; in a dialog or a drawer, it is the next Escape that closes them. The picker's categories are one Tab stop walked by the arrows as a tree's, Tab goes round the picker and never out of it, a press on an entry or on the list's or the rail's empty room leaves the typing in the search, and closing it gives the keyboard back to what opened it, or to the sheet. Its first entry stands current, and wears the keyboard's frame once typing or an arrow puts it there, not on opening. On a phone the categories fold into one row over the list naming the chosen one, which a tap unfolds, so the entries keep the whole width. The words a pin, a card or a craft says under the pointer wait as a hover does.

Read-only (SetIsReadOnly(true), or bound), the viewer still pans, zooms, fits, chooses, copies, reads the map and the log and runs the sheet — nothing that changes it: no drag, wire, fold, pin, paste, duplicate, Delete, undo or redo, and no menu entry that would; an edit that reaches the sheet some other way (a drop under way as it turns read-only) is put back. Its root wears the family's mark, ui-readonly, which a stylesheet keys on; a node's fold and pin marks stay drawn, disabled the framework's way and still focusable. What the canvas would refuse does not promise it either: a pin under the pointer offers no wire, and a node, a frame or a reroute that will not move shows no move cursor — a pinned one neither, on any canvas. Disabled (SetEnabled(false)) or loading, the canvas keeps its tooltip and answers nothing else; the picker, if it was open, closes, as it does when the canvas turns read-only.

A node is dragged wider and taller by its bottom-right corner — every kind's, unless it says Resizable = false; the kind's MinWidth is the floor for one and the contents' own height for the other. A picture drawn large, a display and a multi-line text take the height the node is dragged to; a text's field has no handle of its own. Folded, a node is its head alone: as wide as the head's own words, the size it was dragged to kept for when it opens again. While the grid holds, a node's far corner lands on it as its near one does — dragged there, or simply as wide and tall as its contents came to; folded, its width does and its height stays the head's own, so the title keeps the middle — and on a layered or a production graph it is a node's middle the grid takes, so a chain of nodes of different heights stays one straight line. The canvas draws no ring when it takes the keyboard unless ShowFocusRing asks for it, since it takes the keyboard on every press.

The menus are each the framework's own MenuComponent: the canvas's fixed entries first, and an application's under them, a rule between. Menu, in a folding panel over the canvas's leading corner — the plan's panel, mirrored — carries what is done to the sheet as a whole — Arrange, Fit to content, Save — and AddMenuEntries appends to it; adding to the sheet is the right button's. The panel's switch is the menu's glyph, the sheet's name — SetSheetName or BindSheetName, translated as a title is — else the package's word for the menu, and a chevron; it stays open as entries run, until the viewer folds it to its switch, and starts folded on a phone. The canvas keeps the viewer's fold in the browser, as it keeps the plan's. ShowMenuPanel(false) leaves the panel out. CanvasMenu, the right button's on the empty surface, carries what edits the sheet — Add node, Add group (and on the node canvas Add reroute), Group selection, Duplicate selection, Delete selection, Arrange, Fit to content — and AddContextMenuEntries appends to it; an entry that would act on nothing chosen, or on a read-only canvas, is disabled — in a menu already open, too, the moment the canvas turns read-only. Add group puts an empty, unnamed frame with its corner where the menu was opened, on the grid, and chooses it; Group selection frames the chosen nodes. A frame holds whatever stands wholly inside it: dragging its band carries those items, and nothing else ties them to it. A frame is dragged wider and taller by its bottom-right corner, as a node is, pinned or not: never shorter than its band with a grid step under it, nor narrower than a folded node; sizing it moves nothing, so it simply holds whatever its new edges take in. NodeMenu and GroupMenu, the right button's on a node and on a group's band, pin it, rename it over its title (emptied, the name is its kind's again) and paint it one of ColorChoices — the theme's series by default, SetColorChoices for an application's own — and take an application's entries through AddNodeMenuEntries and AddGroupMenuEntries. A node's menu leads with what is done to the node: Duplicate (Ctrl+D), a copy of it and of every other chosen node a step off, an edge between two copies copied and one to a node left behind not; Disconnect all, every edge of those nodes taken out; on the node canvas Disabled and Reset values (A node turned off on the node canvas's page), and Reset on a kind that keeps a state. The colour stands under a rule after them, an application's entries under another, and Delete last under a rule of its own: it takes the node and whatever else is chosen, as the Delete key does, where the graph lets a node go. On the node canvas a group's menu has Disabled over its colour, for the nodes inside its frame. EdgeMenu, the right button's on an edge, takes an application's entries through AddEdgeMenuEntries on every canvas (the node canvas puts Add reroute first). The node canvas's pins have a menu of their own over the node's — its parameters and a reset of the pin, The sheet's parameters on the node canvas's page. A right press on something not chosen chooses it, and pin, colour, duplicate, disconnect and turning off act on every chosen item of that kind. Every built-in entry wears one of the framework's own glyphs (UIGlyphs), so a canvas needs no icon pack; SetCommandIcon replaces a command's glyph in every menu that has it. Every built-in entry is titled by one of UIGraphWords' keys, the default colour choices among them, whose English the web package carries (GraphStrings): an application translates them as it translates the framework's own words.

SetNodeActionBar() gives every node the framework's action bar: the node menu's entries marked InActionBar stand as icons in a bar above the node the reader pressed or tapped, centred on it, the rest behind its "…" — which opens under it as a menu button's list and holds the rest alone (a right-click or a long press opens the whole menu; SetNodeActionBarRepeatInMore(true) puts the whole menu behind the "…" too) — Pin, Rename and Delete are marked, the colour is not, and an application marks its own (new MenuItem { …, InActionBar = true } in AddNodeMenuEntries). The bar is a view of the menu: a press on an icon is the entry's press, and chooses the node as a right press does; the bar only showing chooses nothing. Never on hover: it shows on a press, and stays while that node is chosen — the node redrawn as the document changes keeps it — until a press elsewhere (the background, another node, the zoom buttons), Escape, or a drag of the node, after which it shows over the node where it was dropped. From the keyboard, the focus in a node's own part (a field, a mark) shows it; the canvas has no keyboard cursor over its nodes. It floats 10 px above the node's edge — clear of a chosen node's glow — at its size on screen whatever the zoom, follows a pan and a zoom, stands under a node the canvas leaves no room above, and hides while the node is out of the canvas's sight. A read-only or disabled canvas shows none (its menu still opens), and none appears in the middle of a drag. On a touch screen a tap on a node shows the bar, and a long press opens its menu with the bar's icons in a row atop it. A pin, a group's band and an edge have their menus alone.

An application's entries, in whichever menu, are heard through one event: OnMenuEntry(command), whose command takes the clicked entry's id — or, named, UIGraphArguments.Entry, TargetKind and Target: which entry, the kind of thing the menu was opened on (UIGraphMenuTargets: the sheet, a node, a group, an edge) and that thing's id. A pick is raised on the entry itself, as its menu's own event: the server runs the command only for an entry that menu holds, enabled and shown, and the kind of thing it was opened on is the menu's own. The canvas's own entries are done in the browser and raise nothing — but they stand in the same menus, so a forged pick may name one of their keys: a command acts on the keys it knows and ignores the rest, as the demo's MenuEntry does. A node's click is OnNodeClick(command), whose command takes the node's id. Each also takes named arguments (OnMenuEntry(command, arguments), OnNodeClick(command, arguments)) and literal ones in place of the entry's or the node's (OnMenuEntryLiteral, OnNodeClickLiteral), for a command that needs neither.