<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Tool</title>
<base target="class-frame">
<link href="../assets/css/docs.css" rel="stylesheet" type="text/css">
<script src="../assets/js/paper.js"></script>
<script src="../assets/js/jquery.js"></script>
<script src="../assets/js/codemirror.js"></script>
<script src="../assets/js/docs.js"></script>
</head>
<body class="reference">
<div class="reference-class">
<h1>Tool</h1>
<p>The Tool object refers to a script that the user can interact with
by using the mouse and keyboard and can be accessed through the global
<tt>tool</tt> variable. All its properties are also available in the paper
scope.</p>
<p>The global <tt>tool</tt> variable only exists in scripts that contain mouse
handler functions (<a href="../classes/Tool.html#onmousemove" onclick="return toggleMember('onmousemove', true);"><tt>onMouseMove</tt></a>, <a href="../classes/Tool.html#onmousedown" onclick="return toggleMember('onmousedown', true);"><tt>onMouseDown</tt></a>,
<a href="../classes/Tool.html#onmousedrag" onclick="return toggleMember('onmousedrag', true);"><tt>onMouseDrag</tt></a>, <a href="../classes/Tool.html#onmouseup" onclick="return toggleMember('onmouseup', true);"><tt>onMouseUp</tt></a>) or a keyboard handler
function (<a href="../classes/Tool.html#onkeydown" onclick="return toggleMember('onkeydown', true);"><tt>onKeyDown</tt></a>, <a href="../classes/Tool.html#onkeyup" onclick="return toggleMember('onkeyup', true);"><tt>onKeyUp</tt></a>).</p>
<p>
<b>Example</b>
</p>
<pre class="code">var path;
// Only execute onMouseDrag when the mouse
// has moved at least 10 points:
tool.distanceThreshold = 10;
function onMouseDown(event) {
// Create a new path every time the mouse is clicked
path = new Path();
path.add(event.point);
path.strokeColor = 'black';
}
function onMouseDrag(event) {
// Add a point to the path every time the mouse is dragged
path.add(event.point);
}</pre>
</div>
<div class="reference-members"><h2>Properties</h2>
<div id="mindistance" class="member">
<div class="member-link">
<a name="mindistance" href="#mindistance"><tt><b>minDistance</b></tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>The minimum distance the mouse has to drag before firing the onMouseDrag
event, since the last onMouseDrag event.</p>
<ul><b>Type:</b>
<li>
<tt>Number</tt>
</li>
</ul>
</div>
</div>
</div>
<div id="maxdistance" class="member">
<div class="member-link">
<a name="maxdistance" href="#maxdistance"><tt><b>maxDistance</b></tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>The maximum distance the mouse has to drag before firing the onMouseDrag
event, since the last onMouseDrag event.</p>
<ul><b>Type:</b>
<li>
<tt>Number</tt>
</li>
</ul>
</div>
</div>
</div>
<div id="fixeddistance" class="member">
<div class="member-link">
<a name="fixeddistance" href="#fixeddistance"><tt><b>fixedDistance</b></tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<ul><b>Type:</b>
<li>
<tt>Number</tt>
</li>
</ul>
</div>
</div>
</div>
<h3>Mouse Event Handlers</h3>
<div id="onmousedown" class="member">
<div class="member-link">
<a name="onmousedown" href="#onmousedown"><tt><b>onMouseDown</b></tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>The function to be called when the mouse button is pushed down. The
function receives a <a href="../classes/ToolEvent.html"><tt>ToolEvent</tt></a> object which contains information
about the mouse event.</p>
<ul><b>Type:</b>
<li>
<tt>Function</tt>
</li>
</ul>
<p>
<b>Example</b> — Creating circle shaped paths where the user presses the mouse button:
</p>
<div class="paperscript split">
<div class="buttons">
<div class="button run">Run</div>
</div>
<script type="text/paperscript" canvas="canvas-0">
function onMouseDown(event) {
// Create a new circle shaped path with a radius of 10
// at the position of the mouse (event.point):
var path = new Path.Circle({
center: event.point,
radius: 10,
fillColor: 'black'
});
}
</script>
<div class="canvas"><canvas width="516" height="100" id="canvas-0"></canvas></div>
</div>
</div>
</div>
</div>
<div id="onmousedrag" class="member">
<div class="member-link">
<a name="onmousedrag" href="#onmousedrag"><tt><b>onMouseDrag</b></tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>The function to be called when the mouse position changes while the mouse
is being dragged. The function receives a <a href="../classes/ToolEvent.html"><tt>ToolEvent</tt></a> object which
contains information about the mouse event.</p>
<ul><b>Type:</b>
<li>
<tt>Function</tt>
</li>
</ul>
<p>
<b>Example</b> — Draw a line by adding a segment to a path on every mouse drag event:
</p>
<div class="paperscript split">
<div class="buttons">
<div class="button run">Run</div>
</div>
<script type="text/paperscript" canvas="canvas-1">
// Create an empty path:
var path = new Path({
strokeColor: 'black'
});
function onMouseDrag(event) {
// Add a segment to the path at the position of the mouse:
path.add(event.point);
}
</script>
<div class="canvas"><canvas width="516" height="100" id="canvas-1"></canvas></div>
</div>
</div>
</div>
</div>
<div id="onmousemove" class="member">
<div class="member-link">
<a name="onmousemove" href="#onmousemove"><tt><b>onMouseMove</b></tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>The function to be called the mouse moves within the project view. The
function receives a <a href="../classes/ToolEvent.html"><tt>ToolEvent</tt></a> object which contains information
about the mouse event.</p>
<ul><b>Type:</b>
<li>
<tt>Function</tt>
</li>
</ul>
<p>
<b>Example</b> — Moving a path to the position of the mouse:
</p>
<div class="paperscript split">
<div class="buttons">
<div class="button run">Run</div>
</div>
<script type="text/paperscript" canvas="canvas-2">
// Create a circle shaped path with a radius of 10 at {x: 0, y: 0}:
var path = new Path.Circle({
center: [0, 0],
radius: 10,
fillColor: 'black'
});
function onMouseMove(event) {
// Whenever the user moves the mouse, move the path
// to that position:
path.position = event.point;
}
</script>
<div class="canvas"><canvas width="516" height="100" id="canvas-2"></canvas></div>
</div>
</div>
</div>
</div>
<div id="onmouseup" class="member">
<div class="member-link">
<a name="onmouseup" href="#onmouseup"><tt><b>onMouseUp</b></tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>The function to be called when the mouse button is released. The function
receives a <a href="../classes/ToolEvent.html"><tt>ToolEvent</tt></a> object which contains information about the
mouse event.</p>
<ul><b>Type:</b>
<li>
<tt>Function</tt>
</li>
</ul>
<p>
<b>Example</b> — Creating circle shaped paths where the user releases the mouse:
</p>
<div class="paperscript split">
<div class="buttons">
<div class="button run">Run</div>
</div>
<script type="text/paperscript" canvas="canvas-3">
function onMouseUp(event) {
// Create a new circle shaped path with a radius of 10
// at the position of the mouse (event.point):
var path = new Path.Circle({
center: event.point,
radius: 10,
fillColor: 'black'
});
}
</script>
<div class="canvas"><canvas width="516" height="100" id="canvas-3"></canvas></div>
</div>
</div>
</div>
</div>
<h3>Keyboard Event Handlers</h3>
<div id="onkeydown" class="member">
<div class="member-link">
<a name="onkeydown" href="#onkeydown"><tt><b>onKeyDown</b></tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>The function to be called when the user presses a key on the keyboard.</p>
<p>The function receives a <a href="../classes/KeyEvent.html"><tt>KeyEvent</tt></a> object which contains
information about the keyboard event.</p>
<p>If the function returns <tt>false</tt>, the keyboard event will be
prevented from bubbling up. This can be used for example to stop the
window from scrolling, when you need the user to interact with arrow
keys.</p>
<ul><b>Type:</b>
<li>
<tt>Function</tt>
</li>
</ul>
<p>
<b>Example</b> — Scaling a path whenever the user presses the space bar:
</p>
<div class="paperscript split">
<div class="buttons">
<div class="button run">Run</div>
</div>
<script type="text/paperscript" canvas="canvas-4">
// Create a circle shaped path:
var path = new Path.Circle({
center: new Point(50, 50),
radius: 30,
fillColor: 'red'
});
function onKeyDown(event) {
if (event.key == 'space') {
// Scale the path by 110%:
path.scale(1.1);
// Prevent the key event from bubbling
return false;
}
}
</script>
<div class="canvas"><canvas width="516" height="100" id="canvas-4"></canvas></div>
</div>
</div>
</div>
</div>
<div id="onkeyup" class="member">
<div class="member-link">
<a name="onkeyup" href="#onkeyup"><tt><b>onKeyUp</b></tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>The function to be called when the user releases a key on the keyboard.</p>
<p>The function receives a <a href="../classes/KeyEvent.html"><tt>KeyEvent</tt></a> object which contains
information about the keyboard event.</p>
<p>If the function returns <tt>false</tt>, the keyboard event will be
prevented from bubbling up. This can be used for example to stop the
window from scrolling, when you need the user to interact with arrow
keys.</p>
<ul><b>Type:</b>
<li>
<tt>Function</tt>
</li>
</ul>
<p>
<b>Example</b>
</p>
<pre class="code">function onKeyUp(event) {
if (event.key == 'space') {
console.log('The spacebar was released!');
}
}</pre>
</div>
</div>
</div>
</div>
<!-- ============================== methods ================================ -->
<div class="reference-members"><h2>Methods</h2>
<div id="activate" class="member">
<div class="member-link">
<a name="activate" href="#activate"><tt><b>activate</b>()</tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>Activates this tool, meaning <a href="../classes/PaperScope.html#tool"><tt>paperScope.tool</tt></a> will
point to it and it will be the one that recieves mouse events.</p>
</div>
</div>
</div>
<div id="remove" class="member">
<div class="member-link">
<a name="remove" href="#remove"><tt><b>remove</b>()</tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>Removes this tool from the <a href="../classes/PaperScope.html#tools"><tt>paperScope.tools</tt></a> list.</p>
</div>
</div>
</div>
<h3>Event Handling</h3>
<div id="attach-type-function" class="member">
<div class="member-link">
<a name="attach-type-function" href="#attach-type-function"><tt><b>attach</b>(type, function)</tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>Attach an event handler to the tool.</p>
<ul><b>Parameters:</b>
<li>
<tt>type:</tt>
<tt>String('mousedown'|'mouseup'|'mousedrag'|'mousemove'|'keydown'|'keyup')</tt>
— the event type
</li>
<li>
<tt>function:</tt>
<tt>Function</tt>
— The function to be called when the event
occurs
</li>
</ul>
</div>
</div>
</div>
<div id="attach-param" class="member">
<div class="member-link">
<a name="attach-param" href="#attach-param"><tt><b>attach</b>(param)</tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>Attach one or more event handlers to the tool.</p>
<ul><b>Parameters:</b>
<li>
<tt>param:</tt>
<tt>Object</tt>
— an object literal containing one or more of the
following properties: <tt>mousedown, mouseup, mousedrag, mousemove,
keydown, keyup</tt>.
</li>
</ul>
</div>
</div>
</div>
<div id="detach-type-function" class="member">
<div class="member-link">
<a name="detach-type-function" href="#detach-type-function"><tt><b>detach</b>(type, function)</tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>Detach an event handler from the tool.</p>
<ul><b>Parameters:</b>
<li>
<tt>type:</tt>
<tt>String('mousedown'|'mouseup'|'mousedrag'|'mousemove'|'keydown'|'keyup')</tt>
— the event type
</li>
<li>
<tt>function:</tt>
<tt>Function</tt>
— The function to be detached
</li>
</ul>
</div>
</div>
</div>
<div id="detach-param" class="member">
<div class="member-link">
<a name="detach-param" href="#detach-param"><tt><b>detach</b>(param)</tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>Detach one or more event handlers from the tool.</p>
<ul><b>Parameters:</b>
<li>
<tt>param:</tt>
<tt>Object</tt>
— an object literal containing one or more of the
following properties: <tt>mousedown, mouseup, mousedrag, mousemove,
keydown, keyup</tt>
</li>
</ul>
</div>
</div>
</div>
<div id="fire-type-event" class="member">
<div class="member-link">
<a name="fire-type-event" href="#fire-type-event"><tt><b>fire</b>(type, event)</tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>Fire an event on the tool.</p>
<ul><b>Parameters:</b>
<li>
<tt>type:</tt>
<tt>String('mousedown'|'mouseup'|'mousedrag'|'mousemove'|'keydown'|'keyup')</tt>
— the event type
</li>
<li>
<tt>event:</tt>
<tt>Object</tt>
— an object literal containing properties describing
the event.
</li>
</ul>
</div>
</div>
</div>
<div id="responds-type" class="member">
<div class="member-link">
<a name="responds-type" href="#responds-type"><tt><b>responds</b>(type)</tt></a>
</div>
<div class="member-description hidden">
<div class="member-text">
<p>Check if the tool has one or more event handlers of the specified type.</p>
<ul><b>Parameters:</b>
<li>
<tt>type:</tt>
<tt>String('mousedown'|'mouseup'|'mousedrag'|'mousemove'|'keydown'|'keyup')</tt>
— the event type
</li>
</ul>
<ul><b>Returns:</b>
<li>
<tt><tt>Boolean</tt></tt> — <tt>true</tt> if the tool has one or more event handlers of
the specified type, <tt>false</tt> otherwise
</li>
</ul>
</div>
</div>
</div>
</div>
<!-- =========================== copyright notice ========================= -->
<p class="footer">Copyright © 2011 <a href="http://www.lehni.org" target="_blank">Jürg Lehni</a> & <a href="http://www.jonathanpuckey.com" target="_blank">Jonathan Puckey</a>. All Rights Reserved.</p>
<div class="content-end"></div>
</body>