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.