Skip to main content

PathEditor

PathEditor allows users to edit <path> elements via an editing overlay.

Learn more about the PathEditor plugin.

constructor​

constructor(options: PathEditor.Options);

The ui.PathEditor constructor accepts several parameters:

pathElement​

[required] The path element to be edited. The path editor will be rendered on top of it.

anchorPointMarkup​

[optional] The SVG markup of anchor point overlay elements. The default is '<circle r="2.5"/>'. (CSS styling should use the .joint-path-editor .anchor-point CSS selector.)

controlPointMarkup​

[optional] The SVG markup of control point overlay elements. The default is '<circle r="2.5"/>'. (CSS styling should use the .joint-path-editor .control-point CSS selector.)

Methods​

render()​

pathEditor.render(): this;

Render the path editor overlay. Called automatically after object is instantiated.

remove()​

pathEditor.remove(): this;

Remove the path editor.

adjustAnchorPoint()​

pathEditor.adjustAnchorPoint(
    index: number,
    dx: number,
    dy: number,
    evt?: dia.Event,
    opt?: { dry?: boolean }
): void;

Adjust the position of an anchor point. Identified by index, the index of the anchor point within the 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()​

pathEditor.adjustControlPoint(
    index: number,
    controlPointIndex: number,
    dx: number,
    dy: number,
    evt?: dia.Event,
    opt?: { dry?: boolean }
): void;

Adjust the position of a control point. Identified by index, the index of the path segment it is attached to within the 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()​

pathEditor.adjustSegment(
    index: number,
    dx: number,
    dy: number,
    evt?: dia.Event,
    opt?: { dry?: boolean }
): void;

Adjust the position of a segment. Identified by its index within the path segment list (starting from 1 for the first non-moveto segment). The evt is the original user interaction event.

getControlPointLockedStates()​

pathEditor.getControlPointLockedStates(): boolean[][];

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()​

pathEditor.setControlPointLockedStates(lockedStates: boolean[][]): void;

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.

startMoving()​

pathEditor.stopMoving(evt: dia.Event): void;

Bound with 'mousedown'/'touchstart' events by default.

The selected anchor point / control point / segment path starts moving with the user pointer. Trigger a corresponding 'path:interact' event.

To start listening for the move() and stopMoving() methods, call delegateDocumentEvents().

The method is meant to be called in response to user interaction.

move()​

pathEditor.move(evt: dia.Event): void;

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.

The method is meant to be called in response to user interaction.

stopMoving()​

pathEditor.stopMoving(evt: dia.Event): void;

Bound with 'mouseup'/'touchend'/'touchcancel' events by default (after delegateDocumentEvents() is called).

The selected anchor point / control point / segment path stops moving with the user pointer. Trigger a corresponding 'path:edit' event.

To stop listening for the move() and stopMoving() methods, call undelegateDocumentEvents().

The method is meant to be called in response to user interaction.

createAnchorPoint()​

pathEditor.createAnchorPoint(evt: dia.Event): void;

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

The method is meant to be called in response to user interaction.

removeAnchorPoint()​

pathEditor.removeAnchorPoint(evt: dia.Event): void;

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.

The method is meant to be called in response to user interaction.

lockControlPoint()​

pathEditor.lockControlPoint(evt: dia.Event): void;

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!

The method is meant to be called in response to user interaction.

addClosePathSegment()​

pathEditor.addClosePathSegment(evt: dia.Event): void;

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.

The method is meant to be called in response to user interaction.

removeClosePathSegment()​

pathEditor.removeClosePathSegment(evt: dia.Event): void;

Not bound with any user interaction by default.

If event is targeted on a closepath segment, remove the segment from the path segment list.

The method is meant to be called in response to user interaction.

convertSegmentPath()​

pathEditor.convertSegmentPath(evt: dia.Event): void;

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

The method is meant to be called in response to user interaction.

Events​

clear​

Triggered when the path editor 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).

Types​

Options​

interface Options extends mvc.ViewOptions<undefined> {
    pathElement: SVGPathElement,
    anchorPointMarkup?: string,
    controlPointMarkup?: string
}

Stay in the know

Be where thousands of diagramming enthusiasts meet

Star us on GitHub