Quick start
In the editor of A first chart, which selects the chart it
inserts, add resizable: true to Diagrams.configure() for resize handles. Then:
// Half the width of the editor's text, at 4:3, stored in the document
editor.commands.setDiagramSize({ size: { width: 0.5, ratio: 4 / 3, locked: true } })
// 150 % in this editor only
editor.storage.diagrams.setZoom({}, 1.5)What is stored and what is not
The document stores the size and the alignment, so collaborators share them and a reload keeps them. Zoom, pan and maximize belong to one editor: not shared, and reset by a reload.
Narrow screens
On phones, the chart.minRenderWidth option, in pixels, lays a chart
out at least that wide and scales it down to fit, to no less than 60 %. In a narrower column, the
chart is laid out narrower and leaves out labels that would overlap. A maximized chart ignores the
option:
Diagrams.configure({ chart: { minRenderWidth: 560 } })Compare a narrow chart with and without the option:
View functions
The view functions on editor.storage.diagrams take a target: { pos }, or {} for the
selected chart or diagram. They need an editor with a view. In an editor without one, such as a
headless editor, set functions return false and get functions null.
| Function | What it does |
|---|---|
setZoom(target, zoom) | Sets the zoom, a number or 'fit' |
getZoom(target?) | Returns the zoom, or null |
setPan(target, { x, y }) | Moves the zoomed picture. Returns false for a value that is not finite |
getPan(target?) | Returns { x, y }, or null |
setMaximized(target, maximized) | Lays the chart or diagram over the window, or puts it back |
getMaximized() | Returns the position of the maximized chart or diagram, or null |
getShownSize(target?) | Returns the size on screen as a FigureSize, or null |
Zoom
setZoom scales a chart or a diagram inside its frame:
editor.storage.diagrams.setZoom({ pos }, 1.5) // 150 % of the unzoomed size
editor.storage.diagrams.setZoom({}, 'fit') // the selected chart, back to the unzoomed size'fit' is the unzoomed size, at which a chart fills its own width. A number is a factor of it,
from 0.25 to 4, clamped outside that range. A zoom of 1 is reported as 'fit'.
Zoomed in, the chart keeps its height, and the user scrolls inside it. Zoomed out, it takes less
room. Every Renderer works with zoom. The root element carries the zoom, such as 1.5 or fit, as
data-tt-chart-zoom or data-tt-flow-diagram-zoom.
Pan
Pan moves a zoomed-in chart or diagram inside its frame:
editor.storage.diagrams.setZoom({ pos }, 2)
editor.storage.diagrams.setPan({ pos }, { x: 120, y: 40 })x and y are how many pixels of the zoomed picture are out of view at the left and the top.
Negative values count as 0, and 'fit' moves the picture back to 0, 0.
The user pans by dragging. A press that moves less than 4px is a click, which selects the chart or diagram.
While dragged, the root element carries data-tt-chart-panning or data-tt-flow-diagram-panning.
Maximize
setMaximized lays a chart or a diagram over the window, and puts it back:
editor.storage.diagrams.setMaximized({ pos }, true) // over the window
editor.storage.diagrams.setMaximized({ pos }, false) // back into the textA maximized chart covers the window, at the distance --tt-chart-maximized-inset from its edges.
It is drawn again at the new size, and its zoom starts at 'fit'. Its root element carries
data-tt-chart-maximized, or data-tt-flow-diagram-maximized for a diagram.
Only one chart or diagram can be maximized. Maximizing another, pressing Escape in the editor, or deleting or moving the chart or diagram puts it back.
Each change dispatches a transaction that leaves the document as it is, so a toolbar can update its button:
editor.on('transaction', ({ transaction }) => {
const maximized = transaction.getMeta('diagramMaximized') // a position, null, or undefined
})Resize handles
With the resizable option, a selected chart or diagram in an editable
editor shows handles at the sides, at the bottom and at the two lower corners.
- A side handle changes the width. A centered chart grows on both sides, an aligned one on the handle's side.
- The bottom handle changes the height.
- A corner handle changes both, keeping the aspect ratio while
locked: true. Shift does the opposite.
Near the full width, a drag snaps to the text's edge, and a double click on a handle sets the full
width. When the drag ends, setDiagramSize writes the size as one undo step. A first resize starts
from the size on screen, with locked: true.
Commands
These commands write the size and the alignment.
setDiagramSize
Gives the selected chart or diagram, or the one at pos, a size.
editor.commands.setDiagramSize({ size: { width: 0.5, ratio: 4 / 3, locked: true } })| Option | Type | Default | Description |
|---|---|---|---|
size | FigureSize | null | Required | The size. null goes back to the full width and the natural aspect ratio |
pos | number | The selected one | The position of the chart or diagram |
A FigureSize has these fields. Values outside the range are clamped.
| Field | Type | Description |
|---|---|---|
width | number | Share of the editor's text width, 0.1 to 1 |
ratio | number | Width divided by height of the drawing area, 0.25 to 8 |
locked | boolean | Whether a corner handle keeps the ratio. Anything but true is false |
align | 'left' | 'center' | 'right' | Optional, see setDiagramAlign |
Where the size goes:
| Where | The size |
|---|---|
| A chart | Kept in its Chart Spec as size |
| A diagram | Kept in its options as size |
| An image export | A chart keeps the aspect ratio, 800 wide. A diagram is exported at the size of its drawing |
| Word | That share of the page width |
| HTML | style="width: …%" on the <figure>, none at width 1 |
width and ratio are required. Returns false without a chart or diagram, or when width or
ratio is missing or not a finite number, or ratio is not above 0.
setDiagramAlign
Aligns the selected chart or diagram, or the one at pos, to the 'left', the 'center' or the
'right' of the editor's text.
editor.commands.setDiagramAlign({ align: 'right' })| Option | Type | Default | Description |
|---|---|---|---|
align | 'left' | 'center' | 'right' | Required | The alignment |
pos | number | The selected one | The position of the chart or diagram |
Aligning a chart or diagram that has no size also stores the size it has on screen. At the full
width, the alignment is stored but shows only once the chart is made narrower. center is the
default. HTML carries the alignment as margins, Word as the paragraph's alignment.
Returns false without a chart or diagram, or for an unknown alignment. It also returns false for
one without a size in an editor without a view, because it reads the size from the screen.