🎉 JointJS has new documentation! ðŸ¥³

JointJS+ FreeTransform

ui.FreeTransform

FreeTransform plugin creates a control panel above an element giving a user the ability to resize an element in any direction or rotate it.

Installation

Include joint.ui.freetransform.css, joint.ui.freetransform.js and joint.dia.freetransform.js files to your HTML:

<link rel="stylesheet" type="text/css" href="joint.ui.freeTransform.css">
<script src="joint.dia.freeTransform.js"></script>
<script src="joint.ui.freeTransform.js"></script>

Usage

The usage of the ui.FreeTransform plugin is pretty straightforward. Just instantiate an object of the joint.ui.FreeTransform type and pass in the view for the element you want to have the free transform handles hooked onto:

const graph = new joint.dia.Graph({}, { cellNamespace: joint.shapes });
const paper = new joint.dia.Paper({
    el: document.getElementById('paper'),
    width: 500,
    height: 500,
    model: graph,
    cellViewNamespace: joint.shapes
});

paper.on('element:pointerup', (elementView) => {
    const freeTransform = new joint.ui.FreeTransform({ cellView: elementView });
    freeTransform.render();
});

Configuration

The joint.ui.FreeTransform constructor accepts the following options:

cellView The view for the element you want the free transform handles to be displayed for.
preserveAspectRatio Set to true if you want the resizing to preserve the aspect ratio of the element. The default is false.
resizeGrid Set to { width: number, height: number } if you want the resizing to snap to grid by specified dimensions. The default is undefined.
allowRotation Set to false if you want the rotating handle to be omitted from the handles. The default is true.
minWidth The minimum width allowed for the element when resizing. The default is 0. It can be a number or a function returning a number (cell) => number;.
maxWidth The maximum width allowed for the element when resizing. The default is Infinity. It can be a number or a function returning a number (cell) => number;.
minHeight The minimum height allowed for the element when resizing. The default is 0. It can be a number or a function returning a number (cell) => number;.
maxHeight The maximum height allowed for the element when resizing. The default is Infinity. It can be a number or a function returning a number (cell) => number;.
rotateAngleGrid The steps in angle when rotating the element. The default is 15.
allowOrthogonalResize Set to false if you only want the four corner handles to be displayed. The default is true.
resizeDirections The list of the resize handles to be displayed referenced by their direction. It defaults to ['top', 'bottom', 'left', 'right', 'top-left', 'top-right', 'bottom-left', 'bottom-right'] i.e. all resize handles are displayed.
clearAll If set to true (the default value), clear all the existing freeTransforms from the page when a new freeTransform is created. This is the most common behavior as it is assumed that there is only one freeTransform visible on the page at a time. However, some applications might need to have more than one freeTransform visible. In this case, set clearAll to false (and make sure to call remove() once you don't need a freeTransform anymore)
clearOnBlankPointerdown If set to true (the default value), clear the freeTransform when a user clicks the blank area of the paper.
usePaperScale If set to true, the freeTransform frame and its handles scale with the paper.
padding The gap between the element and the freeTransform frame. It defaults to 3px.

API

The joint.ui.FreeTransform objects provide the following methods:

render() Render the free transform widget. You should call this right after you instantiate the free transform object.
remove() Remove the free transform widget.
joint.ui.FreeTransform.clear(paper) Clear all the free transform widgets from a JointJS paper.

Events

The plugin fires the following events.

Event Name Handler Signature Description
resize:start (evt: dia.Event) Triggered when the user starts resizing the element.
resize (evt: dia.Event) Triggered while the element is being resized.
resize:stop (evt: dia.Event) Triggered when the user finishes resizing the element.
rotate:start (evt: dia.Event) Triggered when the user starts rotating the element.
rotate (evt: dia.Event) Triggered while the element is being rotated.
rotate:stop (evt: dia.Event) Triggered when the user finishes rotating the element.