callbacks-events.mdx

id	callbacks-events
title	Gesture callbacks & events
sidebar_label	Gesture callbacks & events
sidebar_position	6

import { GestureEventFlowChart, TouchEventFlowChart } from '@site/src/examples/CallbacksFlowCharts'

At any given time, each handler instance has an assigned state that can change when new touch events occur or can be forced to change by the touch system under certain circumstances. You can hook into state transitions using specific gesture callbacks.

When Reanimated is installed, all callbacks are automatically workletized. For more details, refer to the Integration with Reanimated section.

Callbacks flow

GestureEvent callbacks

Note that some of these callbacks are complementary:

• if onBegin was called, it is guaranteed that onFinalize will be called later.
• if onActivate was called, it is guaranteed that onDeactivate will be called later.

TouchEvent callbacks

Callbacks

onBegin

onBegin: (event: GestureEvent<HandlerData>) => void

Called when a handler begins to recognize gestures. If onBegin was called, it is guaranteed that onFinalize will be called later.

onActivate

onActivate: (event: GestureEvent<HandlerData>) => void

Called when activation criteria for handler are met. If onActivate was called, it is guaranteed that onDeactivate will be called later.

onUpdate

onUpdate: (event: GestureEvent<HandlerData>) => void

Called each time a pointer tracked by the gesture changes state, typically due to movement, after the gesture has been activated.

onDeactivate

onDeactivate: (event: GestureEvent<HandlerData>, didSucceed: boolean) => void

Called after when handler stops recognizing gestures, but only if handler activated. It is called before onFinalize. If the handler was interrupted, the didSucceed argument is set to false. Otherwise it is set to true.

onFinalize

onFinalize: (event: GestureEvent<HandlerData>, didSucceed: boolean) => void

Called when handler stops recognizing gestures. If handler managed to activate, the didSucceed argument is set to true and onFinalize will be called right after onDeactivate. Otherwise it is set to false.

onTouchesDown

onTouchesDown: (event: GestureTouchEvent) => void

Called when new pointers are placed on the screen. It may carry information about more than one pointer because the events are batched.

onTouchesMove

onTouchesMove: (event: GestureTouchEvent) => void

Called when pointers are moved on the screen. It may carry information about more than one pointer because the events are batched.

onTouchesUp

onTouchesUp: (event: GestureTouchEvent) => void

Called when pointers are lifted from the screen. It may carry information about more than one pointer because the events are batched.

onTouchesCancel

onTouchesCancel: (event: GestureTouchEvent) => void

Called when there will be no more information about this pointer. It may be called because the gesture has ended or was interrupted. It may carry information about more than one pointer because the events are batched.

Events

GestureEvent

<CollapsibleCode label="Show composed types definitions" expandedLabel="Hide composed types definitions" lineBounds={[0, 4]} src={` export type GestureEvent = { handlerTag: number; numberOfPointers: number; pointerType: PointerType; } & HandlerData;

export enum PointerType { TOUCH, STYLUS, MOUSE, KEY, OTHER, } `}/>

GestureEvent contains properties common to all gestures (handlerTag, numberOfPointers, pointerType) along with gesture-specific data defined in each gesture's documentation.

TouchEvent

<CollapsibleCode label="Show composed types definitions" expandedLabel="Hide composed types definitions" lineBounds={[0, 8]} src={` export type GestureTouchEvent = { handlerTag: number; numberOfTouches: number; state: State; eventType: TouchEventType; allTouches: TouchData[]; changedTouches: TouchData[]; pointerType: PointerType; };

export const State = { UNDETERMINED: 0, FAILED: 1, BEGAN: 2, CANCELLED: 3, ACTIVE: 4, END: 5, } as const;

export const TouchEventType = { UNDETERMINED: 0, TOUCHES_DOWN: 1, TOUCHES_MOVE: 2, TOUCHES_UP: 3, TOUCHES_CANCEL: 4, } as const;

export enum PointerType { TOUCH, STYLUS, MOUSE, KEY, OTHER, }

export type TouchData = { id: number; x: number; y: number; absoluteX: number; absoluteY: number; }; `}/>

TouchEvent carries information about raw touch events, like touching the screen or moving the finger.

• eventType - Type of the current event - whether the finger was placed on the screen, moved, lifted or cancelled.

• changedTouches - An array of objects where every object represents a single touch. Contains information only about the touches that were affected by the event i.e. those that were placed down, moved, lifted or cancelled.

• allTouches - An array of objects where every object represents a single touch. Contains information about all active touches.

• numberOfTouches - Number representing the count of currently active touches.

TouchData contains information about a single touch.

• id - A number representing id of the touch. It may be used to track the touch between events as the id will not change while it is being tracked.

• x - X coordinate of the current position of the touch relative to the view attached to the GestureDetector. Expressed in point units.

• y - Y coordinate of the current position of the touch relative to the view attached to the GestureDetector. Expressed in point units.

• absoluteX - X coordinate of the current position of the touch relative to the window. The value is expressed in point units. It is recommended to use it instead of x in cases when the original view can be transformed as an effect of the gesture.

• absoluteY - Y coordinate of the current position of the touch relative to the window. The value is expressed in point units. It is recommended to use it instead of y in cases when the original view can be transformed as an effect of the gesture.

:::danger Don't rely on the order of items in the changedTouches/allTouches arrays as it may change during the gesture, instead use the id attribute to track individual touches across events. :::