🎉 JointJS has new documentation! ðŸ¥³

JointJS+ PathDrawer

ui.PathDrawer

Path drawer allows users to draw <path> elements.

Installation

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

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

Create a PathDrawer

First, we create a PathDrawer object:

new joint.ui.PathDrawer({
    target: document.getElementById('example-canvas'),
    pathAttributes: {
        'class': 'example-path'
    }
});
The constructor needs a target, a reference to an <svg> SVGSVGElement on the page, which will act as a drawing area. We can use one we created previously in the DOM, for example:

<svg id="example-canvas" width="800" height="800"></svg>

We can also use the .svg property of an existing Paper.

Configuration

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

target SVGSVGElement Required. The drawing area. Any paths drawn by the user are appended to this <svg> element. They are not removed when the PathDrawer is removed.
pathAttributes Object Optional. An object with CSS attributes of the new path. Default values are:
{
    'class': null,
    'fill': '#ffffff',
    'stroke': '#000000',
    'stroke-width': 1,
    'pointer-events': 'none'
}
If your pathAttributes object sets the 'class' attribute (e.g. to 'example-path'), you can access the path for further styling through the #example-canvas .example-path CSS selector.
startPointMarkup string Optional. The SVG markup of control point overlay elements. Default is '<circle r="5"/>'. (CSS styling should use the .joint-path-drawer .start-point CSS selector.)
snapRadius number Optional. If set to a number greater than zero, the endpoint of the current segment snaps to the x- and y-values of previously drawn segment endpoints. The number determines the distance for snapping.
enableCurves boolean Optional, true by default. If set to false, only straight paths can be drawn.

API

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

render() Renders the path drawer. Called automatically after object is instantiated.
remove() Removes the path drawer.

For more fine-tuned programmatic control, you can emulate user interaction with delegated or synthetic mouse events. For example, to start drawing a path immediately after a pathDrawer is initialized:

paper.on('blank.pointerdown', function(event) {
    var vCanvas = V('svg', {
        width: 400,
        height: 400
    }).appendTo(this.paper.el);

    var pathDrawer = this.pathDrawer = new joint.ui.PathDrawer({
        el: vCanvas.node
    };

    pathDrawer.onPointerDown(event);
}, this)

Interaction

Users can interact with joint.ui.PathDrawer objects by clicking/touching its canvas:

mousedown touchstart
.start-point Calls onStartPointPointerDown(event). Closes the path.
Calls onPointerDown(event). If this is the first click of a path, creates a new path with a new start point. Otherwise, finishes previous action and starts a new one. If the user does not release the mouse, triggers a bound mousemove/touchmove event and the option enableCurves is set to true, this function starts drawing a curveto control point until a mouseup/touchend event is registered. Otherwise, starts drawing a lineto path segment.
mousemove Calls onPointerMove(event). If the user is currently drawing a path segment, the path endpoint moves with user pointer.
dblclick Calls onDoubleClick(event). Stops path drawing at the location of the double click. The path is not finished with a closepath segment.
contextmenu Calls onContextMenu(event). Stops path drawing at the location of the previous anchor point. The path is not finished with a closepath segment.

Events

The joint.ui.PathDrawer object triggers various events that you can react on. Events can be handled by using the on() method.

clear Triggered when the pathDrawer is cleared.
path:create Triggered when a new path is created. The handler is passed a reference to the svgPath SVGPathElement.
path:finish Triggered when a path is finished in a valid manner. The handler is passed a reference to the svgPath SVGPathElement. The following specific events are triggered alongside this generic event:
path:close Triggered when a path is finished by being reconnected with the start point. The handler is passed a reference to the svgPath SVGPathElement.
path:stop Triggered when a path is finished by being stopped without reconnecting with the start point (e.g. due to a double click or a right click). The handler is passed a reference to the svgPath SVGPathElement.
path:abort Triggered when a path is finished in an invalid manner (e.g. closed with only one anchor point). The handler is passed a reference to the svgPath SVGPathElement.
path:segment:add Triggered when the user adds a new segment to path segment list. The handler is passed a reference to the svgPath SVGPathElement. The following specific events are triggered alongside this generic event:
path:move-segment:add Triggered when the user adds a moveto segment to path segment list. The handler is passed a reference to the svgPath SVGPathElement.
path:line-segment:add Triggered when the user adds a lineto segment to path segment list. The handler is passed a reference to the svgPath SVGPathElement.
path:curve-segment:add Triggered when the user adds a curveto segment to path segment list. The handler is passed a reference to the svgPath SVGPathElement.
path:edit Triggered when the user edits the path. The handler is passed a reference to the svgPath SVGPathElement. The following specific events are triggered alongside this generic event:
path:last-segment:adjust Triggered when the user adjusts last added segment. (This happens, for example, when the user specifies a control point after having added a curveto segment.) The handler is passed a reference to the svgPath SVGPathElement.
path:last-segment:replace-with-curve Triggered when the user replaces last added line segment with a curved segment. (This happens, for example, when the user begins to specify a control point after having added a lineto segment.) The handler is passed a reference to the svgPath SVGPathElement.
path:last-segment:remove Triggered when the user removes last added segment. (This happens, for example, when the user stops drawing with a right-click). The handler is passed a reference to the svgPath SVGPathElement.
path:interact Triggered when the user interacts with drawer overlay elements. The handler is passed a reference to the svgPath SVGPathElement. The following specific events are triggered alongside this generic event:
path:control:adjust Triggered when the user adjusts a control path. (This happens when the user specifies a control for a curveto segment.) The handler is passed a reference to the svgPath SVGPathElement.
path:control:remove Triggered when a control path is removed from the drawer interface. (This happens when the user is finished drawing a curve.) The handler is passed a reference to the svgPath SVGPathElement.