Accessing gesture event properties
Every event handler receives an
event object each time it’s called, and through this object, you have access to a wealth of information about the event. Check the overview prototype at the end of this chapter to see all the properties together.
When you add an event handler with the Event button (or by right-clicking the layer’s name), it will also add
(event, layer) parameters for your convenience.
layerA.onTap (event, layer) -> # do something
You don’t need them, though. The
event variable will work anyway, and the layer can be accessed as
When you omit the
(event, layer) part, you’ll still be able to access the layer with
this, or its alias in CoffeeScript:
layerA.onTap -> print this print @ print @.backgroundColor print @backgroundColor » <Layer layerA id:1 (0, 0) 200x200> » <Layer layerA id:1 (0, 0) 200x200> » <Color r:123 g:123 b:123 a:0.5> » <Color r:123 g:123 b:123 a:0.5>
These properties give the location of the finger or cursor on the Screen. The exception is
event.point: it gives you a position on the layer itself.
You can get not only the current location, but also where the cursor was a moment earlier (
previous), and the place where the event started (
start: the spot where the user pressed down).
When there are more fingers on the screen, you’ll only get the position of the first one. (Use
touchCenter to get the center point between two fingers.)
|The initial x position of the current gesture (on the Screen)|
|The initial y position of the current gesture (on the Screen)|
|The previous x position of the current panning gesture (on the Screen)|
|The previous y position of the current panning gesture (on the Screen)|
|The current x position (on the Screen)|
|The current y position (on the Screen)|
|The current x position (in the layer itself)|
|The current y position (in the layer itself)|
To get a touch point in the layer’s coordinate system you can, of course, use
event.point. The only problem is that this property (currently) doesn’t return values on mobile devices.
Luckily there’s a function that translates Screen positions to Layer positions:
Screen.convertPointToLayer point, layer
It takes a
point value, which is
y combined in an object, like “, and will give you the point value inside the layer.
pointInLayerA = Screen.convertPointToLayer event.touchCenter, layerA # print the x and y locations print pointInLayerA.x print pointInLayerA.y
In the following prototype, I use this position inside the layer to calculate a new transform origin to rotate the layer around.
square.onTap -> pointInLayer = Screen.convertPointToLayer event.touchCenter, this # calculate and set new transform origin this.originX = pointInLayer.x / this.width this.originY = pointInLayer.y / this.height # reset rotation this.rotation = 0 # rotate ! this.animate rotation: 360
There’s also a function to get the ‘bigger picture,’ the position of the touch event on the
The resulting value depends of course on the current size of the Canvas (or in ‘Present’ mode, the size of your monitor).
pointOnScreen = Screen.convertPointToCanvas event.point # print the x and y locations print pointOnScreen.x print pointOnScreen.y
Naturally, when you’re not using a device frame (Preview Window set to ‘Canvas’), it will just return the point value you gave it.
Well, the ‘offset’ properties give you the distance between these points (how far the user panned), how many milliseconds they’ve been panning, and what this means in terms of angle or direction.
|Horizontal distance between the start position and the current position|
|Vertical distance between the start position and the current position|
|How many milliseconds the user has been panning|
|The angle in degrees between the start point and the current point, a value between -180º and 180º|
|Current direction compared to the start point, contains a string: |
offset.y values will be negative when panning left or upwards.
-180 will give a
"left". Other example values are:
event.previous gives the previous position in an ongoing panning gesture, the ‘delta’ values will give the distance from that point.
They also tell you how many milliseconds have passed since the last movement, and in which direction we’re heading compared to that previous position.
|Horizontal distance between the previous position and the current one|
|Vertical distance between the previous position and the current one|
|Time passed since the last panning movement, in milliseconds|
|Angle change since the last movement|
|Direction change since the last movement|
This speed property is expressed in seconds per 1000 points.
It will be a negative number when moving to the left or upwards.
|Current horizontal speed in seconds per 1000 points|
|Current vertical speed in seconds per 1000 points|
See the Swipe event for an example of its use.
Naturally, you will only get a value higher than
0 on a pressure sensitive device. The options are:
- An iPhone with 3D Touch (iPhone 6s or newer)
- A Magic Trackpad 2 connected to your Mac
- The Force Touch trackpad on a recent MacBook or MacBook Pro
|The current pressure of the touch, a number between `0` and |
See the Force tap event for an example of its use.
The following properties (except
touchCenter) will only return values when there are two or more fingers on the screen.
|Amount of fingers on the screen|
|The x location of the center point between the two fingers (on the Screen)|
|The y location of the center point between the two fingers (on the Screen)|
|The distance between the two fingers (minimum value: |
|The horizontal distance between the two fingers|
|The vertical distance between the two fingers|
An event can start with two fingers and then have fingers added, but subsequently added fingers will be ignored in the calculation of
See Multi-touch events for more information.
The distance between the two fingers compared to their initial distance.
The start value is always
1, so if you pressed down with your fingers 100 points apart and moved them to a distance of 200 points apart, the
scale would then be
|Distance between the two fingers compared to their initial distance|
|A string with the current scaling direction: |
On a pinchable layer the
event.scale property is used to set the layer’s
The angle of the line between the two fingers.
|Current angle of the line between the two fingers|
On touch devices, this is a relative value which always starts at
0 (relative to the initial touch, like
On the desktop, it gives the absolute angle between the first and the second pointer (at least now, with the multi-touch simulation you get when holding down ⌥).
Velocity doesn’t refresh often in the above video because there are so many other Text Layers being updated. I tends to work better on an iPhone.