source: main/trunk/model-sites-dev/von-sparql/js/paper/docs/classes/Tool.html@ 28914

Last change on this file since 28914 was 28914, checked in by ak19, 10 years ago

Supporting javascript libraries and bespoke code written by Steffan to support the von-sparql user interface
File size: 14.4 KB
Line 
1<!DOCTYPE html>
2<html>
3<head>
4<meta charset="UTF-8">
5<title>Tool</title>
6<base target="class-frame">
7<link href="../assets/css/docs.css" rel="stylesheet" type="text/css">
8<script src="../assets/js/paper.js"></script>
9<script src="../assets/js/jquery.js"></script>
10<script src="../assets/js/codemirror.js"></script>
11<script src="../assets/js/docs.js"></script>
12</head>
13<body class="reference">
14<div class="reference-class">
15<h1>Tool</h1>
16
17<p>The Tool object refers to a script that the user can interact with
18by using the mouse and keyboard and can be accessed through the global
19<tt>tool</tt> variable. All its properties are also available in the paper
20scope.</p>
21<p>The global <tt>tool</tt> variable only exists in scripts that contain mouse
22handler 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>,
23<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
24function (<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>
25<p>
26<b>Example</b>
27</p>
28
29
30<pre class="code">var path;
31
32// Only execute onMouseDrag when the mouse
33// has moved at least 10 points:
34tool.distanceThreshold = 10;
35
36function onMouseDown(event) {
37 // Create a new path every time the mouse is clicked
38 path = new Path();
39 path.add(event.point);
40 path.strokeColor = 'black';
41}
42
43function onMouseDrag(event) {
44 // Add a point to the path every time the mouse is dragged
45 path.add(event.point);
46}</pre>
47
48</div>
49
50
51
52
53
54 <div class="reference-members"><h2>Properties</h2>
55
56
57<div id="mindistance" class="member">
58<div class="member-link">
59<a name="mindistance" href="#mindistance"><tt><b>minDistance</b></tt></a>
60</div>
61<div class="member-description hidden">
62
63<div class="member-text">
64 <p>The minimum distance the mouse has to drag before firing the onMouseDrag
65event, since the last onMouseDrag event.</p>
66
67
68 <ul><b>Type:</b>
69 <li>
70 <tt>Number</tt>
71 </li>
72 </ul>
73
74
75</div>
76
77</div>
78</div>
79
80
81<div id="maxdistance" class="member">
82<div class="member-link">
83<a name="maxdistance" href="#maxdistance"><tt><b>maxDistance</b></tt></a>
84</div>
85<div class="member-description hidden">
86
87<div class="member-text">
88 <p>The maximum distance the mouse has to drag before firing the onMouseDrag
89event, since the last onMouseDrag event.</p>
90
91
92 <ul><b>Type:</b>
93 <li>
94 <tt>Number</tt>
95 </li>
96 </ul>
97
98
99</div>
100
101</div>
102</div>
103
104
105<div id="fixeddistance" class="member">
106<div class="member-link">
107<a name="fixeddistance" href="#fixeddistance"><tt><b>fixedDistance</b></tt></a>
108</div>
109<div class="member-description hidden">
110
111<div class="member-text">
112
113
114
115 <ul><b>Type:</b>
116 <li>
117 <tt>Number</tt>
118 </li>
119 </ul>
120
121
122</div>
123
124</div>
125</div>
126
127
128 <h3>Mouse Event Handlers</h3>
129
130<div id="onmousedown" class="member">
131<div class="member-link">
132<a name="onmousedown" href="#onmousedown"><tt><b>onMouseDown</b></tt></a>
133</div>
134<div class="member-description hidden">
135
136<div class="member-text">
137 <p>The function to be called when the mouse button is pushed down. The
138function receives a <a href="../classes/ToolEvent.html"><tt>ToolEvent</tt></a> object which contains information
139about the mouse event.</p>
140
141
142 <ul><b>Type:</b>
143 <li>
144 <tt>Function</tt>
145 </li>
146 </ul>
147
148 <p>
149<b>Example</b> &mdash; Creating circle shaped paths where the user presses the mouse button:
150</p>
151
152<div class="paperscript split">
153
154<div class="buttons">
155<div class="button run">Run</div>
156</div>
157
158<script type="text/paperscript" canvas="canvas-0">
159function onMouseDown(event) {
160 // Create a new circle shaped path with a radius of 10
161 // at the position of the mouse (event.point):
162 var path = new Path.Circle({
163 center: event.point,
164 radius: 10,
165 fillColor: 'black'
166 });
167}
168</script>
169<div class="canvas"><canvas width="516" height="100" id="canvas-0"></canvas></div>
170</div>
171
172
173</div>
174
175</div>
176</div>
177
178
179<div id="onmousedrag" class="member">
180<div class="member-link">
181<a name="onmousedrag" href="#onmousedrag"><tt><b>onMouseDrag</b></tt></a>
182</div>
183<div class="member-description hidden">
184
185<div class="member-text">
186 <p>The function to be called when the mouse position changes while the mouse
187is being dragged. The function receives a <a href="../classes/ToolEvent.html"><tt>ToolEvent</tt></a> object which
188contains information about the mouse event.</p>
189
190
191 <ul><b>Type:</b>
192 <li>
193 <tt>Function</tt>
194 </li>
195 </ul>
196
197 <p>
198<b>Example</b> &mdash; Draw a line by adding a segment to a path on every mouse drag event:
199</p>
200
201<div class="paperscript split">
202
203<div class="buttons">
204<div class="button run">Run</div>
205</div>
206
207<script type="text/paperscript" canvas="canvas-1">
208// Create an empty path:
209var path = new Path({
210 strokeColor: 'black'
211});
212
213function onMouseDrag(event) {
214 // Add a segment to the path at the position of the mouse:
215 path.add(event.point);
216}
217</script>
218<div class="canvas"><canvas width="516" height="100" id="canvas-1"></canvas></div>
219</div>
220
221
222</div>
223
224</div>
225</div>
226
227
228<div id="onmousemove" class="member">
229<div class="member-link">
230<a name="onmousemove" href="#onmousemove"><tt><b>onMouseMove</b></tt></a>
231</div>
232<div class="member-description hidden">
233
234<div class="member-text">
235 <p>The function to be called the mouse moves within the project view. The
236function receives a <a href="../classes/ToolEvent.html"><tt>ToolEvent</tt></a> object which contains information
237about the mouse event.</p>
238
239
240 <ul><b>Type:</b>
241 <li>
242 <tt>Function</tt>
243 </li>
244 </ul>
245
246 <p>
247<b>Example</b> &mdash; Moving a path to the position of the mouse:
248</p>
249
250<div class="paperscript split">
251
252<div class="buttons">
253<div class="button run">Run</div>
254</div>
255
256<script type="text/paperscript" canvas="canvas-2">
257// Create a circle shaped path with a radius of 10 at {x: 0, y: 0}:
258var path = new Path.Circle({
259 center: [0, 0],
260 radius: 10,
261 fillColor: 'black'
262});
263
264function onMouseMove(event) {
265 // Whenever the user moves the mouse, move the path
266 // to that position:
267 path.position = event.point;
268}
269</script>
270<div class="canvas"><canvas width="516" height="100" id="canvas-2"></canvas></div>
271</div>
272
273
274</div>
275
276</div>
277</div>
278
279
280<div id="onmouseup" class="member">
281<div class="member-link">
282<a name="onmouseup" href="#onmouseup"><tt><b>onMouseUp</b></tt></a>
283</div>
284<div class="member-description hidden">
285
286<div class="member-text">
287 <p>The function to be called when the mouse button is released. The function
288receives a <a href="../classes/ToolEvent.html"><tt>ToolEvent</tt></a> object which contains information about the
289mouse event.</p>
290
291
292 <ul><b>Type:</b>
293 <li>
294 <tt>Function</tt>
295 </li>
296 </ul>
297
298 <p>
299<b>Example</b> &mdash; Creating circle shaped paths where the user releases the mouse:
300</p>
301
302<div class="paperscript split">
303
304<div class="buttons">
305<div class="button run">Run</div>
306</div>
307
308<script type="text/paperscript" canvas="canvas-3">
309function onMouseUp(event) {
310 // Create a new circle shaped path with a radius of 10
311 // at the position of the mouse (event.point):
312 var path = new Path.Circle({
313 center: event.point,
314 radius: 10,
315 fillColor: 'black'
316 });
317}
318</script>
319<div class="canvas"><canvas width="516" height="100" id="canvas-3"></canvas></div>
320</div>
321
322
323</div>
324
325</div>
326</div>
327
328
329 <h3>Keyboard Event Handlers</h3>
330
331<div id="onkeydown" class="member">
332<div class="member-link">
333<a name="onkeydown" href="#onkeydown"><tt><b>onKeyDown</b></tt></a>
334</div>
335<div class="member-description hidden">
336
337<div class="member-text">
338 <p>The function to be called when the user presses a key on the keyboard.</p>
339<p>The function receives a <a href="../classes/KeyEvent.html"><tt>KeyEvent</tt></a> object which contains
340information about the keyboard event.</p>
341<p>If the function returns <tt>false</tt>, the keyboard event will be
342prevented from bubbling up. This can be used for example to stop the
343window from scrolling, when you need the user to interact with arrow
344keys.</p>
345
346
347 <ul><b>Type:</b>
348 <li>
349 <tt>Function</tt>
350 </li>
351 </ul>
352
353 <p>
354<b>Example</b> &mdash; Scaling a path whenever the user presses the space bar:
355</p>
356
357<div class="paperscript split">
358
359<div class="buttons">
360<div class="button run">Run</div>
361</div>
362
363<script type="text/paperscript" canvas="canvas-4">
364// Create a circle shaped path:
365 var path = new Path.Circle({
366 center: new Point(50, 50),
367 radius: 30,
368 fillColor: 'red'
369 });
370
371function onKeyDown(event) {
372 if (event.key == 'space') {
373 // Scale the path by 110%:
374 path.scale(1.1);
375
376 // Prevent the key event from bubbling
377 return false;
378 }
379}
380</script>
381<div class="canvas"><canvas width="516" height="100" id="canvas-4"></canvas></div>
382</div>
383
384
385</div>
386
387</div>
388</div>
389
390
391<div id="onkeyup" class="member">
392<div class="member-link">
393<a name="onkeyup" href="#onkeyup"><tt><b>onKeyUp</b></tt></a>
394</div>
395<div class="member-description hidden">
396
397<div class="member-text">
398 <p>The function to be called when the user releases a key on the keyboard.</p>
399<p>The function receives a <a href="../classes/KeyEvent.html"><tt>KeyEvent</tt></a> object which contains
400information about the keyboard event.</p>
401<p>If the function returns <tt>false</tt>, the keyboard event will be
402prevented from bubbling up. This can be used for example to stop the
403window from scrolling, when you need the user to interact with arrow
404keys.</p>
405
406
407 <ul><b>Type:</b>
408 <li>
409 <tt>Function</tt>
410 </li>
411 </ul>
412
413 <p>
414<b>Example</b>
415</p>
416
417
418<pre class="code">function onKeyUp(event) {
419 if (event.key == 'space') {
420 console.log('The spacebar was released!');
421 }
422}</pre>
423
424</div>
425
426</div>
427</div>
428
429 </div>
430
431
432
433<!-- ============================== methods ================================ -->
434 <div class="reference-members"><h2>Methods</h2>
435
436
437<div id="activate" class="member">
438<div class="member-link">
439<a name="activate" href="#activate"><tt><b>activate</b>()</tt></a>
440</div>
441<div class="member-description hidden">
442<div class="member-text">
443 <p>Activates this tool, meaning <a href="../classes/PaperScope.html#tool"><tt>paperScope.tool</tt></a> will
444point to it and it will be the one that recieves mouse events.</p>
445
446
447
448
449</div>
450</div>
451</div>
452
453
454<div id="remove" class="member">
455<div class="member-link">
456<a name="remove" href="#remove"><tt><b>remove</b>()</tt></a>
457</div>
458<div class="member-description hidden">
459<div class="member-text">
460 <p>Removes this tool from the <a href="../classes/PaperScope.html#tools"><tt>paperScope.tools</tt></a> list.</p>
461
462
463
464
465</div>
466</div>
467</div>
468
469
470<h3>Event Handling</h3>
471
472<div id="attach-type-function" class="member">
473<div class="member-link">
474<a name="attach-type-function" href="#attach-type-function"><tt><b>attach</b>(type, function)</tt></a>
475</div>
476<div class="member-description hidden">
477<div class="member-text">
478 <p>Attach an event handler to the tool.</p>
479
480<ul><b>Parameters:</b>
481
482<li>
483<tt>type:</tt>
484<tt>String('mousedown'|'mouseup'|'mousedrag'|'mousemove'|'keydown'|'keyup')</tt>
485&mdash;&nbsp;the event type
486
487</li>
488
489<li>
490<tt>function:</tt>
491<tt>Function</tt>
492&mdash;&nbsp;The function to be called when the event
493occurs
494
495</li>
496
497</ul>
498
499
500
501
502</div>
503</div>
504</div>
505
506
507<div id="attach-param" class="member">
508<div class="member-link">
509<a name="attach-param" href="#attach-param"><tt><b>attach</b>(param)</tt></a>
510</div>
511<div class="member-description hidden">
512<div class="member-text">
513 <p>Attach one or more event handlers to the tool.</p>
514
515<ul><b>Parameters:</b>
516
517<li>
518<tt>param:</tt>
519<tt>Object</tt>
520&mdash;&nbsp;an object literal containing one or more of the
521following properties: <tt>mousedown, mouseup, mousedrag, mousemove,
522keydown, keyup</tt>.
523
524</li>
525
526</ul>
527
528
529
530
531</div>
532</div>
533</div>
534
535
536<div id="detach-type-function" class="member">
537<div class="member-link">
538<a name="detach-type-function" href="#detach-type-function"><tt><b>detach</b>(type, function)</tt></a>
539</div>
540<div class="member-description hidden">
541<div class="member-text">
542 <p>Detach an event handler from the tool.</p>
543
544<ul><b>Parameters:</b>
545
546<li>
547<tt>type:</tt>
548<tt>String('mousedown'|'mouseup'|'mousedrag'|'mousemove'|'keydown'|'keyup')</tt>
549&mdash;&nbsp;the event type
550
551</li>
552
553<li>
554<tt>function:</tt>
555<tt>Function</tt>
556&mdash;&nbsp;The function to be detached
557
558</li>
559
560</ul>
561
562
563
564
565</div>
566</div>
567</div>
568
569
570<div id="detach-param" class="member">
571<div class="member-link">
572<a name="detach-param" href="#detach-param"><tt><b>detach</b>(param)</tt></a>
573</div>
574<div class="member-description hidden">
575<div class="member-text">
576 <p>Detach one or more event handlers from the tool.</p>
577
578<ul><b>Parameters:</b>
579
580<li>
581<tt>param:</tt>
582<tt>Object</tt>
583&mdash;&nbsp;an object literal containing one or more of the
584following properties: <tt>mousedown, mouseup, mousedrag, mousemove,
585keydown, keyup</tt>
586
587</li>
588
589</ul>
590
591
592
593
594</div>
595</div>
596</div>
597
598
599<div id="fire-type-event" class="member">
600<div class="member-link">
601<a name="fire-type-event" href="#fire-type-event"><tt><b>fire</b>(type, event)</tt></a>
602</div>
603<div class="member-description hidden">
604<div class="member-text">
605 <p>Fire an event on the tool.</p>
606
607<ul><b>Parameters:</b>
608
609<li>
610<tt>type:</tt>
611<tt>String('mousedown'|'mouseup'|'mousedrag'|'mousemove'|'keydown'|'keyup')</tt>
612&mdash;&nbsp;the event type
613
614</li>
615
616<li>
617<tt>event:</tt>
618<tt>Object</tt>
619&mdash;&nbsp;an object literal containing properties describing
620the event.
621
622</li>
623
624</ul>
625
626
627
628
629</div>
630</div>
631</div>
632
633
634<div id="responds-type" class="member">
635<div class="member-link">
636<a name="responds-type" href="#responds-type"><tt><b>responds</b>(type)</tt></a>
637</div>
638<div class="member-description hidden">
639<div class="member-text">
640 <p>Check if the tool has one or more event handlers of the specified type.</p>
641
642<ul><b>Parameters:</b>
643
644<li>
645<tt>type:</tt>
646<tt>String('mousedown'|'mouseup'|'mousedrag'|'mousemove'|'keydown'|'keyup')</tt>
647&mdash;&nbsp;the event type
648
649</li>
650
651</ul>
652
653
654 <ul><b>Returns:</b>
655
656 <li>
657<tt><tt>Boolean</tt></tt>&nbsp;&mdash;&nbsp;<tt>true</tt> if the tool has one or more event handlers of
658the specified type, <tt>false</tt> otherwise
659</li>
660
661 </ul>
662
663
664
665</div>
666</div>
667</div>
668
669 </div>
670
671
672
673
674<!-- =========================== copyright notice ========================= -->
675<p class="footer">Copyright &#169; 2011 <a href="http://www.lehni.org" target="_blank">J&uuml;rg Lehni</a> &amp; <a href="http://www.jonathanpuckey.com" target="_blank">Jonathan Puckey</a>. All Rights Reserved.</p>
676<div class="content-end"></div>
677
678</body>
Note: See TracBrowser for help on using the repository browser.