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 this.

Layer

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>

Position

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.)

Warning : contextPoint and point don’t work on touch devices, but you can use touchCenter and optionally convert it to a position inside the layer.

Converting position values

Position inside a layer

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.

An alternative property, touchCenter, does work on touch devices, but it gives the location on the Screen (like event.contextPoint).

Luckily there’s a function that translates Screen positions to Layer positions: Screen.convertPointToLayer.

Screen.convertPointToLayer point, layer

It takes a point value, which is x and 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

Position inside layer example

Position on the Canvas

There’s also a function to get the ‘bigger picture,’ the position of the touch event on the Canvas.

Screen.convertPointToCanvas point

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.

Offset

You know that event.contextPoint gives you the current position of the touch event, and event.start tells you where the user initially pressed down.

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.

Note: The offset.x and offset.y values will be negative when panning left or upwards.

An offsetAngle of -180 will give a offsetDirection of "left". Other example values are:

Delta

While 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.

Velocity

This speed property is expressed in seconds per 1000 points.

It will be a negative number when moving to the left or upwards.

See the Swipe event for an example of its use.

Force

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

See the Force tap event for an example of its use.

Input

The following properties (except fingers and touchCenter) will only return values when there are two or more fingers on the screen.

An event can start with two fingers and then have fingers added, but subsequently added fingers will be ignored in the calculation of touchCenter, touchDistance and touchOffset.

See Multi-touch events for more information.

Scale

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 2.

On a pinchable layer the event.scale property is used to set the layer’s scale.

Rotation

The 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 event.scale).

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 ⌥).

Overview of the gesture event properties

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.