Using Pikchr Studio

The canvas

The diagram fills the window. Around it float a few controls. At the top left, the Menu button () opens the menu, then the document name (click it to rename), the Source button () for the source drawer and the Export button (). The tool palette sits at the top centre (at the bottom on phones), the status chip at the top right shows whether the diagram rendered, and undo and redo (bottom left) and zoom (bottom right) sit in the corners. Click the status chip to review queued changes when there are any. Select an object and a toolbar floats above it; its More button () opens the inspector with size, style, connector and label options.

Documents and the menu

The menu has four parts. Document: New, Open file…, Examples…, and your saved documents, most recent first. Preferences: Theme (System follows your device; Light or Dark keeps that look on every page of the site), Show anchors, Apply accepted changes immediately and Snap resize to 0.1 in. Advanced, collapsed until you open it: Components…, Back up documents… and Restore…. Below those are links to this page, the shortcut list, licences and the source code.

Documents save automatically in this browser. A new document is named after its first label until you rename it: click the name in the chip (or press Enter on it), type a name and press Enter; Esc cancels, and an empty name goes back to the automatic one. A name you chose is never replaced. The trash button on a saved document asks before deleting it; deleting removes that document, its undo history and its queued changes from this browser only, and cannot be undone. Backups you downloaded are not affected, and other documents are untouched.

Export

The Export button offers two groups. Copy: Share link, Pikchr source and SVG. Download: SVG, PNG and Source (.pikchr). Each action confirms with a message such as “Downloaded diagram.svg”. Selection only crops SVG and PNG to the selected objects; Source always exports the whole document, so Copy Pikchr source and Download Source are unavailable while Selection only is on. While the source has a syntax error, SVG and PNG export are unavailable until you fix it; Source can still be copied or downloaded.

The source text is the document. Every gesture becomes a small Pikchr edit that is rendered before it is applied, so the canvas never shows geometry the source cannot reproduce. Open the source drawer to read or type Pikchr; the diagram re-renders as you type.

Tools and shortcuts

Press ? for the same list in the app. Escape cancels a gesture and returns to Select; with nothing in progress it clears the selection.

Tools
V M HSelect, area, pan
B C D R TBox, circle, cylinder, diamond, text
A LArrow, line (drag to draw)
Editing
EnterAccept a preview or apply queued changes; otherwise edit text
Double-clickEdit text (Shift+Enter new line)
⌘D DelDuplicate, delete
⌘A Shift-dragSelect all, select area
Arrow keysNudge 0.1 in (Shift 1 in, Alt 0.01 in)
[ ] EscCycle, discard a preview (queued changes stay)
⌘Z ⇧⌘ZUndo, redo
View
+ − 0 FZoom in, out, fit, focus selection
Space-dragPan over shapes
⌘-scroll or pinchZoom at pointer
/Find object
S ?Source drawer, this panel

Select

Use the Find object button beside Fit (or /) to search by name, label, type or connector endpoints. Combine words such as Beta box to narrow the list. Choosing a row opens that object's properties; technical geometry, dependencies and source positions are under Advanced & source. On phones the inspector is a scrollable sheet with a fixed heading and Close button.

Click a shape to select it; Shift-click adds to the selection. Drag on empty canvas to draw a selection box: every shape and connector fully inside is selected. A shape that encloses other shapes, such as a frame, is selected by its border, so clicks inside it reach the shapes within.

Move and align

Drag a shape. While you drag, the diagram re-renders with the edit that will be applied, and the shape snaps to other shapes' edges and centres, to the mirror position of a sibling about a third shape, and to equal gaps along a row; red guides show what it snapped to. Hold Shift to lock the move to horizontal, vertical or 45°. On release the top-ranked edit applies immediately: Studio keeps the placement you wrote, with new numbers: at A + (2,0) stays an offset from A, 1in below A stays a gap while you drag straight down, and an unplaced shape in a chain extends the arrow it hangs from. Shapes placed against the moved one (B at A + (2,0)) move with it, unchanged; shapes that only follow it in a chain stay where they are and are given a placement there. Hold Alt to swap the two. The status line names what moved along. Undo reverts it. Shapes from a macro or inside a [ ] group can’t be dragged; the drag shows why before you let go.

With several shapes selected, Arrange in › Group aligns or distributes them as one undoable change; Arrow keys nudge every selected shape by 0.1 inch, Shift by 1 inch, Alt by 0.01 inch. To select more than one without a keyboard, turn on Select multiple in the tool palette (shown on touch screens), then tap shapes to add or remove them; the selected count appears beside the toolbar. Escape or a tap on empty canvas ends both the selection and multiple-select mode.

Style… in the same Group section edits stroke colour, line thickness and — when every selected object is a shape — fill across the whole selection as one source change, and Undo reverses all of it at once. A selection mixing shapes and connectors keeps stroke and thickness but offers no fill. If any selected object is inside a group or macro, or its style is written as an expression, nothing is changed: the editor names each object it cannot style and leaves the source untouched.

Resize

A selected shape has four corner handles and a grab strip along each edge. The side or corner opposite the handle stays fixed; Shift keeps the aspect ratio and Alt resizes from the centre. Moving edges snap to other shapes, otherwise to a 0.05 inch grid. A shape attached to another (for example with .n at API.s) keeps that attachment and grows around it.

Connect

Hover a shape to show its four attach dots. Drag from a dot to another shape to connect them; a dashed guide shows the route and a badge names the connection. Dropping on empty canvas creates a new connected shape there. With the Arrow or Line tool, drag anywhere to draw a free line: each end attaches to a shape if it lands on one and stays a point otherwise. Shift locks the line to straight or 45°.

Text and labels

With the Text tool, click the canvas and type; Shift+Enter starts a new line and Enter finishes. Double-click any text, shape or connector label to edit it in place; the editor follows the canvas as you pan and zoom, and quotes and backslashes are written with Pikchr's escapes. Labels from a macro or inside a [ ] group say why they can only be edited in source. When text is selected, and while you edit a label in place, a style bar offers size, bold, italic, monospace (Pikchr's only font choice), alignment and colour; styling mid-edit keeps what you typed. The same text controls sit under Label in the inspector. Pikchr's color draws a shape's outline and its label together, so for shapes the bar's colours and Style's Line & text row are the same setting. A style value written as an expression or variable, such as fill $c, disables just that control and names what is written, with Show in source to reach it; a shape whose position is an expression can still be restyled and relabelled, and the inspector says why it cannot be moved. For label sizing, choose Text fit in : Grow shape fits the shape to its text, Wrap wraps the text inside the box's width, and Fixed keeps the size. Labels typed on the canvas follow the shape's Text fit. Unless you choose one, a box wraps and other shapes grow, so a label never overflows; a shape whose position cannot keep its anchor while it changes size keeps its size, and the status says why. Size (in) applies a typed width and height when you press Enter or leave the fields; Escape restores the current size, and a size Pikchr cannot draw is explained under the fields.

Routes and arrowheads

The connector inspector shows each end as source, such as Client.e, with Reconnect, then Reverse direction, Heads (None, End, Start, Both) and the visual Straight, Elbow, Curve, Arc and Waypoints choices. Elbow offers horizontal-first and vertical-first paths. For a spline, Segments keeps its bends while replacing the curve with straight edges. A shortcut explains when the source cannot be safely rewritten; it does not unlock protected objects. Undo restores the exact previous source.

Select any arrow, line, spline or arc and choose Route in its floating toolbar to jump straight to Suggested routes. They are also in , collapsed with a count. Each thumbnail is a complete Pikchr program that has already been rendered: Curve turns an elbowed route into a spline through the same waypoints, Arc swaps a two-point connector for arc cw or arc ccw, and Rounded corners adds rad 0.1. Arrowheads are not thumbnails: Heads switches between ->, <-, <-> and none; removing an arrow's heads changes its type to line, because Pikchr has no property that clears an arrow's default head. Stroke, weight, colour and the connector's label placement are under Style.

Shape-aware styles read the diagram. Tie bends replaces a literal bend with until even with a shape it already lines up with, so the bend follows that shape later. Route above, below, left and right detour around every shape in between. Back-edges arch over or under shapes on one row, and a connector whose ends are on the same shape gets loops. Choosing a thumbnail previews it; Enter or Accept applies it, Escape keeps the original, and [ ] cycle. Styles that would move any other object are not offered. Tidy route proposes an orthogonal path around obstacles.

Delete

Delete or Backspace removes the selection and its connectors. A shape positioned relative to a deleted one is pinned where it is, so nothing else moves; the change says which shapes were pinned.

Queue mode

Changes apply immediately by default. To review edits before they apply, turn off Apply accepted changes immediately in the menu under Preferences: accepted edits then join a draft, the status chip shows how many are queued, and clicking it opens Apply all, Discard all, Undo last and the diff. Enter on the canvas applies the queue; Escape leaves it queued. Undo after Discard all puts the discarded changes back. While changes are queued the source is read-only.

Advanced tools

Reusable components and document backup and restore are under Advanced in the menu (). The section is collapsed by default; open it to use Components…, Back up documents… or Restore…. Saved documents are always listed under Document.

Supported scope

Macros, nested objects, complex expressions, and unsupported placements can be inspected but not freely manipulated; Studio explains why an operation is unavailable. Your Pikchr remains the canonical document. If the source fails to render, the error appears on the canvas, the last valid diagram of that document stays visible but dimmed (an empty canvas if it never rendered), and it cannot be manipulated until the source renders again. The renderer accepts source up to 100000 UTF-8 bytes and rejects NUL characters.

Run locally

From the studio directory, run npm run build with a C compiler and Emscripten installed. Then run npm start and open http://127.0.0.1:8790. Use npm test for the unit, native and browser suites.

For integrating the renderer into another page, see the developer API contract and embedding example.