Creating Mouse Tools

This tutorial explains the different ways to create Paper.js tools that the user can interact with by using the mouse.

We start with an example of a very simple tool that creates an empty path on execution and adds segments to it whenever you click the mouse:

Paper.js offers mouse handlers for the different actions you can perform with a mouse. You can use these mouse handlers to produce different types of tools that have different ways of reacting to mouse interaction and movement.

To see when the different handler functions are called, copy-paste the following code into a new JavaScript file, execute it and interact with the Paper.js tool:

function onMouseDown(event) {
	console.log('You pressed the mouse!');
}

function onMouseDrag(event) {
	console.log('You dragged the mouse!');
}

function onMouseUp(event) {
	console.log('You released the mouse!');
}

The mouse handler functions receive an event object which contains information about the mouse event, such as the current position of the mouse (event.point), the position where the mouse was pressed (event.downPoint) etc.

Here is a simple tool that draws lines. The starting point of the line is where you click and the last point is where you release the mouse.

Click, drag and release below to try it out:

The same tool can be written more simply, by using only the onMouseUp(event) handler, and accessing the event.downPoint property:

Click, drag and release below to try it out:

When the mouse is released, the onMouseUp(event) handler is called.

In the onMouseUp handler we create a new path and give it a black stroke:

	var myPath = new Path();
	myPath.strokeColor = 'black';

Then we add two segments to it using the path.add(segment) function.

First, we add a segment at event.downPoint, which is the position where the mouse button was pressed:

	myPath.add(event.downPoint);

Then, we add a segment at event.point, which is the position where the mouse button was released:

	myPath.add(event.point);

As a next step, we are going to make a small drawing tool:

When you click the mouse it will make a new Path.
When you drag the mouse it will add segments to the path.
When you release the mouse it will add a circle shaped path at that position with a radius of 10.

Click and drag below to try it out:

Now lets go through the script line by line to see whats happening:

To be able to access the myPath variable from both mouse handlers we declare it outside of the onMouseDown and onMouseDrag handlers:

var myPath;

In the onMouseDown handler we create a new path and store it in the myPath variable:

function onMouseDown(event) {
	myPath = new Path();
}

In the onMouseDrag handler we add event.point (the position of the mouse) to myPath every time the user drags the mouse:

function onMouseDrag(event) {
	myPath.add(event.point);
	myPath.strokeColor = 'black';
}

In the onMouseUp handler we create a circle shaped path with its center point at the position of the mouse when it was released and a radius of 10.

function onMouseUp(event) {
	var myCircle = new Path.Circle({
		center: event.point,
		radius: 10
	});
	myCircle.strokeColor = 'black';
	myCircle.fillColor = 'white';
}

Another handy property in the event object is event.delta which describes the difference between the current position and the last position of the mouse when the event was fired. So in an onMouseUp handler, event.delta would describe the difference between the position where the mouse was clicked and the position where the mouse was released.

For example, if we would want to make a tool that creates circles through mouse interaction, we could write something like:

This small script creates a circular path whenever you click, drag and release. It uses the position where the mouse was clicked (event.downPoint) for the center point of the circle, and the distance between the down point and the position where the mouse was released (the length of event.delta) for its radius.

Normally while dragging, the onMouseDrag handler is called, no matter how far the mouse has dragged. We can set the minimum distance the mouse has to drag before firing the onMouseDrag event by setting the tool.minDistance property.

For example, in the following tool script the onMouseDrag function is only called when the mouse has moved more than 20 points.

So when you click and drag in the following example, you will see that the radius of the circles is always 20pt or higher.

We can also set the maximum distance until the firing of the next onMouseDrag event by setting the tool.maxDistance property. This will repeatedly fire the onMouseDrag event until the distance between the event point and the mouse is less than tool.maxDistance.

In the following code we set tool.maxDistance to be 10 pt. Therefore, if the user were to drag the mouse by 50 pt, it would call the onMouseDrag handler 5 times.

When you click and drag in the following example, you will see that when you drag fast enough the radiuses of the circles max out at 5pt. When you drag slower, the circles will be smaller.

To set both the minimum and maximum distances we can set the tool.fixedDistance property. Then onMouseDrag events are fired with intervals of fixed distances.

The following example creates circle shaped paths while you drag. By setting tool.fixedDistance to 30, the circles are created at strict 30pt intervals.

Click and drag below to try it out: