Size and view

A chart or a diagram takes the full width of the editor's text until you give it a size of its own. Until then, a chart has an aspect ratio of 16:9, and a diagram keeps the aspect ratio of its drawing, at most 640px high.
New tab

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:

New tab

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.

FunctionWhat 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 text

A 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 } })
OptionTypeDefaultDescription
sizeFigureSize | nullRequiredThe size. null goes back to the full width and the natural aspect ratio
posnumberThe selected oneThe position of the chart or diagram

A FigureSize has these fields. Values outside the range are clamped.

FieldTypeDescription
widthnumberShare of the editor's text width, 0.1 to 1
rationumberWidth divided by height of the drawing area, 0.25 to 8
lockedbooleanWhether a corner handle keeps the ratio. Anything but true is false
align'left' | 'center' | 'right'Optional, see setDiagramAlign

Where the size goes:

WhereThe size
A chartKept in its Chart Spec as size
A diagramKept in its options as size
An image exportA chart keeps the aspect ratio, 800 wide. A diagram is exported at the size of its drawing
WordThat share of the page width
HTMLstyle="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' })
OptionTypeDefaultDescription
align'left' | 'center' | 'right'RequiredThe alignment
posnumberThe selected oneThe 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.