Events » Accessing gesture event properties

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.


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

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.

event.start.xThe initial x position of the current gesture (on the Screen)
event.start.yThe initial y position of the current gesture (on the Screen)
event.previous.xThe previous x position of the current panning gesture (on the Screen)
event.previous.yThe previous y position of the current panning gesture (on the Screen)
event.contextPoint.xThe current x position (on the Screen)
event.contextPoint.yThe current y position (on the Screen)
event.point.xThe current x position (in the layer itself)
event.point.yThe current y position (in the layer itself)

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 !
        rotation: 360
Download Framer project
Position inside layer example
Each tap changes the transform origin

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.


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.

point.xHorizontal distance of the Frame from the start position to the current position
point.yVertical distance of the Frame from the start position to the current position
delta.xHow many milliseconds the user has been panning
delta.yThe angle in degrees between the start point and the current point, a value between -180º and 180º
offset.xCurrent direction compared to the start point, contains a string: "left", "right", "up" or "down"

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:

180…also "left"


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.

Delta distance between the previous position and the current one distance between the previous position and the current one
event.deltaTimeTime passed since the last panning movement, in milliseconds
event.deltaAngleAngle change since the last movement
event.deltaDirectionDirection 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.

event.velocity.xCurrent horizontal speed in seconds per 1000 points
event.velocity.yCurrent 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
event.forceThe current pressure of the touch, a number between `0` and 1

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


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

event.fingersAmount of fingers on the screen
event.touchCenter.xThe x location of the center point between the two fingers (on the Screen)
event.touchCenter.yThe y location of the center point between the two fingers (on the Screen)
event.touchDistanceThe distance between the two fingers (minimum value: 30)
event.touchOffset.xThe horizontal distance between the two fingers
event.touchOffset.yThe 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 touchCenter, touchDistance and touchOffset.

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

event.scaleDistance between the two fingers compared to their initial distance
event.scaleDirectionA string with the current scaling direction: "up" when the fingers are moving apart, "down" when moving towards each other

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


The angle of the line between the two fingers.

event.rotationCurrent 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

Values of all the gesture event properties
Download Framer project

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.