Size and view

Quick start

// 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 they are kept after a reload. Zoom, pan and maximize change only how one editor shows a chart or a diagram. They are not shared, and they are gone after a reload.

Narrow screens

On phones, the chart.minRenderWidth option draws a chart as wide as on a large screen and then scales it down. Compare a narrow chart with and without the option:

View functions

The view functions are on editor.storage.diagrams. Each takes a target, which is { pos? }. Without pos, a function acts on the selected chart or diagram.

These functions work only on a chart or a diagram that is on screen. For one that is not, the set functions return false and the get functions return null.

Zoom

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

The unzoomed size, 'fit', is the size at which a chart fills its own width. A number is a factor of it, from 0.25 to 4. A number outside that range is clamped.

Zoomed in, the chart keeps its height, and you scroll inside it. Zoomed out, it takes less room. Every Renderer works with zoom, because the drawn chart is scaled, not drawn again. The chart's root element carries the zoom as data-tt-chart-zoom.

Pan

editor.storage.diagrams.setZoom({ pos }, 2)
editor.storage.diagrams.setPan({ pos }, { x: 120, y: 40 })

Pan moves a zoomed-in chart or diagram inside its frame.

• Dragging with the mouse button held down moves it. A click without movement selects it.
• setPan moves it from code. x and y are how many pixels of the zoomed chart or diagram are moved out of view at the left and at the top.
• 'fit' moves it back to 0, 0.
• While you drag, the root element carries data-tt-chart-panning or data-tt-flow-diagram-panning.

Maximize

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. The chart is drawn again at the new size, and its zoom starts at 'fit'. While maximized, its root element carries data-tt-chart-maximized.

Only one chart can be maximized. Maximizing another chart, pressing Escape in the editor, or deleting or moving the chart puts it back. Each change dispatches a transaction that does not change the document, so a toolbar that listens to transaction can update its button.

Resize handles

With the resizable option, a selected chart or diagram shows handles while the editor is editable. The handles sit at the left and right sides, at the bottom, and at the two lower corners.

• A side handle changes the width and keeps the height. A centered chart or diagram grows on both sides. One aligned left or right (see setDiagramAlign) grows only on the side of the handle.
• The bottom handle changes the height.
• A corner handle changes both. It keeps the aspect ratio while the size has locked: true. Holding Shift does the opposite.
• Near the full width, a drag snaps to the edge of the editor's text. A double click on a handle sets the full width.
• When the drag ends, setDiagramSize writes the size, as one undo step.

Commands

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 } })

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

Returns false when there is no chart or diagram, or when size is not a size.

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' })

• The alignment is stored in the size as align. center is the default and is not written.
• A chart or diagram without a size of its own gets the size it has on screen, getShownSize(), together with the alignment.
• At the full width, you see the alignment only once the chart or diagram is made narrower.
• HTML carries the alignment as margins. Word carries it as the alignment of the paragraph that holds the chart or diagram.

Returns false when there is no chart or diagram, or for an unknown alignment. It also returns false for a chart or diagram that has no size of its own and is not on screen, because the command reads the aspect ratio from the screen.