JointJS+ PathEditor

Path editor allows users to edit <path> elements via an editing overlay. Users can interact with the path's segments, anchor points and curve control points.

Installation

Include joint.ui.pathEditor.css and joint.ui.pathEditor.js files to your HTML.

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

Create a PathEditor

First, we create a PathEditor object. The constructor needs a reference to a <path> SVGPathElement on the page.

new joint.dia.PathEditor({
    pathElement: document.querySelector('path')
});

Configuration

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

pathElement	SVGPathElement	Required. The path element to be edited. The PathEditor will be rendered on top of it.
anchorPointMarkup	string	Optional. The SVG markup of anchor point overlay elements. Default is '<circle r="2.5"/>'. (CSS styling should use the .joint-path-editor .anchor-point CSS selector.)
controlPointMarkup	string	Optional. The SVG markup of control point overlay elements. Default is '<circle r="2.5"/>'. (CSS styling should use the .joint-path-editor .control-point CSS selector.)

API

The joint.ui.PathEditor object provides the following methods:

render()	Render the path editor overlay. Called automatically after object is instantiated.
remove()	Remove the path editor.
adjustAnchorPoint(index, dx, dy, evt [, opt])	Adjust the position of an anchor point. Identified by index, the index of the anchor point within path segment list (starting from 0 for the endpoint of the first moveto segment). The anchor point is translated by (dx,dy). The evt is the original user interaction event. The opt parameter is optional; it is used by internal methods. It can have one property: dry (indicating that corresponding 'path:editing' and 'path:edit' events will be suppressed).
adjustControlPoint(index, controlPointIndex, dx, dy, evt [, opt])	Adjust the position of a control point. Identified by index, the index of the path segment it is attached to within path segment list (starting from 1 for the first non-moveto segment), and controlPointIndex, the index of the control point within the segment (1 for the first control point - the one visually attached to the previous anchor point, or 2 for the second control point - the one visually attached to this segment's anchor point). The control point is translated by (dx,dy). The evt is the original user interaction event. The opt parameter is optional; it is used by internal methods. It can have one property: dry (indicating that corresponding 'path:editing'/'path:edit' events will be suppressed).
adjustSegment(index, dx, dy, evt)	Adjust the position of a segment. Identified by its index within path segment list (starting from 1 for the first non-moveto segment). The evt is the original user interaction event.
getControlPointLockedStates()	Return an array of arrays that records, for every control point (identified as [index][controlPointIndex]), whether it is currently locked with another point (true) or not (false). In tandem with setControlPointLockedStates(lockedStates), the function can be used to preserve locking information across multiple path editor sessions for a given element.
setControlPointLockedStates(lockedStates)	Change the locked status of the editor's control points, so they correspond to the information in the given lockedStates list (e.g. the output of the getControlPointLockedStates() function). A true value adds the 'locked' class to the control point element; a false value removes the class.

Interaction API

The following methods are meant to be called in response to user interaction events (e.g. click, touch, dblclick). Some of them are bound with user interactions by default (see the Interaction section), but others are not. Those may be called upon by delegated events from your application. For example:

pathEditor.delegate('contextmenu', '.segment-path', function(event) {
    event.stopPropagation();
    event.preventDefault();

    this.convertSegmentPath(event);
}.bind(pathEditor));

startMoving(event)	Bound with 'mousedown'/'touchstart' events by default. The selected anchor point / control point / segment path starts moving with user pointer. Trigger a corresponding 'path:interact' event. To start listening for the move() and stopMoving() methods, call delegateDocumentEvents().
move(event)	Bound with 'mousemove'/'touchmove' events by default (after delegateDocumentEvents() is called). The selected anchor point / control point / segment path moves with user pointer. Trigger corresponding 'path:editing' events.
stopMoving(event)	Bound with 'mouseup'/'touchend'/'touchcancel' events by default (after delegateDocumentEvents() is called). The selected anchor point / control point / segment path stops moving with user pointer. Trigger a corresponding 'path:edit' event. To stop listening for the move() and stopMoving() methods, call undelegateDocumentEvents().
createAnchorPoint(event)	Bound with 'dblclick .segment-path' event by default. If event is targeted on a segment path, create an anchor point at the location of the user click and insert it into the path segment list. Trigger the 'path:anchor-point:create' event. Note: Due to current limitations, the function does not work properly for closepath segments in paths that have 2 or more closepath segments (the anchor points are created at wrong position).
removeAnchorPoint(event)	Bound with 'dblclick .anchor-point' event by default. If event is targeted on an anchor point, remove it. Trigger the 'path:anchor-point:remove' event. If only one anchor point remains in the path after the removal, also trigger the 'path:invalid' event.
lockControlPoint(event)	Bound with 'dblclick .control-point' event by default. If event is targeted on a control point of a curveto segment, and the control point is immediately adjacent to a control point of another curveto segment, toggle its locked status. Trigger the corresponding 'path:control-point:lock'/'path:control-point:unlock' event. Note that the locking action necessarily causes a change in the path markup which does not trigger an 'path:edit' event!
addClosePathSegment(event)	Not bound with any user interaction by default. If event is targeted on the first or last anchor point, and the path segment list contains no closepath segment, append a closepath segment to the path segment list.
removeClosePathSegment(event)	Not bound with any user interaction by default. If event is targeted on a closepath segment, remove the segment from the path segment list.
convertSegmentPath(event)	Not bound with any user interaction by default. If event is targeted on a path segment, convert the segment from linear to curved or vice versa. A curveto segment is replaced by a lineto segment. A lineto/closepath segment is replaced by a curveto segment whose control points are coincident with anchor points; a replacement closepath segment is appended to the path segment list if the converted segment was a closepath segment. Note: Due to current limitations, the function does not work properly for closepath segments in paths that have 2 or more closepath segments (the anchor points are created at wrong position).

Interaction

Users can interact with joint.ui.PathEditor objects by clicking/touching editor overlay elements:

mousedown touchstart	.anchor-point Call onAnchorPointPointerDown(event), which calls startMoving() followed by delegateDocumentEvents() by default. .control-point Calls onControlPointPointerDown(event), which calls startMoving() followed by delegateDocumentEvents() by default. .segment-path Calls onSegmentPathPointerDown(event), which calls startMoving() followed by delegateDocumentEvents() by default.

Double-clicking editor overlay elements triggers additional actions:

dblclick	.anchor-point Calls onAnchorPointDoubleClick(event), which calls removeAnchorPoint() by default. .control-point Calls onControlPointDoubleClick(event), which calls lockControlPoint() by default. .segment-path Calls onSegmentPathDoubleClick(event), which calls createAnchorPoint() by default.

For the documentation of the called functions, see the Interaction API section.

Events

The joint.ui.PathEditor object triggers various events that you can react on:

clear	Triggered when the pathEditor is cleared.
path:interact	Triggered when the user interacts with (clicks/touches) the path. The following specific events are triggered alongside this generic event: path:anchor-point:select Triggered when the user interacts with an anchor point. The handler is passed the index of the segment that this anchor point is bound to in the path segment list. The first anchor point on the path has an index of 0. path:control-point:select Triggered when the user interacts with a control point. The handler is passed two values. The first value is the index of the segment that this control point is bound to in the path segment list. (Since the first moveto segment cannot have control points, the minimal index is 1.) The second value is the controlPointIndex of the control point. It can be either 1 or 2. path:segment:select Triggered when the user interacts with a path segment. The handler is passed the index of the segment in the path segment list. (Since the first moveto segment is not clickable, the minimal index is 1.) path:control-point:lock Triggered when the user successfully locks a control segment (binds it with a control point in an adjacent curveto path). The handler is passed two values. The first value is the index of the segment that this control point is bound to in the path segment list. (Since the first moveto segment cannot have control points, the minimal index is 1.) The second value is the controlPointIndex of the control point. It can be either 1 or 2. path:control-point:unlock Triggered when the user unlocks a control segment (stops its binding with a control point in an adjacent curveto path). The handler is passed two values. The first value is the index of the segment that this control point is bound to in the path segment list. (Since the first moveto segment cannot have control points, the minimal index is 1.) The second value is the controlPointIndex of the control point. It can be either 1 or 2.
path:editing	Triggered while the user is editing the path. The handler is passed a reference to the updated svgPath SVGPathElement, and evt (the user interaction event). The following specific events are triggered alongside this generic event: path:anchor-point:adjusting Triggered while the user is adjusting the position of an anchor point. The handler is passed a reference to the updated svgPath SVGPathElement, evt (the user interaction event), and an opt object with two properties: index (the index of the adjusted anchor point), and segPoint (the new position of the anchor point). path:control-point:adjusting Triggered while the user is adjusting the position of a control point. The handler is passed a reference to the updated svgPath SVGPathElement, evt (the user interaction event), and an opt object with three properties: index (the index of the associated anchor point), controlPointIndex (the index of the adjusted control point), and segPoint (the new position of the anchor point). path:segment:adjusting Triggered while the user is adjusting the position of a segment. The handler is passed a reference to the updated svgPath SVGPathElement, evt (the user interaction event), and an opt object with one property: index (the index of the adjusted segment).
path:edit	Triggered when the user edits the path. The handler is passed a reference to the updated svgPath SVGPathElement, and evt (the user interaction event). The following specific events are triggered alongside this generic event: path:anchor-point:adjust Triggered when the user adjusts the position of an anchor point. The handler is passed a reference to the updated svgPath SVGPathElement, evt (the user interaction event), and an opt object with two properties: index (the index of the adjusted anchor point), and segPoint (the new position of the anchor point). path:control-point:adjust Triggered when the user adjusts the position of a control point. The handler is passed a reference to the updated svgPath SVGPathElement, evt (the user interaction event), and an opt object with three properties: index (the index of the associated anchor point), controlPointIndex (the index of the adjusted control point), and segPoint (the new position of the anchor point). path:segment:adjust Triggered when the user adjusts the position of a segment. The handler is passed a reference to the updated svgPath SVGPathElement, evt (the user interaction event), and an opt object with one property: index (the index of the adjusted segment). path:anchor-point:create Triggered when the user adds a new anchor point to the path. The handler is passed a reference to the updated svgPath SVGPathElement, and evt (the user interaction event). path:anchor-point:remove Triggered when the user removes an anchor point from the path. The handler is passed a reference to the updated svgPath SVGPathElement, and evt (the user interaction event). path:segment:convert Triggered when the user converts a lineto path segment into a curveto segment or vice versa. The handler is passed a reference to the updated svgPath SVGPathElement, and evt (the user interaction event). path:closepath-segment:add Triggered when the user adds a closepath segment to the path. The handler is passed a reference to the updated svgPath SVGPathElement, and evt (the user interaction event). path:closepath-segment:add Triggered when the user removes a closepath segment from the path. The handler is passed a reference to the updated svgPath SVGPathElement, and evt (the user interaction event).
path:invalid	Triggered when user modifications result in an invalid path (e.g. after removing, a path that has only one anchor point). The handler is passed a reference to the svgPath SVGPathElement, and evt (the user interaction event).

You can react to these events by using the on() method:

pathEditor.on({
    'path:control-point:select': console.log('started moving control point'),
    'path:control-point:adjusting': console.log('moving control point'),
    'path:control-point:adjust': console.log('stopped moving control point')
});

It is also possible to specify a custom context for the on() method. This is useful when you need to handle user interaction on your PathEditor from within another mvc object, for instance:

pathEditor.on({
    'path:edit': this.onPathEdit.bind(this),
}, this);