diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/_category_.json b/packages/docs-gesture-handler/docs/legacy-gestures/_category_.json new file mode 100644 index 0000000000..34711dcafc --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Gesture Handler 2", + "position": 4, + "link": { + "type": "generated-index" + } +} diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-continuous-gesture-callbacks.md b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-continuous-gesture-callbacks.md new file mode 100644 index 0000000000..60e2af2c48 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-continuous-gesture-callbacks.md @@ -0,0 +1,9 @@ +### Callbacks common to all continuous gestures: + +### `onUpdate(callback)` + +Set the callback that is being called every time the gesture receives an update while it's active. + +### `onChange(callback)` + +Set the callback that is being called every time the gesture receives an update while it's active. This callback will receive information about change in value in relation to the last received event. diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-continuous-gesture-config.md b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-continuous-gesture-config.md new file mode 100644 index 0000000000..f829d626e9 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-continuous-gesture-config.md @@ -0,0 +1,5 @@ +### Properties common to all continuous gestures: + +### `manualActivation(value: boolean)` + +When `true` the handler will not activate by itself even if its activation criteria are met. Instead you can manipulate its state using [state manager](/docs/2.x/gestures/state-manager/). diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-gesture-callbacks.md b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-gesture-callbacks.md new file mode 100644 index 0000000000..dff985b307 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-gesture-callbacks.md @@ -0,0 +1,33 @@ +### Callbacks common to all gestures: + +### `onBegin(callback)` + +Set the callback that is being called when given gesture handler starts receiving touches. At the moment of this callback the handler is not yet in an active state and we don't know yet if it will recognize the gesture at all. + +### `onStart(callback)` + +Set the callback that is being called when the gesture is recognized by the handler and it transitions to the active state. + +### `onEnd(callback)` + +Set the callback that is being called when the gesture that was recognized by the handler finishes. It will be called only if the handler was previously in the active state. + +### `onFinalize(callback)` + +Set the callback that is being called when the handler finalizes handling gesture - the gesture was recognized and has finished or it failed to recognize. + +### `onTouchesDown(callback)` + +Set the `onTouchesDown` callback which is called every time a finger is placed on the screen. + +### `onTouchesMove(callback)` + +Set the `onTouchesMove` callback which is called every time a finger is moved on the screen. + +### `onTouchesUp(callback)` + +Set the `onTouchesUp` callback which is called every time a finger is lifted from the screen. + +### `onTouchesCancelled(callback)` + +Set the `onTouchesCancelled` callback which is called every time a finger stops being tracked, for example when the gesture finishes. diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-gesture-config.md b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-gesture-config.md new file mode 100644 index 0000000000..6a39d4cb75 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-gesture-config.md @@ -0,0 +1,68 @@ +### Properties common to all gestures: + +### `enabled(value: boolean)` + +Indicates whether the given handler should be analyzing stream of touch events or not. +When set to `false` we can be sure that the handler's state will **never** become [`ACTIVE`](/docs/2.x/fundamentals/states-events#active). +If the value gets updated while the handler already started recognizing a gesture, then the handler's state it will immediately change to [`FAILED`](/docs/2.x/fundamentals/states-events#failed) or [`CANCELLED`](/docs/2.x/fundamentals/states-events#cancelled) (depending on its current state). +Default value is `true`. + +### `shouldCancelWhenOutside(value: boolean)` + +When `true` the handler will [cancel](/docs/2.x/fundamentals/states-events#cancelled) or [fail](/docs/2.x/fundamentals/states-events#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. +Default value of this property is different depending on the handler type. +Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGesture`](/docs/2.x/gestures/long-press-gesture) and [`TapGesture`](/docs/2.x/gestures/tap-gesture) which default to `true`. + +### `hitSlop(settings)` + +This parameter enables control over what part of the connected view area can be used to [begin](/docs/2.x/fundamentals/states-events#began) recognizing the gesture. +When a negative number is provided the bounds of the view will reduce the area by the given number of points in each of the sides evenly. + +Instead you can pass an object to specify how each boundary side should be reduced by providing different number of points for `left`, `right`, `top` or `bottom` sides. +You can alternatively provide `horizontal` or `vertical` instead of specifying directly `left`, `right` or `top` and `bottom`. +Finally, the object can also take `width` and `height` attributes. +When `width` is set it is only allow to specify one of the sides `right` or `left`. +Similarly when `height` is provided only `top` or `bottom` can be set. +Specifying `width` or `height` is useful if we only want the gesture to activate on the edge of the view. In which case for example we can set `left: 0` and `width: 20` which would make it possible for the gesture to be recognize when started no more than 20 points from the left edge. + +**IMPORTANT:** Note that this parameter is primarily designed to reduce the area where gesture can activate. Hence it is only supported for all the values (except `width` and `height`) to be non positive (0 or lower). Although on Android it is supported for the values to also be positive and therefore allow to expand beyond view bounds but not further than the parent view bounds. To achieve this effect on both platforms you can use React Native's View [hitSlop](https://reactnative.dev/docs/view.html#hitslop) property. + +### `withRef(ref)` + +Sets a ref to the gesture object, allowing for interoperability with the old +API. + +### `withTestId(testID)` + +Sets a `testID` property for gesture object, allowing for querying for it in tests. + +### `cancelsTouchesInView(value)` (**iOS only**) + +Accepts a boolean value. +When `true`, the gesture will cancel touches for native UI components (`UIButton`, `UISwitch`, etc) it's attached to when it becomes [`ACTIVE`](/docs/2.x/fundamentals/states-events#active). +Default value is `true`. + +### `runOnJS(value: boolean)` + +When `react-native-reanimated` is installed, the callbacks passed to the gestures are automatically workletized and run on the UI thread when called. This option allows for changing this behavior: when `true`, all the callbacks will be run on the JS thread instead of the UI thread, regardless of whether they are worklets or not. +Defaults to `false`. + +### `simultaneousWithExternalGesture(otherGesture1, otherGesture2, ...)` + +Adds a gesture that should be recognized simultaneously with this one. + +**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](/docs/2.x/fundamentals/gesture-composition). [`GestureDetector`](/docs/2.x/gestures/gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. + +### `requireExternalGestureToFail(otherGesture1, otherGesture2, ...)` + +Adds a relation requiring another gesture to fail, before this one can activate. + +### `blocksExternalGesture(otherGesture1, otherGesture2, ...)` + +Adds a relation that makes other gestures wait with activation until this gesture fails (or doesn't start at all). + +**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](/docs/2.x/fundamentals/gesture-composition).[`GestureDetector`](/docs/2.x/gestures/gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. + +### `activeCursor(value)` (Web only) + +This parameter allows to specify which cursor should be used when gesture activates. Supports all CSS cursor values (e.g. `"grab"`, `"zoom-in"`). Default value is set to `"auto"`. diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-gesture-event-data.md b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-gesture-event-data.md new file mode 100644 index 0000000000..674f2fb478 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/base-gesture-event-data.md @@ -0,0 +1,19 @@ +### Event attributes common to all gestures: + +### `state` + +Current [state](/docs/2.x/fundamentals/states-events) of the handler. Expressed as one of the constants exported under `State` object by the library. + +### `numberOfPointers` + +Represents the number of pointers (fingers) currently placed on the screen. + +### `pointerType` + +Indicates the type of pointer device in use. This value is represented by the `PointerType` enum, which includes the following fields: + +- `TOUCH` - represents finger +- `STYLUS` - represents stylus or digital pen +- `MOUSE` - represents computer mouse +- `KEY` - represents keyboard +- `OTHER` - represents unknown device type that is not relevant diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/_shared/gesture-detector-functional1.md b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/gesture-detector-functional1.md new file mode 100644 index 0000000000..2397af9dfa --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/gesture-detector-functional1.md @@ -0,0 +1,19 @@ +```jsx +export default function Example() { + const tap = Gesture.Tap().onStart(() => { + console.log('tap'); + }); + + return ( + + + + + + ); +} + +function FunctionalComponent(props) { + return {props.children}; +} +``` diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/_shared/v2-info.md b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/v2-info.md new file mode 100644 index 0000000000..8de3945b6f --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/_shared/v2-info.md @@ -0,0 +1,3 @@ +:::warning +Heads up! This page covers the old builder-based API from Gesture Handler 2. We recommend checking out the newer hook-based API from Gesture Handler 3. +::: diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/composed-gestures.md b/packages/docs-gesture-handler/docs/legacy-gestures/composed-gestures.md new file mode 100644 index 0000000000..32d211e074 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/composed-gestures.md @@ -0,0 +1,32 @@ +--- +id: composed-gestures +title: Composed gestures +sidebar_label: Composed gestures +sidebar_position: 13 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +Composed gestures (`Race`, `Simultaneous`, `Exclusive`) provide a simple way of building relations between gestures. See [Gesture Composition](/docs/2.x/fundamentals/gesture-composition) for more details. + +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + const pan = Gesture.Pan(); + const longPress = Gesture.LongPress(); + + // highlight-next-line + const composed = Gesture.Race(pan, longPress); + + return ( + + + + ); +} +``` diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/fling-gesture.md b/packages/docs-gesture-handler/docs/legacy-gestures/fling-gesture.md new file mode 100644 index 0000000000..7a3ec0c304 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/fling-gesture.md @@ -0,0 +1,157 @@ +--- +id: fling-gesture +title: Fling gesture +sidebar_label: Fling gesture +sidebar_position: 7 +--- + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import FlingGestureBasic from '@site/static/examples/FlingGestureBasic'; +import FlingGestureBasicSrc from '!!raw-loader!@site/static/examples/FlingGestureBasicSrc'; + +import OldAPIInfo from './\_shared/v2-info.md' + + + +
+
+ +
+ } + src={FlingGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; + +A discrete gesture that activates when the movement is sufficiently long and fast. +Gesture gets [ACTIVE](/docs/2.x/fundamentals/states-events#active) when movement is sufficiently long and it does not take too much time. +When gesture gets activated it will turn into [END](/docs/2.x/fundamentals/states-events#end) state when finger is released. +The gesture will fail to recognize if the finger is lifted before being activated. + +
+ +
+ +Fling Gesture + +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { + Gesture, + GestureDetector, + Directions, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, + withTiming, +} from 'react-native-reanimated'; + +export default function App() { + const position = useSharedValue(0); + // highlight-next-line + const flingGesture = Gesture.Fling() + .direction(Directions.RIGHT) + .onStart((e) => { + position.value = withTiming(position.value + 10, { duration: 100 }); + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ translateX: position.value }], + })); + + return ( + + + + ); +} + +const styles = StyleSheet.create({ + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Config + +### Properties specific to `FlingGesture`: + +### `direction(value: Directions)` + +Expressed allowed direction of movement. Expected values are exported as constants in the `Directions` object. It's possible to pass one or many directions in one parameter: + +```js +import { Directions } from 'react-native-gesture-handler'; +fling.direction(Directions.RIGHT | Directions.LEFT); +``` + +or + +```js +fling.direction(Directions.DOWN); +``` + +### `numberOfPointers(value: number)` + +Determine exact number of points required to handle the fling gesture. + +### `mouseButton(value: MouseButton)` (Web & Android only) + +Allows users to choose which mouse button should handler respond to. The enum `MouseButton` consists of the following predefined fields: + +- `LEFT` +- `RIGHT` +- `MIDDLE` +- `BUTTON_4` +- `BUTTON_5` +- `ALL` + +Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Default value is set to `MouseButton.LEFT`. + + + +## Callbacks + + + +## Event data + +### Event attributes specific to `FlingGesture`: + +### `x` + +X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. + +### `y` + +Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. + +### `absoluteX` + +X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#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 pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. + + diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/force-touch-gesture.md b/packages/docs-gesture-handler/docs/legacy-gestures/force-touch-gesture.md new file mode 100644 index 0000000000..be8eba81b6 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/force-touch-gesture.md @@ -0,0 +1,80 @@ +--- +id: force-touch-gesture +title: Force touch gesture (iOS only) +sidebar_label: Force touch gesture +sidebar_position: 10 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +:::warning +ForceTouch gesture is deprecated and will be removed in the future version of Gesture Handler. +::: + +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseContinuousEventConfig from './\_shared/base-continuous-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinuousEventCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; + +A continuous gesture that recognizes force of a touch. It allows for tracking pressure of touch on some iOS devices. +The gesture [activates](/docs/2.x/fundamentals/states-events#active) when pressure of touch is greater than or equal to `minForce`. It fails if pressure is greater than `maxForce`. +Gesture callback can be used for continuous tracking of the touch pressure. It provides information for one finger (the first one). + +At the beginning of the gesture, the pressure factor is 0.0. As the pressure increases, the pressure factor increases proportionally. The maximum pressure is 1.0. + +There's no implementation provided on Android and it simply renders children without any wrappers. +Since this behaviour is only provided on some iOS devices, this gesture should not be used for defining any crucial behaviors. Use it only as an additional improvement and make all features to be accessed without this gesture as well. + +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const forceTouch = Gesture.ForceTouch(); + + return ( + + + + ); +} +``` + +## Config + +### Properties specific to `ForceTouchGesture`: + +### `minForce(value: number)` + +A minimal pressure that is required before gesture can [activate](/docs/2.x/fundamentals/states-events#active). Should be a value from range `[0.0, 1.0]`. Default is `0.2`. + +### `maxForce(value: number)` + +A maximal pressure that could be applied for gesture. If the pressure is greater, gesture [fails](/docs/2.x/fundamentals/states-events#failed). Should be a value from range `[0.0, 1.0]`. + +### `feedbackOnActivation(value: boolean)` + +Value defining if haptic feedback has to be performed on activation. + + + + +## Callbacks + + + + +## Event data + +### Event attributes specific to `ForceTouchGesture`: + +### `force` + +The pressure of a touch. + + diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/gesture-composition.md b/packages/docs-gesture-handler/docs/legacy-gestures/gesture-composition.md new file mode 100644 index 0000000000..4bbdac55c7 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/gesture-composition.md @@ -0,0 +1,411 @@ +--- +id: gesture-composition +title: Gesture composition & interactions +sidebar_label: Gesture composition & interactions +sidebar_position: 14 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +Composing gestures is much simpler in RNGH2, you don't need to create a ref for every gesture that depends on another one. Instead you can use `Race`, `Simultaneous` and `Exclusive` methods provided by the `Gesture` object. + +## Race + +Only one of the provided gestures can become active at the same time. The first gesture to become active will cancel the rest of the gestures. It accepts variable number of arguments. +It is the equivalent to having more than one gesture handler without defining `simultaneousHandlers` and `waitFor` props. + +For example, lets say that you have a component that you want to make draggable but you also want to show additional options on long press. Presumably you would not want the component to move after the long press activates. You can accomplish this using `Race`: + +> Note: the `useSharedValue` and `useAnimatedStyle` are part of [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/). + +```js +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, + withTiming, +} from 'react-native-reanimated'; + +function App() { + const offset = useSharedValue({ x: 0, y: 0 }); + const start = useSharedValue({ x: 0, y: 0 }); + const popupPosition = useSharedValue({ x: 0, y: 0 }); + const popupAlpha = useSharedValue(0); + + const animatedStyles = useAnimatedStyle(() => { + return { + transform: [ + { translateX: offset.value.x }, + { translateY: offset.value.y }, + ], + }; + }); + + const animatedPopupStyles = useAnimatedStyle(() => { + return { + transform: [ + { translateX: popupPosition.value.x }, + { translateY: popupPosition.value.y }, + ], + opacity: popupAlpha.value, + }; + }); + + const dragGesture = Gesture.Pan() + .onStart((_e) => { + popupAlpha.value = withTiming(0); + }) + .onUpdate((e) => { + offset.value = { + x: e.translationX + start.value.x, + y: e.translationY + start.value.y, + }; + }) + .onEnd(() => { + start.value = { + x: offset.value.x, + y: offset.value.y, + }; + }); + + const longPressGesture = Gesture.LongPress().onStart((_event) => { + popupPosition.value = { x: offset.value.x, y: offset.value.y }; + popupAlpha.value = withTiming(1); + }); + + const composed = Gesture.Race(dragGesture, longPressGesture); + + return ( + + + + + + + ); +} +``` + +## Simultaneous + +All of the provided gestures can activate at the same time. Activation of one will not cancel the other. +It is the equivalent to having some gesture handlers, each with `simultaneousHandlers` prop set to the other handlers. + +For example, if you want to make a gallery app, you might want user to be able to zoom, rotate and pan around photos. You can do it with `Simultaneous`: + +> Note: the `useSharedValue` and `useAnimatedStyle` are part of [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/). + +```js +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, +} from 'react-native-reanimated'; + +function App() { + const offset = useSharedValue({ x: 0, y: 0 }); + const start = useSharedValue({ x: 0, y: 0 }); + const scale = useSharedValue(1); + const savedScale = useSharedValue(1); + const rotation = useSharedValue(0); + const savedRotation = useSharedValue(0); + const animatedStyles = useAnimatedStyle(() => { + return { + transform: [ + { translateX: offset.value.x }, + { translateY: offset.value.y }, + { scale: scale.value }, + { rotateZ: `${rotation.value}rad` }, + ], + }; + }); + + const dragGesture = Gesture.Pan() + .averageTouches(true) + .onUpdate((e) => { + offset.value = { + x: e.translationX + start.value.x, + y: e.translationY + start.value.y, + }; + }) + .onEnd(() => { + start.value = { + x: offset.value.x, + y: offset.value.y, + }; + }); + + const zoomGesture = Gesture.Pinch() + .onUpdate((event) => { + scale.value = savedScale.value * event.scale; + }) + .onEnd(() => { + savedScale.value = scale.value; + }); + + const rotateGesture = Gesture.Rotation() + .onUpdate((event) => { + rotation.value = savedRotation.value + event.rotation; + }) + .onEnd(() => { + savedRotation.value = rotation.value; + }); + + const composed = Gesture.Simultaneous( + dragGesture, + Gesture.Simultaneous(zoomGesture, rotateGesture) + ); + + return ( + + + + + + ); +} +``` + +## Exclusive + +Only one of the provided gestures can become active, with the first one having a higher priority than the second one (if both gestures are still possible, the second one will wait for the first one to fail before it activates), second one having a higher priority than the third one, and so on. +It is equivalent to having some gesture handlers where the second one has the `waitFor` prop set to the first handler, third one has the `waitFor` prop set to the first and the second one, and so on. + +For example, if you want to make a component that responds to single tap as well as to a double tap, you can accomplish that using `Exclusive`: + +> Note: the `useSharedValue` and `useAnimatedStyle` are part of [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/). + +```js +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + const singleTap = Gesture.Tap().onEnd((_event, success) => { + if (success) { + console.log('single tap!'); + } + }); + const doubleTap = Gesture.Tap() + .numberOfTaps(2) + .onEnd((_event, success) => { + if (success) { + console.log('double tap!'); + } + }); + + const taps = Gesture.Exclusive(doubleTap, singleTap); + + return ( + + + + ); +} +``` + +# Cross-component interactions + +You may have noticed that gesture composition described above requires you to mount all of the composed gestures under a single `GestureDetector`, effectively attaching them to the same underlying component. You can customize how gestures interact with each other across multiple components in a couple of ways: + +## requireExternalGestureToFail + +`requireExternalGestureToFail` allows to delay activation of the handler until all handlers passed as arguments to this method fail (or don't begin at all). + +For example, you may want to have two nested components, both of them can be tapped by the user to trigger different actions: outer view requires one tap, but the inner one requires 2 taps. If you don't want the first tap on the inner view to activate the outer handler, you must make the outer gesture wait until the inner one fails: + +```jsx +import React from 'react'; +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + Gesture, + GestureHandlerRootView, +} from 'react-native-gesture-handler'; + +export default function Example() { + const innerTap = Gesture.Tap() + .numberOfTaps(2) + .onStart(() => { + console.log('inner tap'); + }); + + const outerTap = Gesture.Tap() + .onStart(() => { + console.log('outer tap'); + }) + .requireExternalGestureToFail(innerTap); + + return ( + + + + + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'center', + }, + outer: { + width: 250, + height: 250, + backgroundColor: 'lightblue', + }, + inner: { + width: 100, + height: 100, + backgroundColor: 'blue', + alignSelf: 'center', + }, +}); +``` + +## blocksExternalGesture + +`blocksExternalGesture` works similarly to `requireExternalGestureToFail` but the direction of the relation is reversed - instead of being one-to-many relation, it's many-to-one. It's especially useful for making lists where the `ScrollView` component needs to wait for every gesture underneath it. All that's required to do is to pass a ref, for example: + +```jsx +import React, { useRef } from 'react'; +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + Gesture, + GestureHandlerRootView, + ScrollView, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, + withTiming, +} from 'react-native-reanimated'; + +const ITEMS = ['red', 'green', 'blue', 'yellow']; + +function Item({ backgroundColor, scrollRef }) { + const scale = useSharedValue(1); + const zIndex = useSharedValue(1); + + const pinch = Gesture.Pinch() + .blocksExternalGesture(scrollRef) + .onBegin(() => { + zIndex.value = 100; + }) + .onChange((e) => { + scale.value *= e.scaleChange; + }) + .onFinalize(() => { + scale.value = withTiming(1, undefined, (finished) => { + if (finished) { + zIndex.value = 1; + } + }); + }); + + const animatedStyles = useAnimatedStyle(() => ({ + transform: [{ scale: scale.value }], + zIndex: zIndex.value, + })); + + return ( + + + + ); +} + +export default function Example() { + const scrollRef = useRef(); + + return ( + + + {ITEMS.map((item) => ( + + ))} + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + }, + item: { + flex: 1, + aspectRatio: 1, + }, +}); +``` + +## simultaneousWithExternalGesture + +`simultaneousWithExternalGesture` allows gestures across different components to be recognized simultaneously. For example, you may want to have two nested views, both with tap gesture attached. Both of them require one tap, but tapping the inner one should also activate the gesture attached to the outer view: + +```jsx +import React from 'react'; +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + Gesture, + GestureHandlerRootView, +} from 'react-native-gesture-handler'; + +export default function Example() { + const innerTap = Gesture.Tap().onStart(() => { + console.log('inner tap'); + }); + + const outerTap = Gesture.Tap() + .onStart(() => { + console.log('outer tap'); + }) + .simultaneousWithExternalGesture(innerTap); + + return ( + + + + + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'center', + }, + outer: { + width: 250, + height: 250, + backgroundColor: 'lightblue', + }, + inner: { + width: 100, + height: 100, + backgroundColor: 'blue', + alignSelf: 'center', + }, +}); +``` diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/gesture-detector.md b/packages/docs-gesture-handler/docs/legacy-gestures/gesture-detector.md new file mode 100644 index 0000000000..e1708d63d0 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/gesture-detector.md @@ -0,0 +1,85 @@ +--- +id: gesture-detector +title: GestureDetector +sidebar_label: Gesture detector +sidebar_position: 11 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +import FunctionalComponents from './\_shared/gesture-detector-functional1.md'; + +`GestureDetector` is the main component of the RNGH2. It is responsible for creating and updating native gesture handlers based on the config of provided gesture. The most significant difference between it and old gesture handlers is that the `GestureDetector` can recognize more than one gesture at the time thanks to gesture composition. Keep in mind that `GestureDetector` is not compatible with the [Animated API](https://reactnative.dev/docs/animated), nor with [Reanimated 1](https://docs.swmansion.com/react-native-reanimated/docs/1.x/). + +## Reference + +```javascript +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; + +function App() { + const tap = Gesture.Tap(); + return ( + // highlight-next-line + + + // highlight-next-line + + ); +} +``` + +## Properties + +### `gesture` + +A gesture object containing the configuration and callbacks. Can be any of the base gestures (`Tap`, `Pan`, `LongPress`, `Fling`, `Pinch`, `Rotation`, `ForceTouch`) or any [`ComposedGesture`](./composed-gestures.md) (`Race`, `Simultaneous`, `Exclusive`). + +:::info +GestureDetector will decide whether to use Reanimated to process provided gestures based on callbacks they have. If any of the callbacks is a worklet, tools provided by the Reanimated will be utilized bringing ability to handle gestures synchronously. + +Starting with Reanimated 2.3.0 Gesture Handler will provide a [StateManager](/docs/2.x/gestures/state-manager) in the [touch events](/docs/2.x/gestures/touch-events) that allows for managing the state of the gesture. +::: + +### `userSelect` (Web only) + +This parameter allows to specify which `userSelect` property should be applied to underlying view. Possible values are `"none" | "auto" | "text"`. Default value is set to `"none"`. + +### `touchAction` (Web only) + +This parameter allows to specify which `touchAction` property should be applied to underlying view. Supports all CSS `touch-action` values (e.g. `"none"`, `"pan-y"`). Default value is set to `"none"`. + +### `enableContextMenu(value: boolean)` (Web only) + +Specifies whether context menu should be enabled after clicking on underlying view with right mouse button. Default value is set to `false`. + +## Remarks + +- Gesture Detector will use first native view in its subtree to recognize gestures, however if this view is used only to group its children it may get automatically [collapsed](https://reactnative.dev/docs/view#collapsable-android). Consider this example: + + If we were to remove the collapsable prop from the View, the gesture would stop working because it would be attached to a view that is not present in the view hierarchy. Gesture Detector adds this prop automatically to its direct child but it's impossible to do automatically for more complex view trees. + +- Using the same instance of a gesture across multiple Gesture Detectors is not possible. Have a look at the code below: + + ```jsx + export default function Example() { + const pan = Gesture.Pan(); + + return ( + + + + + {' '} + {/* Don't do this! */} + + + + + + ); + } + ``` + + This example will throw an error, becuse we try to use the same instance of `Pan` in two different Gesture Detectors. diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/gesture.md b/packages/docs-gesture-handler/docs/legacy-gestures/gesture.md new file mode 100644 index 0000000000..ce09ff86eb --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/gesture.md @@ -0,0 +1,101 @@ +--- +id: gesture +title: Gesture +sidebar_label: Gesture +sidebar_position: 12 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +`Gesture` is the object that allows you to create and compose gestures. + +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const tap = Gesture.Tap(); + + return ( + + + + ); +} +``` + +### Gesture.Tap() + +Creates a new instance of [`TapGesture`](/docs/2.x/gestures/tap-gesture) with its default config and no callbacks. + +### Gesture.Pan() + +Creates a new instance of [`PanGesture`](/docs/2.x/gestures/pan-gesture) with its default config and no callbacks. + +### Gesture.LongPress() + +Creates a new instance of [`LongPressGesture`](/docs/2.x/gestures/long-press-gesture) with its default config and no callbacks. + +### Gesture.Fling() + +Creates a new instance of [`FlingGesture`](/docs/2.x/gestures/fling-gesture) with its default config and no callbacks. + +### Gesture.Pinch() + +Creates a new instance of [`PinchGesture`](/docs/2.x/gestures/pinch-gesture) with its default config and no callbacks. + +### Gesture.Rotation() + +Creates a new instance of [`RotationGesture`](/docs/2.x/gestures/rotation-gesture) with its default config and no callbacks. + +### Gesture.Hover() + +Creates a new instance of [`HoverGesture`](/docs/2.x/gestures/hover-gesture) with its default config and no callbacks. + +### Gesture.ForceTouch() + +Creates a new instance of [`ForceTouchGesture`](/docs/2.x/gestures/force-touch-gesture) with its default config and no callbacks. + +### Gesture.Manual() + +Creates a new instance of [`ManualGesture`](/docs/2.x/gestures/manual-gesture) with its default config and no callbacks. + +### Gesture.Native() + +Creates a new instance of [`NativeGesture`](/docs/2.x/gestures/native-gesture) with its default config and no callbacks. + +### Gesture.Race(gesture1, gesture2, gesture3, ...): ComposedGesture + +Creates a gesture composed of those provided as arguments. Only one of those can become active and there are no restrictions to the activation of the gesture. The first one to activate will cancel all the others. + +### Gesture.Simultaneous(gesture1, gesture2, gesture3, ...): ComposedGesture + +Creates a gesture composed of those provided as arguments. All of them can become active without cancelling the others. + +### Gesture.Exclusive(gesture1, gesture2, gesture3, ...): ComposedGesture + +Creates a gesture composed of those provided as arguments. Only one of them can become active, but the first one has a higher priority than the second one, the second one has a higher priority than the third one, and so on. When all gestures are in the `BEGAN` state and the activation criteria for the second one is met, instead of activating it will wait until the first one fails (and only then it will activate) or until the first one activates (and then the second one will get cancelled). It is useful when you want to compose gestures with similar activation criteria (e.g. single and double tap at the same component, without Exclusive the single tap would activate every time user taps thus cancelling the double tap). + +## Remarks + +- Consider wrapping your gesture configurations with `useMemo`, as it will reduce the amount of work Gesture Handler has to do under the hood when updating gestures. For example: + +```jsx +import React from 'react'; + +function App() { + const gesture = React.useMemo( + () => + Gesture.Tap().onStart(() => { + console.log('Number of taps:', tapNumber + 1); + setTapNumber((value) => value + 1); + }), + [tapNumber, setTapNumber] + ); + // ... +} +``` diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/hover-gesture.md b/packages/docs-gesture-handler/docs/legacy-gestures/hover-gesture.md new file mode 100644 index 0000000000..92dd00604d --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/hover-gesture.md @@ -0,0 +1,125 @@ +--- +id: hover-gesture +title: Hover gesture +sidebar_label: Hover gesture +sidebar_position: 6 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import HoverGestureBasic from '@site/static/examples/HoverGestureBasic'; +import HoverGestureBasicSrc from '!!raw-loader!@site/static/examples/HoverGestureBasic'; + +
+
+ +
+ } + src={HoverGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinuousEventCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; + +A continuous gesture that can recognize hovering above the view it's attached to. The hover effect may be activated by moving a mouse or a stylus over the view. + +On iOS additional visual effects may be configured. + +
+ +
+ +Hover Gesture + +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const hover = Gesture.Hover(); + + return ( + + + + ); +} +``` + +## Remarks + +- Don't rely on `Hover` gesture to continue after the mouse button is clicked or the stylus touches the screen. If you want to handle both cases, [compose](/docs/2.x/fundamentals/gesture-composition) it with [`Pan` gesture](/docs/2.x/gestures/pan-gesture). + +## Config + +### Properties specific to `HoverGesture`: + +### `effect(effect: HoverEffect)` (iOS only) + +```js +import { HoverEffect } from 'react-native-gesture-handler'; +``` + +Visual effect applied to the view while the view is hovered. The possible values are: + +- `HoverEffect.None` +- `HoverEffect.Lift` +- `HoverEffect.Highlight` + +Defaults to `HoverEffect.None` + + + +## Callbacks + + + + +## Event data + +### Event attributes specific to `HoverGesture`: + +### `x` + +X coordinate of the current position of the pointer relative to the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector). Expressed in point units. + +### `y` + +Y coordinate of the current position of the pointer relative to the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector). Expressed in point units. + +### `absoluteX` + +X coordinate of the current position of the pointer relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#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 pointer relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. + +### `stylusData` + +Object that contains additional information about `stylus`. It consists of the following fields: + +- [`tiltX`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/tiltX) - angle in degrees between the Y-Z plane of the stylus and the screen. +- [`tiltY`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/tiltY) - angle in degrees between the X-Z plane of the stylus and the screen. +- [`altitudeAngle`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/altitudeAngle) - angle between stylus axis and the X-Y plane of a device screen. +- [`azimuthAngle`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/azimuthAngle) - angle between the Y-Z plane and the plane containing both the stylus axis and the Y axis. +- [`pressure`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/pressure) - indicates the normalized pressure of the stylus. + + diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/long-press-gesture.md b/packages/docs-gesture-handler/docs/legacy-gestures/long-press-gesture.md new file mode 100644 index 0000000000..43315a239f --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/long-press-gesture.md @@ -0,0 +1,135 @@ +--- +id: long-press-gesture +title: Long press gesture +sidebar_label: Long press gesture +sidebar_position: 3 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import LongPressGestureBasic from '@site/static/examples/LongPressGestureBasic'; +import LongPressGestureBasicSrc from '!!raw-loader!@site/static/examples/LongPressGestureBasic'; + +
+
+ +
+ } + src={LongPressGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; + +A discrete gesture that activates when the corresponding view is pressed for a sufficiently long time. +This gesture's state will turn into [END](/docs/2.x/fundamentals/states-events#end) immediately after the finger is released. +The gesture will fail to recognize a touch event if the finger is lifted before the [minimum required time](/docs/2.x/gestures/long-press-gesture#mindurationvalue-number) or if the finger is moved further than the [allowable distance](/docs/2.x/gestures/long-press-gesture#maxdistancevalue-number). + +
+ +
+ +Long Press Gesture + +## Example + +```jsx +import { View, StyleSheet } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; + +export default function App() { + // highlight-next-line + const longPressGesture = Gesture.LongPress().onEnd((e, success) => { + if (success) { + console.log(`Long pressed for ${e.duration} ms!`); + } + }); + + return ( + + + + ); +} + +const styles = StyleSheet.create({ + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Config + +### Properties specific to `LongPressGesture`: + +### `minDuration(value: number)` + +Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. + +### `maxDistance(value: number)` + +Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](/docs/2.x/fundamentals/states-events#active), it will fail to recognize the gesture. The default value is 10. + +### `mouseButton(value: MouseButton)` (Web & Android only) + +Allows users to choose which mouse button should handler respond to. The enum `MouseButton` consists of the following predefined fields: + +- `LEFT` +- `RIGHT` +- `MIDDLE` +- `BUTTON_4` +- `BUTTON_5` +- `ALL` + +Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Default value is set to `MouseButton.LEFT`. + + + +## Callbacks + + + +## Event data + +### Event attributes specific to `LongPressGesture`: + +### `x` + +X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector). + +### `y` + +Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector). + +### `absoluteX` + +X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector) can be transformed as an effect of the gesture. + +### `absoluteY` + +Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector) can be transformed as an effect of the gesture. + +### `duration` + +Duration of the long press (time since the start of the gesture), expressed in milliseconds. + + diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/manual-gesture.md b/packages/docs-gesture-handler/docs/legacy-gestures/manual-gesture.md new file mode 100644 index 0000000000..fb2dfdfb7a --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/manual-gesture.md @@ -0,0 +1,47 @@ +--- +id: manual-gesture +title: Manual gesture +sidebar_label: Manual gesture +sidebar_position: 9 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinuousEventCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; + +A plain gesture that has no specific activation criteria nor event data set. Its state has to be controlled manually using a [state manager](/docs/2.x/gestures/state-manager). It will not fail when all the pointers are lifted from the screen. + +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const manual = Gesture.Manual(); + + return ( + + + + ); +} +``` + +## Config + + + +## Callbacks + + + + +## Event data + + diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/native-gesture.md b/packages/docs-gesture-handler/docs/legacy-gestures/native-gesture.md new file mode 100644 index 0000000000..9764127837 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/native-gesture.md @@ -0,0 +1,103 @@ +--- +id: native-gesture +title: Native gesture +sidebar_label: Native gesture +sidebar_position: 8 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinuousEventCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; + +A gesture that allows other touch handling components to work within RNGH's gesture system. This streamlines interactions between gestures and the native component, allowing it to form [relations](/docs/2.x/fundamentals/gesture-composition) with other gestures. + +When used, the native component should be the direct child of a `GestureDetector`. + +## Example + +This example renders a `ScrollView` with multiple colored rectangles, where each rectangle has a black section. Starting a touch on a black section will disable the `ScrollView` for the duration of the `Pan` gesture. + +```jsx +import { View, ScrollView } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; + +const COLORS = ['red', 'green', 'blue', 'purple', 'orange', 'cyan']; + +export default function App() { + // highlight-next-line + const native = Gesture.Native(); + + return ( + + + + + + ); +} + +function ScrollableContent({ scrollGesture }) { + return ( + + {COLORS.map((color) => ( + + ))} + + ); +} + +function Rectangle({ color, scrollGesture }) { + const pan = Gesture.Pan().blocksExternalGesture(scrollGesture); + + return ( + + + + + + ); +} +``` + +## Remarks + +- `Native` gesture can be used as part of [gesture composition and cross-component interactions](/docs/2.x/fundamentals/gesture-composition) just like any other gesture. You can use this to block a native component for the duration of the gesture or to make it work alongside a gesture. + +:::danger +Do not use `Native` gesture with components exported by React Native Gesture Handler. Those come with a native gesture handler preapplied. Attaching a native gesture twice will likely result in the components not working as intended. +::: + +## Config + +### Properties specific to `NativeGesture`: + +### `shouldActivateOnStart(value: boolean)` (**Android only**) + +When `true`, underlying handler will activate unconditionally when it receives any touches in [`BEGAN`](/docs/2.x/fundamentals/states-events#began) or [`UNDETERMINED`](/docs/2.x/fundamentals/states-events#undetermined) state. + +### `disallowInterruption(value: boolean)` + +When `true`, cancels all other gesture handlers when this `NativeViewGestureHandler` changes its state to [`ACTIVE`](/docs/2.x/fundamentals/states-events#active). + + + +## Callbacks + + + +## Event data + +### Event attributes specific to `NativeGesture`: + +### `pointerInside` + +True if gesture was performed inside of containing view, false otherwise. + + diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/pan-gesture.md b/packages/docs-gesture-handler/docs/legacy-gestures/pan-gesture.md new file mode 100644 index 0000000000..8cee2377c2 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/pan-gesture.md @@ -0,0 +1,248 @@ +--- +id: pan-gesture +title: Pan gesture +sidebar_label: Pan gesture +sidebar_position: 1 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import PanGestureBasic from '@site/static/examples/PanGestureBasic'; +import PanGestureBasicSrc from '!!raw-loader!@site/static/examples/PanGestureBasicSrc'; + +
+
+ +
+ } + src={PanGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseContinuousEventConfig from './\_shared/base-continuous-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinuousEventCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; + +A continuous gesture that can recognize a panning (dragging) gesture and track its movement. + +The gesture [activates](/docs/2.x/fundamentals/states-events#active) when a finger is placed on the screen and moved some initial distance. + +Configurations such as a minimum initial distance, specific vertical or horizontal pan detection and [number of fingers](/docs/2.x/gestures/pan-gesture#minpointersvalue-number) required for activation (allowing for multifinger swipes) may be specified. + +Gesture callback can be used for continuous tracking of the pan gesture. It provides information about the gesture such as its XY translation from the starting point as well as its instantaneous velocity. + +
+ +
+ +Pan Gesture + +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + withTiming, + useAnimatedStyle, +} from 'react-native-reanimated'; + +const END_POSITION = 200; + +export default function App() { + const onLeft = useSharedValue(true); + const position = useSharedValue(0); + + // highlight-next-line + const panGesture = Gesture.Pan() + .onUpdate((e) => { + if (onLeft.value) { + position.value = e.translationX; + } else { + position.value = END_POSITION + e.translationX; + } + }) + .onEnd((e) => { + if (position.value > END_POSITION / 2) { + position.value = withTiming(END_POSITION, { duration: 100 }); + onLeft.value = false; + } else { + position.value = withTiming(0, { duration: 100 }); + onLeft.value = true; + } + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ translateX: position.value }], + })); + + return ( + // highlight-next-line + + + + ); +} + +const styles = StyleSheet.create({ + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Multi touch pan handling + +If your app relies on multi touch pan handling this section provides some information how the default behavior differs between the platform and how (if necessary) it can be unified. + +The difference in multi touch pan handling lies in the way how translation properties during the event are being calculated. +On iOS the default behavior when more than one finger is placed on the screen is to treat this situation as if only one pointer was placed in the center of mass (average position of all the pointers). +This applies also to many platform native components that handle touch even if not primarily interested in multi touch interactions like for example UIScrollView component. + +On Android, the default behavior for native components like scroll view, pager views or drawers is different and hence gesture defaults to that when it comes to pan handling. +The difference is that instead of treating the center of mass of all the fingers placed as a leading pointer it takes the latest placed finger as such. +This behavior can be changed on Android using [`averageTouches`](#averagetouchesvalue-boolean-android-only) flag. + +Note that on both Android and iOS when the additional finger is placed on the screen that translation prop is not affected even though the position of the pointer being tracked might have changed. +Therefore it is safe to rely on translation most of the time as it only reflects the movement that happens regardless of how many fingers are placed on the screen and if that number changes over time. +If you wish to track the "center of mass" virtual pointer and account for its changes when the number of finger changes you can use relative or absolute position provided in the event ([`x`](#x) and [`y`](#y) or [`absoluteX`](#absolutex) and [`absoluteY`](#absolutey)). + +## Config + +### Properties specific to `PanGesture`: + +### `minDistance(value: number)` + +Minimum distance the finger (or multiple finger) need to travel before the gesture [activates](/docs/2.x/fundamentals/states-events#active). Expressed in points. + +### `minPointers(value: number)` + +A number of fingers that is required to be placed before gesture can [activate](/docs/2.x/fundamentals/states-events#active). Should be a higher or equal to 0 integer. + +### `maxPointers(value: number)` + +When the given number of fingers is placed on the screen and gesture hasn't yet [activated](/docs/2.x/fundamentals/states-events#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. + +### `activateAfterLongPress(duration: number)` + +Duration in milliseconds of the `LongPress` gesture before `Pan` is allowed to [activate](/docs/2.x/fundamentals/states-events#active). If the finger is moved during that period, the gesture will [fail](/docs/2.x/fundamentals/states-events#failed). Should be a higher or equal to 0 integer. Default value is 0, meaning no `LongPress` is required to [activate](/docs/2.x/fundamentals/states-events#active) the `Pan`. + +### `activeOffsetX(value: number | number[])` + +Range along X axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. +If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. +If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. + +### `activeOffsetY(value: number | number[])` + +Range along Y axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. +If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. +If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. + +### `failOffsetY(value: number | number[])` + +When the finger moves outside this range (in points) along Y axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. +If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. +If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. + +### `failOffsetX(value: number | number[])` + +When the finger moves outside this range (in points) along X axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. +If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. +If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. + +### `averageTouches(value: boolean)` (Android only) + +Android, by default, will calculate translation values based on the position of the leading pointer (the first one that was placed on the screen). This modifier allows that behavior to be changed to the one that is default on iOS - the averaged position of all active pointers will be used to calculate the translation values. + +### `enableTrackpadTwoFingerGesture(value: boolean)` (iOS only) + +Enables two-finger gestures on supported devices, for example iPads with trackpads. If not enabled the gesture will require click + drag, with enableTrackpadTwoFingerGesture swiping with two fingers will also trigger the gesture. + +### `mouseButton(value: MouseButton)` (Web & Android only) + +Allows users to choose which mouse button should handler respond to. The enum `MouseButton` consists of the following predefined fields: + +- `LEFT` +- `RIGHT` +- `MIDDLE` +- `BUTTON_4` +- `BUTTON_5` +- `ALL` + +Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Default value is set to `MouseButton.LEFT`. + + + + +## Callbacks + + + + +## Event data + +### Event attributes specific to `PanGesture`: + +### `translationX` + +Translation of the pan gesture along X axis accumulated over the time of the gesture. The value is expressed in the point units. + +### `translationY` + +Translation of the pan gesture along Y axis accumulated over the time of the gesture. The value is expressed in the point units. + +### `velocityX` + +Velocity of the pan gesture along the X axis in the current moment. The value is expressed in point units per second. + +### `velocityY` + +Velocity of the pan gesture along the Y axis in the current moment. The value is expressed in point units per second. + +### `x` + +X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector). Expressed in point units. + +### `y` + +Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector). Expressed in point units. + +### `absoluteX` + +X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#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 pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. + +### `stylusData` + +Object that contains additional information about `stylus`. It consists of the following fields: + +- [`tiltX`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/tiltX) - angle in degrees between the Y-Z plane of the stylus and the screen. +- [`tiltY`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/tiltY) - angle in degrees between the X-Z plane of the stylus and the screen. +- [`altitudeAngle`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/altitudeAngle) - angle between stylus axis and the X-Y plane of a device screen. +- [`azimuthAngle`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/azimuthAngle) - angle between the Y-Z plane and the plane containing both the stylus axis and the Y axis. +- [`pressure`](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/pressure) - indicates the normalized pressure of the stylus. + + diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/pinch-gesture.md b/packages/docs-gesture-handler/docs/legacy-gestures/pinch-gesture.md new file mode 100644 index 0000000000..1010a2a4ec --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/pinch-gesture.md @@ -0,0 +1,134 @@ +--- +id: pinch-gesture +title: Pinch gesture +sidebar_label: Pinch gesture +sidebar_position: 5 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import PinchGestureBasic from '@site/static/examples/PinchGestureBasic'; +import PinchGestureBasicSrc from '!!raw-loader!@site/static/examples/PinchGestureBasicSrc'; + +
+
+ +
+ } + src={PinchGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseContinuousEventConfig from './\_shared/base-continuous-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinuousEventCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; + +A continuous gesture that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. +The gesture [activates](/docs/2.x/fundamentals/states-events#active) when fingers are placed on the screen and change their position. +Gesture callback can be used for continuous tracking of the pinch gesture. It provides information about velocity, anchor (focal) point of gesture and scale. + +The distance between the fingers is reported as a scale factor. At the beginning of the gesture, the scale factor is 1.0. As the distance between the two fingers increases, the scale factor increases proportionally. +Similarly, the scale factor decreases as the distance between the fingers decreases. +Pinch gestures are used most commonly to change the size of objects or content onscreen. +For example, map views use pinch gestures to change the zoom level of the map. + +
+ +
+ +Pinch Gesture + +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, +} from 'react-native-reanimated'; + +export default function App() { + const scale = useSharedValue(1); + const savedScale = useSharedValue(1); + + // highlight-next-line + const pinchGesture = Gesture.Pinch() + .onUpdate((e) => { + scale.value = savedScale.value * e.scale; + }) + .onEnd(() => { + savedScale.value = scale.value; + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ scale: scale.value }], + })); + + return ( + + + + ); +} + +const styles = StyleSheet.create({ + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Remarks + +- When implementing pinch based on `focal` point, make sure to use it after gesture has activated, i.e. in `onStart`, `onUpdate` or `onChange` callbacks. Using it in `onBegan` may lead to unexpected behavior. + +## Config + + + + +## Callbacks + + + + +## Event data + +### Event attributes specific to `PinchGesture`: + +### `scale` + +The scale factor relative to the points of the two touches in screen coordinates. + +### `velocity` + +Velocity of the pan gesture the current moment. The value is expressed in scale factor per second. + +### `focalX` + +Position expressed in points along X axis of center anchor point of gesture + +### `focalY` + +Position expressed in points along Y axis of center anchor point of gesture + + diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/rotation-gesture.md b/packages/docs-gesture-handler/docs/legacy-gestures/rotation-gesture.md new file mode 100644 index 0000000000..ac6b4bcb2d --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/rotation-gesture.md @@ -0,0 +1,131 @@ +--- +id: rotation-gesture +title: Rotation gesture +sidebar_label: Rotation gesture +sidebar_position: 4 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import RotationGestureBasic from '@site/static/examples/RotationGestureBasic'; +import RotationGestureBasicSrc from '!!raw-loader!@site/static/examples/RotationGestureBasicSrc'; + +
+
+ +
+ } + src={RotationGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseContinuousEventConfig from './\_shared/base-continuous-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinuousEventCallbacks from './\_shared/base-continuous-gesture-callbacks.md'; + +A continuous gesture that can recognize a rotation gesture and track its movement. + +The gesture [activates](/docs/2.x/fundamentals/states-events#active) when fingers are placed on the screen and change position in a proper way. + +Gesture callback can be used for continuous tracking of the rotation gesture. It provides information about the gesture such as the amount rotated, the focal point of the rotation (anchor), and its instantaneous velocity. + +
+ +
+ +Rotation Gesture + +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, +} from 'react-native-reanimated'; + +export default function App() { + const rotation = useSharedValue(1); + const savedRotation = useSharedValue(1); + + // highlight-next-line + const rotationGesture = Gesture.Rotation() + .onUpdate((e) => { + rotation.value = savedRotation.value + e.rotation; + }) + .onEnd(() => { + savedRotation.value = rotation.value; + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ rotateZ: `${(rotation.value / Math.PI) * 180}deg` }], + })); + + return ( + + + + ); +} + +const styles = StyleSheet.create({ + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Remarks + +- When implementing rotation based on `anchor` point, make sure to use it after gesture has activated, i.e. in `onStart`, `onUpdate` or `onChange` callbacks. Using it in `onBegan` may lead to unexpected behavior. + +## Config + + + + +## Callbacks + + + + +## Event data + +### Event attributes specific to `RotationGesture`: + +### `rotation` + +Amount rotated, expressed in radians, from the gesture's focal point (anchor). + +### `velocity` + +Instantaneous velocity, expressed in point units per second, of the gesture. + +### `anchorX` + +X coordinate, expressed in points, of the gesture's central focal point (anchor). + +### `anchorY` + +Y coordinate, expressed in points, of the gesture's central focal point (anchor). + + diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/state-manager.md b/packages/docs-gesture-handler/docs/legacy-gestures/state-manager.md new file mode 100644 index 0000000000..7494cb8c25 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/state-manager.md @@ -0,0 +1,31 @@ +--- +id: state-manager +title: Gesture state manager +sidebar_label: Gesture state manager +sidebar_position: 15 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +`GestureStateManager` allows to manually control the state of the gestures. Please note that `react-native-reanimated` is required to use it, since it allows for synchronously executing methods in worklets. + +## Methods + +### `begin()` + +Transition the gesture to the [`BEGAN`](/docs/2.x/fundamentals/states-events#began) state. This method will have no effect if the gesture has already activated or finished. + +### `activate()` + +Transition the gesture to the [`ACTIVE`](/docs/2.x/fundamentals/states-events#active) state. This method will have no effect if the handler is already active, or has finished. +If the gesture is [`exclusive`](/docs/2.x/fundamentals/gesture-composition) with another one, the activation will be delayed until the gesture with higher priority fails. + +### `end()` + +Transition the gesture to the [`END`](/docs/2.x/fundamentals/states-events#end) state. This method will have no effect if the handler has already finished. + +### `fail()` + +Transition the gesture to the [`FAILED`](/docs/2.x/fundamentals/states-events#failed) state. This method will have no effect if the handler has already finished. diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/tap-gesture.md b/packages/docs-gesture-handler/docs/legacy-gestures/tap-gesture.md new file mode 100644 index 0000000000..ba7bc690e0 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/tap-gesture.md @@ -0,0 +1,164 @@ +--- +id: tap-gesture +title: Tap gesture +sidebar_label: Tap gesture +sidebar_position: 2 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +import { vanishOnMobile, appearOnMobile, webContainer } from '@site/src/utils/getGestureStyles'; + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +import TapGestureBasic from '@site/static/examples/TapGestureBasic'; +import TapGestureBasicSrc from '!!raw-loader!@site/static/examples/TapGestureBasic'; + +
+
+ +
+ } + src={TapGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; + +A discrete gesture that recognizes one or many taps. + +Tap gestures detect one or more fingers briefly touching the screen. +The fingers involved in these gestures must not move significantly from their initial touch positions. +The required number of taps and allowed distance from initial position may be configured. +For example, you might configure tap gesture recognizers to detect single taps, double taps, or triple taps. + +In order for a gesture to [activate](/docs/2.x/fundamentals/states-events#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDuration, and maxDelayMs (explained below) must be met. Immediately after the gesture [activates](/docs/2.x/fundamentals/states-events#active), it will [end](/docs/2.x/fundamentals/states-events#end). + +
+ +
+ +Tap Gesture + +## Example + +```jsx +import { View, StyleSheet } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; + +export default function App() { + // highlight-next-line + const singleTap = Gesture.Tap() + .maxDuration(250) + .onStart(() => { + console.log('Single tap!'); + }); + + // highlight-next-line + const doubleTap = Gesture.Tap() + .maxDuration(250) + .numberOfTaps(2) + .onStart(() => { + console.log('Double tap!'); + }); + + return ( + + + + ); +} + +const styles = StyleSheet.create({ + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Config + +### Properties specific to `TapGesture`: + +### `minPointers(value: number)` + +Minimum number of pointers (fingers) required to be placed before the gesture [activates](/docs/2.x/fundamentals/states-events#active). Should be a positive integer. The default value is 1. + +### `maxDuration(value: number)` + +Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch. The default value is 500. + +### `maxDelay(value: number)` + +Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required. The default value is 500. + +### `numberOfTaps(value: number)` + +Number of tap gestures required to [activate](/docs/2.x/fundamentals/states-events#active) the gesture. The default value is 1. + +### `maxDeltaX(value: number)` + +Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the X axis during a tap gesture. If the finger travels further than the defined distance along the X axis and the gesture hasn't yet [activated](/docs/2.x/fundamentals/states-events#active), it will fail to recognize the gesture. + +### `maxDeltaY(value: number)` + +Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the Y axis during a tap gesture. If the finger travels further than the defined distance along the Y axis and the gesture hasn't yet [activated](/docs/2.x/fundamentals/states-events#active), it will fail to recognize the gesture. + +### `maxDistance(value: number)` + +Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a tap gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](/docs/2.x/fundamentals/states-events#active), it will fail to recognize the gesture. + +### `mouseButton(value: MouseButton)` (Web & Android only) + +Allows users to choose which mouse button should handler respond to. The enum `MouseButton` consists of the following predefined fields: + +- `LEFT` +- `RIGHT` +- `MIDDLE` +- `BUTTON_4` +- `BUTTON_5` +- `ALL` + +Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`. Default value is set to `MouseButton.LEFT`. + + + +## Callbacks + + + +## Event data + +### Event attributes specific to `TapGesture`: + +### `x` + +X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector). + +### `y` + +Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector). + +### `absoluteX` + +X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector) can be transformed as an effect of the gesture. + +### `absoluteY` + +Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector) can be transformed as an effect of the gesture. + + diff --git a/packages/docs-gesture-handler/docs/legacy-gestures/touch-events.md b/packages/docs-gesture-handler/docs/legacy-gestures/touch-events.md new file mode 100644 index 0000000000..79136fe5e4 --- /dev/null +++ b/packages/docs-gesture-handler/docs/legacy-gestures/touch-events.md @@ -0,0 +1,54 @@ +--- +id: touch-events +title: Touch events +sidebar_label: Touch events +sidebar_position: 16 +--- + +import OldAPIInfo from './\_shared/v2-info.md' + + + +### Touch event attributes: + +### `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. + +:::caution +Don't rely on the order of items in the `touches` as it may change during the gesture, instead use the `id` attribute to track individual touches across events. +::: + +### PointerData attributes: + +### `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`](/docs/2.x/gestures/gesture-detector). Expressed in point units. + +### `y` + +Y coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](/docs/2.x/gestures/gesture-detector). 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`](#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`](#y) in cases when the original view can be transformed as an effect of the gesture. diff --git a/packages/docs-gesture-handler/docusaurus.config.js b/packages/docs-gesture-handler/docusaurus.config.js index e99e54b4a8..ebca894dc4 100644 --- a/packages/docs-gesture-handler/docusaurus.config.js +++ b/packages/docs-gesture-handler/docusaurus.config.js @@ -7,6 +7,8 @@ const darkCodeTheme = require('./src/theme/CodeBlock/highlighting-dark.js'); // @ts-check const webpack = require('webpack'); +const redirectsData = require('./redirects.json'); + /** @type {import('@docusaurus/types').Config} */ const config = { title: 'React Native Gesture Handler', @@ -133,9 +135,15 @@ const config = { }, ], ].filter(Boolean), - async function reanimatedDocusaurusPlugin(context, options) { + [ + '@docusaurus/plugin-client-redirects', + { + redirects: redirectsData.redirects, + }, + ], + async function gestureHandlerDocusaurusPlugin(context, options) { return { - name: 'react-native-reanimated/docusaurus-plugin', + name: 'react-native-gesture-handler/docusaurus-plugin', configureWebpack(config, isServer, utils) { const processMock = !isServer ? { process: { env: {} } } : {}; diff --git a/packages/docs-gesture-handler/package.json b/packages/docs-gesture-handler/package.json index 74b3cb0c83..47629f552d 100644 --- a/packages/docs-gesture-handler/package.json +++ b/packages/docs-gesture-handler/package.json @@ -23,6 +23,7 @@ "@babel/preset-react": "^7.18.6", "@babel/preset-typescript": "^7.21.0", "@docusaurus/core": "3.7.0", + "@docusaurus/plugin-client-redirects": "3.7.0", "@docusaurus/plugin-debug": "3.7.0", "@docusaurus/plugin-google-tag-manager": "3.7.0", "@docusaurus/preset-classic": "3.7.0", diff --git a/packages/docs-gesture-handler/redirects.json b/packages/docs-gesture-handler/redirects.json new file mode 100644 index 0000000000..201acf3283 --- /dev/null +++ b/packages/docs-gesture-handler/redirects.json @@ -0,0 +1,52 @@ +{ + "redirects": [ + { + "to": "/docs/legacy-gestures/pan-gesture", + "from": "/docs/gestures/pan-gesture" + }, + { + "to": "/docs/legacy-gestures/tap-gesture", + "from": "/docs/gestures/tap-gesture" + }, + { + "to": "/docs/legacy-gestures/long-press-gesture", + "from": "/docs/gestures/long-press-gesture" + }, + { + "to": "/docs/legacy-gestures/rotation-gesture", + "from": "/docs/gestures/rotation-gesture" + }, + { + "to": "/docs/legacy-gestures/pinch-gesture", + "from": "/docs/gestures/pinch-gesture" + }, + { + "to": "/docs/legacy-gestures/fling-gesture", + "from": "/docs/gestures/fling-gesture" + }, + { + "to": "/docs/legacy-gestures/hover-gesture", + "from": "/docs/gestures/hover-gesture" + }, + { + "to": "/docs/legacy-gestures/native-gesture", + "from": "/docs/gestures/native-gesture" + }, + { + "to": "/docs/legacy-gestures/manual-gesture", + "from": "/docs/gestures/manual-gesture" + }, + { + "to": "/docs/legacy-gestures/force-touch-gesture", + "from": "/docs/gestures/force-touch-gesture" + }, + { + "to": "/docs/2.x/guides/upgrading-to-2", + "from": "/docs/guides/upgrading-to-2" + }, + { + "to": "/docs/fundamentals/gesture-detectors", + "from": "/docs/gestures/gesture-detector" + } + ] +} diff --git a/packages/docs-gesture-handler/yarn.lock b/packages/docs-gesture-handler/yarn.lock index 2f646084e0..d39ee667c8 100644 --- a/packages/docs-gesture-handler/yarn.lock +++ b/packages/docs-gesture-handler/yarn.lock @@ -1763,6 +1763,21 @@ react-helmet-async "npm:@slorber/react-helmet-async@*" react-loadable "npm:@docusaurus/react-loadable@6.0.0" +"@docusaurus/plugin-client-redirects@3.7.0": + version "3.7.0" + resolved "https://registry.yarnpkg.com/@docusaurus/plugin-client-redirects/-/plugin-client-redirects-3.7.0.tgz#b5cf92529768c457c01ad350bfc50862c6149463" + integrity sha512-6B4XAtE5ZVKOyhPgpgMkb7LwCkN+Hgd4vOnlbwR8nCdTQhLjz8MHbGlwwvZ/cay2SPNRX5KssqKAlcHVZP2m8g== + dependencies: + "@docusaurus/core" "3.7.0" + "@docusaurus/logger" "3.7.0" + "@docusaurus/utils" "3.7.0" + "@docusaurus/utils-common" "3.7.0" + "@docusaurus/utils-validation" "3.7.0" + eta "^2.2.0" + fs-extra "^11.1.1" + lodash "^4.17.21" + tslib "^2.6.0" + "@docusaurus/plugin-content-blog@3.7.0": version "3.7.0" resolved "https://registry.yarnpkg.com/@docusaurus/plugin-content-blog/-/plugin-content-blog-3.7.0.tgz#7bd69de87a1f3adb652e1473ef5b7ccc9468f47e"