diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml index 109cbec317..064990d766 100644 --- a/.github/workflows/docs-check.yml +++ b/.github/workflows/docs-check.yml @@ -25,7 +25,6 @@ jobs: uses: actions/setup-node@v6 with: node-version: 24 - cache: yarn - name: Install node dependencies working-directory: ${{ env.WORKING_DIRECTORY }} diff --git a/packages/docs-gesture-handler/docs/components/buttons.mdx b/packages/docs-gesture-handler/docs/components/buttons.mdx index e20bff3256..bd3f360c0c 100644 --- a/packages/docs-gesture-handler/docs/components/buttons.mdx +++ b/packages/docs-gesture-handler/docs/components/buttons.mdx @@ -19,7 +19,7 @@ Currently Gesture handler library exposes three components that render native to - [`RectButton`](/docs/components/buttons/#rectbutton) - [`BorderlessButton`](/docs/components/buttons/#borderlessbutton) -On top of that all the buttons are wrapped with `NativeViewGestureHandler` and therefore allow for all the [common gesture handler properties](/docs/gesture-handlers/common-gh/) and `NativeViewGestureHandler`'s [extra properties](/docs/gesture-handlers/nativeview-gh#properties) to be applied to them. +On top of that all the buttons are wrapped with `NativeViewGestureHandler` and therefore allow for all the [common gesture handler properties](/docs/gestures/use-native-gesture#properties-common-to-all-gestures) and `NativeViewGestureHandler`'s [extra properties](/docs/gestures/use-native-gesture#properties-specific-to-nativegesture) to be applied to them. **IMPORTANT**: In order to make buttons accessible, you have to wrap your children in a `View` with `accessible` and `accessibilityRole="button"` props. Example: diff --git a/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-callbacks.mdx b/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-callbacks.mdx new file mode 100644 index 0000000000..3ccef9036b --- /dev/null +++ b/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-callbacks.mdx @@ -0,0 +1,13 @@ +import CodeBlock from '@theme/CodeBlock'; + +### Callbacks common to all continuous gestures: + +### onUpdate + +{ + + {`onUpdate: (event: ${props.gesture}HandlerData) => void`} + +} + +Set the callback that is being called every time the gesture receives an update while it's active. diff --git a/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-config.md b/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-config.md index 71ca8db252..af148874b5 100644 --- a/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-config.md +++ b/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-config.md @@ -1,5 +1,9 @@ ### Properties common to all continuous gestures: -### `manualActivation(value: boolean)` +### manualActivation + +```ts +manualActivation: boolean | SharedValue; +``` 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/gestures/state-manager/). diff --git a/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-callbacks.mdx b/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-callbacks.mdx new file mode 100644 index 0000000000..8872630dfc --- /dev/null +++ b/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-callbacks.mdx @@ -0,0 +1,75 @@ +import CodeBlock from '@theme/CodeBlock'; + +### Callbacks common to all gestures: + +### onBegin + +{ + + {`onBegin: (event: ${props.gesture}HandlerData) => void`} + +} + +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. + +### onActivate + +{ + + {`onActivate: (event: ${props.gesture}HandlerData) => void`} + +} + +Set the callback that is being called when the gesture is recognized by the handler and it transitions to the active state. + +### onDeactivate + +{ + + {`onDeactivate: (event: ${props.gesture}HandlerData, didSucceed: boolean) => void`} + +} + +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 + +{ + + {`onFinalize: (event: ${props.gesture}HandlerData, didSucceed: boolean) => void`} + +} + +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 + +```ts +onTouchesDown: (event: GestureTouchEvent) => void +``` + +Set the `onTouchesDown` callback which is called every time a finger is placed on the screen. + +### onTouchesMove + +```ts +onTouchesMove: (event: GestureTouchEvent) => void +``` + +Set the `onTouchesMove` callback which is called every time a finger is moved on the screen. + +### onTouchesUp + +```ts +onTouchesUp: (event: GestureTouchEvent) => void +``` + +Set the `onTouchesUp` callback which is called every time a finger is lifted from the screen. + +### onTouchesCancel + +```ts +onTouchesCancel: (event: GestureTouchEvent) => void +``` + +Set the `onTouchesCancel` 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/gestures/_shared/base-gesture-config.md b/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-config.md index 2e2fb6d425..4c59d2a4ab 100644 --- a/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-config.md +++ b/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-config.md @@ -1,19 +1,48 @@ ### Properties common to all gestures: -### `enabled(value: boolean)` +### enabled + +```ts +enabled: boolean | SharedValue; +``` 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/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/fundamentals/states-events#failed) or [`CANCELLED`](/docs/fundamentals/states-events#cancelled) (depending on its current state). Default value is `true`. -### `shouldCancelWhenOutside(value: boolean)` +### shouldCancelWhenOutside + +```ts +shouldCancelWhenOutside: boolean | SharedValue; +``` When `true` the handler will [cancel](/docs/fundamentals/states-events#cancelled) or [fail](/docs/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/gestures/long-press-gesture) and [`TapGesture`](/docs/gestures/tap-gesture) which default to `true`. - -### `hitSlop(settings)` +Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGesture`](/docs/gestures/use-long-press-gesture) and [`TapGesture`](/docs/gestures/use-tap-gesture) which default to `true`. + +### hitSlop + +```ts +hitSlop: HitSlop | SharedValue; +``` + +```ts +type HitSlop = + | number + | null + | undefined + | Partial< + Record< + 'left' | 'right' | 'top' | 'bottom' | 'vertical' | 'horizontal', + number + > + > + | Record<'width' | 'left', number> + | Record<'width' | 'right', number> + | Record<'height' | 'top', number> + | Record<'height' | 'bottom', number>; +``` This parameter enables control over what part of the connected view area can be used to [begin](/docs/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. @@ -27,42 +56,65 @@ Specifying `width` or `height` is useful if we only want the gesture to activate **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)` +### testID -Sets a ref to the gesture object, allowing for interoperability with the old -API. - -### `withTestId(testID)` +```ts +testID: string; +``` Sets a `testID` property for gesture object, allowing for querying for it in tests. -### `cancelsTouchesInView(value)` (**iOS only**) +### cancelsTouchesInView (**iOS only**) + +```ts +cancelsTouchesInView: boolean | SharedValue; +``` 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/fundamentals/states-events#active). Default value is `true`. -### `runOnJS(value: boolean)` +### runOnJS + +```ts +runOnJS: boolean | SharedValue; +``` 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, ...)` +### simultaneousWith + +```ts +simultaneousWith: Gesture | Gesture[] +``` 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/fundamentals/gesture-composition). [`GestureDetector`](/docs/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, ...)` +### requireToFail + +```ts +requireToFail: Gesture | Gesture[] +``` Adds a relation requiring another gesture to fail, before this one can activate. -### `blocksExternalGesture(otherGesture1, otherGesture2, ...)` +### block + +```ts +block: Gesture | Gesture[] +``` 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/fundamentals/gesture-composition).[`GestureDetector`](/docs/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) +### activeCursor + +```ts +activeCursor: ActiveCursor | SharedValue; +``` -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"`. +This parameter allows to specify which cursor should be used when gesture activates. Supports all [CSS cursor values](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/cursor#keyword) (e.g. `"grab"`, `"zoom-in"`). Default value is set to `"auto"`. diff --git a/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-event-data.md b/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-event-data.md index 6d6767d639..86fb0115ff 100644 --- a/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-event-data.md +++ b/packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-event-data.md @@ -1,19 +1,27 @@ ### Event attributes common to all gestures: -### `state` +### numberOfPointers -Current [state](/docs/fundamentals/states-events) of the handler. Expressed as one of the constants exported under `State` object by the library. - -### `numberOfPointers` +```ts +numberOfPointers: number; +``` Represents the number of pointers (fingers) currently placed on the screen. -### `pointerType` +### pointerType + +```ts +pointerType: PointerType; +``` -Indicates the type of pointer device in use. This value is represented by the `PointerType` enum, which includes the following fields: +```ts +enum PointerType { + TOUCH, + STYLUS, + MOUSE, + KEY, + OTHER, +} +``` -- `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 +Indicates the type of pointer device in use. diff --git a/packages/docs-gesture-handler/docs/gestures/gesture-composition.md b/packages/docs-gesture-handler/docs/gestures/gesture-composition.md new file mode 100644 index 0000000000..0026681bec --- /dev/null +++ b/packages/docs-gesture-handler/docs/gestures/gesture-composition.md @@ -0,0 +1,476 @@ +--- +id: gesture-composition +title: Gesture composition & interactions +sidebar_label: Gesture composition & interactions +sidebar_position: 10 +--- + +RNGH3 provides simple way to set up interactions between gestures by using dedicated hooks and config properties. + +## Composition hooks + +### useCompetingGestures + +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 `simultaneousWith`, `requireTofail` and `block` 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 `useCompetingGestures`: + +> Note: the `useSharedValue` and `useAnimatedStyle` are part of [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/). + +```js +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + usePanGesture, + useLongPressGesture, + GestureHandlerRootView, + useCompetingGestures, +} from 'react-native-gesture-handler'; + +export default function App() { + const panGesture = usePanGesture({ + onUpdate: () => { + console.log('Pan'); + }, + }); + const longPressGesture = useLongPressGesture({ + onDeactivate: (_, success) => { + if (success) { + console.log('Long Press'); + } + }, + }); + + const gesture = useCompetingGestures(panGesture, longPressGesture); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +### useSimultaneousGestures + +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 `simultaneousWith` 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 `useSimultaneousGestures`: + +> Note: the `useSharedValue` and `useAnimatedStyle` are part of [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/). + +```js +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + usePanGesture, + usePinchGesture, + useRotationGesture, + useSimultaneousGestures, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, +} from 'react-native-reanimated'; + +export default 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 = usePanGesture({ + averageTouches: true, + onUpdate: (e) => { + offset.value = { + x: e.translationX + start.value.x, + y: e.translationY + start.value.y, + }; + }, + onDeactivate: () => { + start.value = { + x: offset.value.x, + y: offset.value.y, + }; + }, + }); + + const zoomGesture = usePinchGesture({ + onUpdate: (e) => { + scale.value = savedScale.value * e.scale; + }, + onDeactivate: () => { + savedScale.value = scale.value; + }, + }); + + const rotationGesture = useRotationGesture({ + onUpdate: (e) => { + rotation.value = savedRotation.value + e.rotation; + }, + onDeactivate: () => { + savedRotation.value = rotation.value; + }, + }); + + const composedGesture = useSimultaneousGestures( + dragGesture, + zoomGesture, + rotationGesture + ); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + width: 100, + height: 100, + backgroundColor: 'blue', + }, +}); +``` + +### useExclusiveGestures + +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 `requireToFail` prop set to the first handler, third one has the `requireToFail` 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 `useExclusiveGestures`: + +> Note: the `useSharedValue` and `useAnimatedStyle` are part of [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/). + +```js +import { StyleSheet, View } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + useTapGesture, + useExclusiveGestures, +} from 'react-native-gesture-handler'; + +export default function App() { + const singleTap = useTapGesture({ + onDeactivate: (_, success) => { + if (success) { + console.log('Single tap!'); + } + }, + }); + + const doubleTap = useTapGesture({ + numberOfTaps: 2, + onDeactivate: (_, success) => { + if (success) { + console.log('Double tap!'); + } + }, + }); + + const taps = useExclusiveGestures(doubleTap, singleTap); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + width: 100, + height: 100, + backgroundColor: 'plum', + }, +}); +``` + +## 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: + +### requireToFail + +`requireToFail` 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, + GestureHandlerRootView, + useTapGesture, +} from 'react-native-gesture-handler'; + +export default function Example() { + const innerTap = useTapGesture({ + numberOfTaps: 2, + onDeactivate: (_, success) => { + if (success) { + console.log('inner tap'); + } + }, + }); + + const outerTap = useTapGesture({ + onDeactivate: (_, success) => { + if (success) { + console.log('outer tap'); + } + }, + requireToFail: 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', + }, +}); +``` + +### block + +`block` works similarly to `requireToFail` 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, { useState } from 'react'; +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + ScrollView, + NativeGesture, + usePinchGesture, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, + withTiming, +} from 'react-native-reanimated'; + +const ITEMS = ['red', 'green', 'blue', 'yellow']; + +export default function Example() { + const [scrollGesture, setScrollGesture] = useState( + null + ); + + return ( + + { + if (!scrollGesture || scrollGesture.tag !== gesture.tag) { + setScrollGesture(gesture); + } + }}> + {ITEMS.map((item) => ( + + ))} + + + ); +} + +type ItemProps = { + backgroundColor: string; + scrollGesture: NativeGesture | null; +}; + +function Item({ backgroundColor, scrollGesture }: ItemProps) { + const scale = useSharedValue(1); + const zIndex = useSharedValue(1); + + const pinch = usePinchGesture({ + onBegin: () => { + zIndex.value = 100; + }, + onUpdate: (e) => { + scale.value *= e.scaleChange; + }, + onFinalize: () => { + scale.value = withTiming(1, undefined, (finished) => { + if (finished) { + zIndex.value = 1; + } + }); + }, + block: scrollGesture ?? undefined, + }); + + const animatedStyles = useAnimatedStyle(() => ({ + transform: [{ scale: scale.value }], + zIndex: zIndex.value, + })); + + return ( + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + }, + item: { + flex: 1, + aspectRatio: 1, + }, +}); +``` + +### simultaneousWith + +`simultaneousWith` 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, + GestureHandlerRootView, + useTapGesture, +} from 'react-native-gesture-handler'; + +export default function Example() { + const innerTap = useTapGesture({ + onDeactivate: (_, success) => { + if (success) { + console.log('inner tap'); + } + }, + }); + + const outerTap = useTapGesture({ + onDeactivate: (_, success) => { + if (success) { + console.log('outer tap'); + } + }, + simultaneousWith: 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/gestures/gesture-detector.md b/packages/docs-gesture-handler/docs/gestures/gesture-detector.md index cd8ca83a7d..57c6f36668 100644 --- a/packages/docs-gesture-handler/docs/gestures/gesture-detector.md +++ b/packages/docs-gesture-handler/docs/gestures/gesture-detector.md @@ -2,7 +2,7 @@ id: gesture-detector title: GestureDetector sidebar_label: Gesture detector -sidebar_position: 1 +sidebar_position: 11 --- import FunctionalComponents from './\_shared/gesture-detector-functional1.md'; @@ -30,12 +30,12 @@ function App() { ### `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`). +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`](./gesture-composition.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/gestures/state-manager) in the [touch events](/docs/gestures/touch-events) that allows for managing the state of the gesture. +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) @@ -66,7 +66,9 @@ Specifies whether context menu should be enabled after clicking on underlying vi - {/* Don't do this! */} + + {' '} + {/* Don't do this! */} diff --git a/packages/docs-gesture-handler/docs/gestures/state-manager.md b/packages/docs-gesture-handler/docs/gestures/state-manager.md index 2191213cff..f4c39cdfdc 100644 --- a/packages/docs-gesture-handler/docs/gestures/state-manager.md +++ b/packages/docs-gesture-handler/docs/gestures/state-manager.md @@ -11,17 +11,17 @@ sidebar_position: 15 ### `begin()` -Transition the gesture to the [`BEGAN`](/docs/fundamentals/states-events#began) state. This method will have no effect if the gesture has already activated or finished. +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/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/fundamentals/gesture-composition) with another one, the activation will be delayed until the gesture with higher priority fails. +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/fundamentals/states-events#end) state. This method will have no effect if the handler has already finished. +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/fundamentals/states-events#failed) state. This method will have no effect if the handler has already finished. +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/gestures/touch-events.md b/packages/docs-gesture-handler/docs/gestures/touch-events.md index 29374b89f1..c2244830ee 100644 --- a/packages/docs-gesture-handler/docs/gestures/touch-events.md +++ b/packages/docs-gesture-handler/docs/gestures/touch-events.md @@ -35,11 +35,11 @@ A number representing id of the touch. It may be used to track the touch between ### `x` -X coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). Expressed in point units. +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/gestures/gesture-detector). Expressed in point units. +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` diff --git a/packages/docs-gesture-handler/docs/gestures/use-fling-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-fling-gesture.mdx new file mode 100644 index 0000000000..ad94f406e9 --- /dev/null +++ b/packages/docs-gesture-handler/docs/gestures/use-fling-gesture.mdx @@ -0,0 +1,189 @@ +--- +id: use-fling-gesture +title: Fling gesture +sidebar_label: Fling gesture +sidebar_position: 6 +--- + +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'; + +
+
+ +
+ } + src={FlingGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; + +A discrete gesture that activates when the movement is sufficiently long and fast. +Gesture gets [ACTIVE](/docs/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/fundamentals/states-events#end) state when finger is released. +The gesture will fail to recognize if the finger is lifted before being activated. + +
+ +
+ +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + Directions, + useFlingGesture, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, + withTiming, +} from 'react-native-reanimated'; + +export default function App() { + const position = useSharedValue(0); + + const flingGesture = useFlingGesture({ + direction: Directions.RIGHT, + onActivate: () => { + position.value = withTiming(position.value + 10, { duration: 100 }); + }, + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ translateX: position.value }], + })); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Config + +### Properties specific to `FlingGesture`: + +### direction + +```ts +direction: Directions | SharedValue; +``` + +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'; + +// Single direction +fling.direction(Directions.DOWN); + +// Combined directions +fling.direction(Directions.RIGHT | Directions.LEFT); +``` + +### numberOfPointers + +```ts +numberOfPointers: number | SharedValue; +``` + +Determine exact number of points required to handle the fling gesture. + +### mouseButton (Web & Android only) + +```ts +mouseButton: MouseButton | SharedValue; +``` + +```ts +enum MouseButton { + LEFT, + RIGHT, + MIDDLE, + BUTTON_4, + BUTTON_5, + ALL, +} +``` + +Allows users to choose which mouse button should handler respond to. 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 + +```ts +x: number; +``` + +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/gestures/gesture-detector). Expressed in point units. + +### y + +```ts +y: number; +``` + +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/gestures/gesture-detector). Expressed in point units. + +### absoluteX + +```ts +absoluteX: number; +``` + +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 + +```ts +absoluteY: number; +``` + +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/gestures/use-hover-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-hover-gesture.mdx new file mode 100644 index 0000000000..e15c2375f6 --- /dev/null +++ b/packages/docs-gesture-handler/docs/gestures/use-hover-gesture.mdx @@ -0,0 +1,172 @@ +--- +id: use-hover-gesture +title: Hover gesture +sidebar_label: Hover gesture +sidebar_position: 7 +--- + +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 BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.mdx'; + +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. + +
+ +
+ +## Reference + +```jsx +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + useHoverGesture, +} from 'react-native-gesture-handler'; + +export default function App() { + const hoverGesture = useHoverGesture({}); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## 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/gestures/gesture-composition) it with [`Pan` gesture](/docs/gestures/use-pan-gesture). + +## Config + +### Properties specific to `HoverGesture`: + +### effect (iOS only) + +```ts +effect: HoverEffect | SharedValue; +``` + +```ts +enum HoverEffect { + NONE = 0, + LIFT = 1, + HIGHLIGHT = 2, +} +``` + +Visual effect applied to the view while the view is hovered. Defaults to `HoverEffect.None` + + + +## Callbacks + + + + +## Event data + +### Event attributes specific to `HoverGesture`: + +### x + +```ts +x: number; +``` + +X coordinate of the current position of the pointer relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). Expressed in point units. + +### y + +```ts +y: number; +``` + +Y coordinate of the current position of the pointer relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). Expressed in point units. + +### absoluteX + +```ts +absoluteX: number; +``` + +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 + +```ts +absoluteY: number; +``` + +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 + +```ts +stylusData: StylusData; +``` + +```ts +interface StylusData { + tiltX: number; + tiltY: number; + azimuthAngle: number; + altitudeAngle: number; + pressure: number; +} +``` + +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/gestures/use-long-press-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-long-press-gesture.mdx new file mode 100644 index 0000000000..c313d11f30 --- /dev/null +++ b/packages/docs-gesture-handler/docs/gestures/use-long-press-gesture.mdx @@ -0,0 +1,175 @@ +--- +id: use-long-press-gesture +title: Long press gesture +sidebar_label: Long press gesture +sidebar_position: 3 +--- + +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 BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; + +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/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 or if the finger is moved further than the allowable distance. + +
+ +
+ +## Example + +```jsx +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + useLongPressGesture, +} from 'react-native-gesture-handler'; + +export default function App() { + const longPressGesture = useLongPressGesture({ + onDeactivate: (e, success) => { + if (success) { + console.log(`Long pressed for ${e.duration} ms!`); + } + }, + }); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Config + +### Properties specific to `LongPressGesture`: + +### minDuration + +```ts +minDuration: number | SharedValue; +``` + +Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. + +### maxDistance + +```ts +maxDistance: number | SharedValue; +``` + +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/fundamentals/states-events#active), it will fail to recognize the gesture. The default value is 10. + +### mouseButton (Web & Android only) + +```ts +mouseButton: MouseButton | SharedValue; +``` + +```ts +enum MouseButton { + LEFT, + RIGHT, + MIDDLE, + BUTTON_4, + BUTTON_5, + ALL, +} +``` + +Allows users to choose which mouse button should handler respond to. 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 + +```ts +x: number; +``` + +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/gestures/gesture-detector). + +### y + +```ts +y: number; +``` + +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/gestures/gesture-detector). + +### absoluteX + +```ts +absoluteX: number; +``` + +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/gestures/gesture-detector) can be transformed as an effect of the gesture. + +### absoluteY + +```ts +absoluteY: number; +``` + +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/gestures/gesture-detector) can be transformed as an effect of the gesture. + +### duration + +```ts +duration: number; +``` + +Duration of the long press (time since the start of the gesture), expressed in milliseconds. + + diff --git a/packages/docs-gesture-handler/docs/gestures/use-manual-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-manual-gesture.mdx new file mode 100644 index 0000000000..31eda7ca3c --- /dev/null +++ b/packages/docs-gesture-handler/docs/gestures/use-manual-gesture.mdx @@ -0,0 +1,49 @@ +--- +id: use-manual-gesture +title: Manual gesture +sidebar_label: Manual gesture +sidebar_position: 9 +--- + +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.mdx'; + +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/gestures/state-manager). It will not fail when all the pointers are lifted from the screen. + +## Reference + +```jsx +import { + GestureDetector, + GestureHandlerRootView, + useManualGesture, +} from 'react-native-gesture-handler'; +import Animated from 'react-native-reanimated'; + +export default function App() { + const manualGesture = useManualGesture({}); + + return ( + + + + + + ); +} +``` + +## Config + + + +## Callbacks + + + + +## Event data + + diff --git a/packages/docs-gesture-handler/docs/gestures/use-native-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-native-gesture.mdx new file mode 100644 index 0000000000..500e548629 --- /dev/null +++ b/packages/docs-gesture-handler/docs/gestures/use-native-gesture.mdx @@ -0,0 +1,125 @@ +--- +id: use-native-gesture +title: Native gesture +sidebar_label: Native gesture +sidebar_position: 8 +--- + +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.mdx'; + +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/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 { + GestureDetector, + GestureHandlerRootView, + useNativeGesture, + usePanGesture, + NativeGesture, +} from 'react-native-gesture-handler'; + +const COLORS = ['red', 'green', 'blue', 'purple', 'orange', 'cyan']; + +export default function App() { + const nativeGesture = useNativeGesture({}); + + return ( + + + + + {COLORS.map((color) => ( + + ))} + + + + + ); +} + +type RectangleProps = { + color: string; + scrollGesture: NativeGesture; +}; + +function Rectangle({ color, scrollGesture }: RectangleProps) { + const pan = usePanGesture({ + block: scrollGesture, + }); + + return ( + <> + + + + + + ); +} +``` + +## Remarks + +- `Native` gesture can be used as part of [gesture composition and cross-component interactions](/docs/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 (**Android only**) + +```ts +shouldActivateOnStart: boolean | SharedValue; +``` + +When `true`, underlying handler will activate unconditionally when it receives any touches in [`BEGAN`](/docs/fundamentals/states-events#began) or [`UNDETERMINED`](/docs/fundamentals/states-events#undetermined) state. + +### disallowInterruption + +```ts +disallowInterruption: boolean | SharedValue; +``` + +When `true`, cancels all other gesture handlers when changes its state to [`ACTIVE`](/docs/fundamentals/states-events#active). + + + +## Callbacks + + + +## Event data + +### Event attributes specific to `NativeGesture`: + +### pointerInside + +```ts +pointerInside: boolean; +``` + +`true` if gesture was performed inside of containing view, `false` otherwise. + + diff --git a/packages/docs-gesture-handler/docs/gestures/use-pan-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-pan-gesture.mdx new file mode 100644 index 0000000000..b46c40ac55 --- /dev/null +++ b/packages/docs-gesture-handler/docs/gestures/use-pan-gesture.mdx @@ -0,0 +1,339 @@ +--- +id: use-pan-gesture +title: Pan gesture +sidebar_label: Pan gesture +sidebar_position: 1 +--- + +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'; + +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseContinuousGestureConfig from './\_shared/base-continuous-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.mdx'; + +
+
+ +
+ } + src={PanGestureBasicSrc} + disableMarginBottom={true} + /> +
+ +A continuous gesture that can recognize a panning (dragging) gesture and track its movement. + +The gesture [activates](/docs/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 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. + +
+ +
+ +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + usePanGesture, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + withTiming, + useAnimatedStyle, +} from 'react-native-reanimated'; + +export default function App() { + const position = useSharedValue(0); + + const panGesture = usePanGesture({ + onUpdate: (e) => { + position.value = e.translationX; + }, + onDeactivate: () => { + position.value = withTiming(0, { duration: 100 }); + }, + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ translateX: position.value }], + })); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + 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`](#averagetouches-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 + +```ts +minDistance: number | SharedValue; +``` + +Minimum distance the finger (or multiple finger) need to travel before the gesture [activates](/docs/fundamentals/states-events#active). Expressed in points. + +### minPointers + +```ts +minPointers: number | SharedValue; +``` + +A number of fingers that is required to be placed before gesture can [activate](/docs/fundamentals/states-events#active). Should be a higher or equal to 0 integer. + +### maxPointers + +```ts +maxPointers: number | SharedValue; +``` + +When the given number of fingers is placed on the screen and gesture hasn't yet [activated](/docs/fundamentals/states-events#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. + +### activateAfterLongPress + +```ts +activateAfterLongPress: number | SharedValue; +``` + +Duration in milliseconds of the `LongPress` gesture before `Pan` is allowed to [activate](/docs/fundamentals/states-events#active). If the finger is moved during that period, the gesture will [fail](/docs/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/fundamentals/states-events#active) the `Pan`. + +### activeOffsetX + +```ts +activeOffsetX: number | + SharedValue | + [number | SharedValue, number | SharedValue]; +``` + +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 + +```ts +activeOffsetY: number | + SharedValue | + [number | SharedValue, number | SharedValue]; +``` + +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 + +```ts +failOffsetY: number | + SharedValue | + [number | SharedValue, number | SharedValue]; +``` + +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 + +```ts +failOffsetX: number | + SharedValue | + [number | SharedValue, number | SharedValue]; +``` + +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 (Android only) + +```ts +averageTouches: boolean | SharedValue; +``` + +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 (iOS only) + +```ts +enableTrackpadTwoFingerGesture: boolean | SharedValue; +``` + +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 (Web & Android only) + +```ts +mouseButton: MouseButton | SharedValue; +``` + +```ts +enum MouseButton { + LEFT, + RIGHT, + MIDDLE, + BUTTON_4, + BUTTON_5, + ALL, +} +``` + +Allows users to choose which mouse button should handler respond to. 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 + +```ts +translationX: number; +``` + +Translation of the pan gesture along X axis accumulated over the time of the gesture. The value is expressed in the point units. + +### translationY + +```ts +translationY: number; +``` + +Translation of the pan gesture along Y axis accumulated over the time of the gesture. The value is expressed in the point units. + +### velocityX + +```ts +velocityX: number; +``` + +Velocity of the pan gesture along the X axis in the current moment. The value is expressed in point units per second. + +### velocityY + +```ts +velocityY: number; +``` + +Velocity of the pan gesture along the Y axis in the current moment. The value is expressed in point units per second. + +### x + +```ts +x: number; +``` + +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/gestures/gesture-detector). Expressed in point units. + +### y + +```ts +y: number; +``` + +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/gestures/gesture-detector). Expressed in point units. + +### absoluteX + +```ts +absoluteX: number; +``` + +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 + +```ts +absoluteY: number; +``` + +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 + +```ts +stylusData: StylusData; +``` + +```ts +interface StylusData { + tiltX: number; + tiltY: number; + azimuthAngle: number; + altitudeAngle: number; + pressure: number; +} +``` + +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/gestures/use-pinch-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-pinch-gesture.mdx new file mode 100644 index 0000000000..f6b2e88aa1 --- /dev/null +++ b/packages/docs-gesture-handler/docs/gestures/use-pinch-gesture.mdx @@ -0,0 +1,155 @@ +--- +id: use-pinch-gesture +title: Pinch gesture +sidebar_label: Pinch gesture +sidebar_position: 5 +--- + +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 BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseContinuousGestureConfig from './\_shared/base-continuous-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.mdx'; + +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/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. + +
+ +
+ +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + usePinchGesture, +} 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); + + const pinchGesture = usePinchGesture({ + onUpdate: (e) => { + scale.value = savedScale.value * e.scale; + }, + onDeactivate: () => { + savedScale.value = scale.value; + }, + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ scale: scale.value }], + })); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + 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 `onActivate` or `onUpdate` callbacks. Using it in `onBegin` may lead to unexpected behavior. + +## Config + + + + +## Callbacks + + + + +## Event data + +### Event attributes specific to `PinchGesture`: + +### scale + +```ts +scale: number; +``` + +The scale factor relative to the points of the two touches in screen coordinates. + +### velocity + +```ts +velocity: number; +``` + +Velocity of the pan gesture the current moment. The value is expressed in scale factor per second. + +### `focalX` + +```ts +focalX: number; +``` + +Position expressed in points along X axis of center anchor point of gesture + +### `focalY` + +```ts +focalY: number; +``` + +Position expressed in points along Y axis of center anchor point of gesture + + diff --git a/packages/docs-gesture-handler/docs/gestures/use-rotation-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-rotation-gesture.mdx new file mode 100644 index 0000000000..ee3ebfce8b --- /dev/null +++ b/packages/docs-gesture-handler/docs/gestures/use-rotation-gesture.mdx @@ -0,0 +1,152 @@ +--- +id: use-rotation-gesture +title: Rotation gesture +sidebar_label: Rotation gesture +sidebar_position: 4 +--- + +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 BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseContinuousGestureConfig from './\_shared/base-continuous-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; +import BaseContinuousGestureCallbacks from './\_shared/base-continuous-gesture-callbacks.mdx'; + +A continuous gesture that can recognize a rotation gesture and track its movement. + +The gesture [activates](/docs/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. + +
+ +
+ +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + useRotationGesture, +} 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); + + const rotationGesture = useRotationGesture({ + onUpdate: (e) => { + rotation.value = savedRotation.value + e.rotation; + }, + onDeactivate: () => { + savedRotation.value = rotation.value; + }, + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ rotateZ: `${(rotation.value / Math.PI) * 180}deg` }], + })); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + 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 `onActivate` or `onUpdate` callbacks. Using it in `onBegin` may lead to unexpected behavior. + +## Config + + + + +## Callbacks + + + + +## Event data + +### Event attributes specific to `RotationGesture`: + +### rotation + +```ts +rotation: number; +``` + +Amount rotated, expressed in radians, from the gesture's focal point (anchor). + +### velocity + +```ts +velocity: number; +``` + +Instantaneous velocity, expressed in point units per second, of the gesture. + +### anchorX + +```ts +anchorX: number; +``` + +X coordinate, expressed in points, of the gesture's central focal point (anchor). + +### anchorY + +```ts +anchorY: number; +``` + +Y coordinate, expressed in points, of the gesture's central focal point (anchor). + + diff --git a/packages/docs-gesture-handler/docs/gestures/use-tap-gesture.mdx b/packages/docs-gesture-handler/docs/gestures/use-tap-gesture.mdx new file mode 100644 index 0000000000..b13bcb9f36 --- /dev/null +++ b/packages/docs-gesture-handler/docs/gestures/use-tap-gesture.mdx @@ -0,0 +1,211 @@ +--- +id: use-tap-gesture +title: Tap gesture +sidebar_label: Tap gesture +sidebar_position: 2 +--- + +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 BaseGestureConfig from './\_shared/base-gesture-config.md'; +import BaseGestureCallbacks from './\_shared/base-gesture-callbacks.mdx'; + +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/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/fundamentals/states-events#active), it will [end](/docs/fundamentals/states-events#end). + +
+ +
+ +## Example + +```jsx +import { View, StyleSheet } from 'react-native'; +import { + GestureDetector, + GestureHandlerRootView, + useTapGesture, +} from 'react-native-gesture-handler'; + +export default function App() { + const singleTap = useTapGesture({ + maxDuration: 250, + onActivate: () => { + console.log('Single tap!'); + }, + }); + + return ( + + + + + + ); +} + +const styles = StyleSheet.create({ + container: { + flex: 1, + alignItems: 'center', + justifyContent: 'space-around', + }, + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` + +## Config + +### Properties specific to `TapGesture`: + +### minPointers + +```ts +minPointers: number | SharedValue; +``` + +Minimum number of pointers (fingers) required to be placed before the gesture [activates](/docs/fundamentals/states-events#active). Should be a positive integer. The default value is 1. + +### maxDuration + +```ts +maxDuration: number | SharedValue; +``` + +Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch. The default value is 500. + +### maxDelay + +```ts +maxDelay: number | SharedValue; +``` + +Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required. The default value is 500. + +### numberOfTaps + +```ts +numberOfTaps: number | SharedValue; +``` + +Number of tap gestures required to [activate](/docs/fundamentals/states-events#active) the gesture. The default value is 1. + +### maxDeltaX + +```ts +maxDeltaX: number | SharedValue; +``` + +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/fundamentals/states-events#active), it will fail to recognize the gesture. + +### maxDeltaY + +```ts +maxDeltaY: number | SharedValue; +``` + +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/fundamentals/states-events#active), it will fail to recognize the gesture. + +### maxDistance + +```ts +maxDistance: number | SharedValue; +``` + +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/fundamentals/states-events#active), it will fail to recognize the gesture. + +### mouseButton (Web & Android only) + +```ts +mouseButton: MouseButton | SharedValue; +``` + +```ts +enum MouseButton { + LEFT, + RIGHT, + MIDDLE, + BUTTON_4, + BUTTON_5, + ALL, +} +``` + +Allows users to choose which mouse button should handler respond to. 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 + +```ts +x: number; +``` + +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/gestures/gesture-detector). + +### y + +```ts +y: number; +``` + +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/gestures/gesture-detector). + +### absoluteX + +```ts +absoluteX: number; +``` + +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/gestures/gesture-detector) can be transformed as an effect of the gesture. + +### absoluteY + +```ts +absoluteY: number; +``` + +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/gestures/gesture-detector) can be transformed as an effect of the gesture. + + diff --git a/packages/docs-gesture-handler/docs/guides/swipe-and-scroll.md b/packages/docs-gesture-handler/docs/guides/swipe-and-scroll.md index b6d2f79bd7..a5ac5fbf69 100644 --- a/packages/docs-gesture-handler/docs/guides/swipe-and-scroll.md +++ b/packages/docs-gesture-handler/docs/guides/swipe-and-scroll.md @@ -4,7 +4,7 @@ title: Custom swipeable components inside ScrollView (web) sidebar_position: 5 --- -While we recommend using our own [`ReanimatedSwipeable`](../components/reanimated_swipeable.md) component, creating your own version of swipeable gives you more control over its behavior. Common issue here is that after creating your own swipeable component, scroll does not work. In that case, try adding [`touchAction`](../gestures/gesture-detector.md#touchaction-web-only) set to `"pan-y"`, like this: +While we recommend using our own [`ReanimatedSwipeable`](/docs/components/reanimated_swipeable) component, creating your own version of swipeable gives you more control over its behavior. Common issue here is that after creating your own swipeable component, scroll does not work. In that case, try adding [`touchAction`](/docs/gestures/gesture-detector#touchaction-web-only) set to `"pan-y"`, like this: ```jsx diff --git a/packages/docs-gesture-handler/docs/guides/testing.md b/packages/docs-gesture-handler/docs/guides/testing.md index 7a8f3bc49a..c4264d1a9c 100644 --- a/packages/docs-gesture-handler/docs/guides/testing.md +++ b/packages/docs-gesture-handler/docs/guides/testing.md @@ -112,7 +112,7 @@ it('sends events with additional data to handlers', () => { ## getByGestureTestId(testID) Returns opaque data type associated with gesture. Gesture is found via `testID` attribute in rendered -components (see [`withTestID` method](/docs/gestures/pan-gesture#withrefref)). +components (see [`withTestID` method](/docs/gestures/use-pan-gesture#testid)). ### Arguments diff --git a/packages/docs-gesture-handler/docs/under-the-hood/state.md b/packages/docs-gesture-handler/docs/under-the-hood/state.md index 2cd6b0a5b2..2ab380e0d3 100644 --- a/packages/docs-gesture-handler/docs/under-the-hood/state.md +++ b/packages/docs-gesture-handler/docs/under-the-hood/state.md @@ -4,7 +4,7 @@ title: Handler State sidebar_label: Handler State --- -As described in ["About Gesture Handlers"](/docs/gesture-handlers/about-handlers), gesture handlers can be treated as ["state machines"](https://en.wikipedia.org/wiki/Finite-state_machine). +As described in ["About Gesture Handlers"](/docs/1.x/about-handlers), gesture handlers can be treated as ["state machines"](https://en.wikipedia.org/wiki/Finite-state_machine). 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 in certain circumstances. A gesture handler can be in one of the six possible states: @@ -23,8 +23,8 @@ Each state has its own description below. ## Accessing state -We can monitor a handler's state changes by using the [`onHandlerStateChange`](/docs/gesture-handlers/common-gh#onhandlerstatechange) callback and the destructured `nativeEvent` argument passed to it. -This can be done by comparing the `nativeEvent`'s [`state`](/docs/gesture-handlers/common-gh#state) attribute to one of the constants exported under the `State` object (see example below). +We can monitor a handler's state changes by using the [`onHandlerStateChange`](/docs/1.x/api/gesture-handlers/common-gh#onhandlerstatechange) callback and the destructured `nativeEvent` argument passed to it. +This can be done by comparing the `nativeEvent`'s [`state`](/docs/1.x/api/gesture-handlers/common-gh#state) attribute to one of the constants exported under the `State` object (see example below). ```jsx import { State, LongPressGestureHandler } from 'react-native-gesture-handler'; @@ -84,7 +84,7 @@ The gesture recognizer has received a signal (possibly new touches or a command ### ACTIVE Handler has recognized a gesture. It will become and stay in the `ACTIVE` state until the gesture finishes (e.g. when user lifts the finger) or gets cancelled by the touch system. Under normal circumstances the state will then turn into `END`. In the case that a gesture is cancelled by the touch system, its state would then become `CANCELLED`. -Learn about [discrete and continuous handlers here](/docs/gesture-handlers/about-handlers#discrete-vs-continuous) to understand how long a handler can be kept in the `ACTIVE` state. +Learn about [discrete and continuous handlers here](/docs/1.x/about-handlers#discrete-vs-continuous) to understand how long a handler can be kept in the `ACTIVE` state. ### END diff --git a/packages/docs-gesture-handler/docusaurus.config.js b/packages/docs-gesture-handler/docusaurus.config.js index 42974be4b2..9521346f34 100644 --- a/packages/docs-gesture-handler/docusaurus.config.js +++ b/packages/docs-gesture-handler/docusaurus.config.js @@ -46,7 +46,7 @@ const config = { lastVersion: 'current', // <- this makes 2.x docs as default versions: { current: { - label: '2.x', + label: '3.x', }, }, }, diff --git a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/common-gh.md b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/common-gh.md index 4c077a212a..74eb5b52d1 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/common-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/common-gh.md @@ -20,28 +20,28 @@ This section describes properties that can be used with all gesture handler comp Accepts a boolean value. 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/under-the-hood/state#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/under-the-hood/state#failed) or [`CANCELLED`](/docs/under-the-hood/state#cancelled) (depending on its current state). +When set to `false` we can be sure that the handler's state will **never** become [`ACTIVE`](/docs/1.x/state#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/1.x/state#failed) or [`CANCELLED`](/docs/1.x/state#cancelled) (depending on its current state). Default value is `true`. ### `shouldCancelWhenOutside` Accepts a boolean value. -When `true` the handler will [cancel](/docs/under-the-hood/state#cancelled) or [fail](/docs/under-the-hood/state#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. +When `true` the handler will [cancel](/docs/1.x/state#cancelled) or [fail](/docs/1.x/state#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 [`LongPressGestureHandler`](longpress-gh) and [`TapGestureHandler`](tap-gh) which default to `true`. ### `simultaneousHandlers` -Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set, the handler will be allowed to [activate](/docs/under-the-hood/state#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](/docs/under-the-hood/state#active) state. It will also prevent the provided handlers from [cancelling](/docs/under-the-hood/state#cancelled) the current handler when they [activate](/docs/under-the-hood/state#active). Read more in the [cross handler interaction](interactions.md#simultaneous-recognition) section. +Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set, the handler will be allowed to [activate](/docs/1.x/state#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](/docs/1.x/state#active) state. It will also prevent the provided handlers from [cancelling](/docs/1.x/state#cancelled) the current handler when they [activate](/docs/1.x/state#active). Read more in the [cross handler interaction](interactions.md#simultaneous-recognition) section. ### `waitFor` -Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set the handler will not [activate](/docs/under-the-hood/state#active) as long as the handlers provided by their refs are in the [`BEGAN`](/docs/under-the-hood/state#began) state. Read more in the [cross handler interaction](interactions.md#awaiting-other-handlers) section. +Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set the handler will not [activate](/docs/1.x/state#active) as long as the handlers provided by their refs are in the [`BEGAN`](/docs/1.x/state#began) state. Read more in the [cross handler interaction](interactions.md#awaiting-other-handlers) section. ### `hitSlop` -This parameter enables control over what part of the connected view area can be used to [begin](/docs/under-the-hood/state#began) recognizing the gesture. +This parameter enables control over what part of the connected view area can be used to [begin](/docs/1.x/state#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. @@ -55,17 +55,17 @@ Specifying `width` or `height` is useful if we only want the gesture to activate ### `onGestureEvent` -Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](/docs/under-the-hood/state#active) state. Event payload depends on the particular handler type. Common set of event data attributes is documented [below](#event-data) and handler specific attributes are documented on the corresponding handler pages. E.g. event payload for [`PinchGestureHandler`](rotation-gh#event-data) contains `scale` attribute that represents how the distance between fingers changed since when the gesture started. +Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](/docs/1.x/state#active) state. Event payload depends on the particular handler type. Common set of event data attributes is documented [below](#event-data) and handler specific attributes are documented on the corresponding handler pages. E.g. event payload for [`PinchGestureHandler`](rotation-gh#event-data) contains `scale` attribute that represents how the distance between fingers changed since when the gesture started. Instead of a callback [`Animated.event`](https://reactnative.dev/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. ### `onHandlerStateChange` -Takes a callback that is going to be triggered when [state](/docs/under-the-hood/state) of the given handler changes. +Takes a callback that is going to be triggered when [state](/docs/1.x/state) of the given handler changes. The event payload contains the same payload as in case of [`onGestureEvent`](#ongestureevent) including handler specific event attributes some handlers may provide. -In addition `onHandlerStateChange` event payload contains `oldState` attribute which represents the [state](/docs/under-the-hood/state) of the handler right before the change. +In addition `onHandlerStateChange` event payload contains `oldState` attribute which represents the [state](/docs/1.x/state) of the handler right before the change. Instead of a callback [`Animated.event`](https://reactnative.dev/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. @@ -75,7 +75,7 @@ This section describes the attributes of event object being provided to [`onGest ### `state` -Current [state](/docs/under-the-hood/state) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](/docs/under-the-hood/state) to learn more about how to use it. +Current [state](/docs/1.x/state) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](/docs/1.x/state) to learn more about how to use it. ### `numberOfPointers` diff --git a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/force-gh.md b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/force-gh.md index d910ecb35f..d83a38f9b2 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/force-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/force-gh.md @@ -5,7 +5,7 @@ sidebar_label: Force touch --- A continuous gesture handler that recognizes force of a touch. It allows for tracking pressure of touch on some iOS devices. -The handler [activates](/docs/under-the-hood/state#active) when pressure of touch if greater or equal than `minForce`. It fails if pressure is greater than `maxForce` +The handler [activates](/docs/1.x/state#active) when pressure of touch if greater or equal than `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. @@ -19,11 +19,11 @@ See [set of properties inherited from base handler class](common-gh#properties). ### `minForce` -A minimal pressure that is required before handler can [activate](/docs/under-the-hood/state#active). Should be a value from range `[0.0, 1.0]`. Default is `0.2`. +A minimal pressure that is required before handler can [activate](/docs/1.x/state#active). Should be a value from range `[0.0, 1.0]`. Default is `0.2`. ### `maxForce` -A maximal pressure that could be applied for handler. If the pressure is greater, handler [fails](/docs/under-the-hood/state#failed). Should be a value from range `[0.0, 1.0]`. +A maximal pressure that could be applied for handler. If the pressure is greater, handler [fails](/docs/1.x/state#failed). Should be a value from range `[0.0, 1.0]`. ### `feedbackOnActivation` diff --git a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/longpress-gh.md b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/longpress-gh.md index 69db5218c3..fa53e37298 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/longpress-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/longpress-gh.md @@ -5,7 +5,7 @@ sidebar_label: Long press --- A discrete gesture handler that activates when the corresponding view is pressed for a sufficiently long time. -This handler's state will turn into [END](/docs/under-the-hood/state#end) immediately after the finger is released. +This handler's state will turn into [END](/docs/1.x/state#end) immediately after the finger is released. The handler will fail to recognize a touch event if the finger is lifted before the [minimum required time](#mindurationms) or if the finger is moved further than the [allowable distance](#maxdist). The handler is implemented using [UILongPressGestureRecognizer](https://developer.apple.com/documentation/uikit/uilongpressgesturerecognizer) on iOS and [LongPressGestureHandler](https://github.com/software-mansion/react-native-gesture-handler/blob/main/android/lib/src/main/java/com/swmansion/gesturehandler/LongPressGestureHandler.kt) on Android. @@ -20,7 +20,7 @@ Minimum time, expressed in milliseconds, that a finger must remain pressed on th ### `maxDist` -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 handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. The default value is 10. +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 handler hasn't yet [activated](/docs/1.x/state#active), it will fail to recognize the gesture. The default value is 10. ## Event data diff --git a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pan-gh.md b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pan-gh.md index 8f3490e3e1..3cb640b7bd 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pan-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pan-gh.md @@ -6,7 +6,7 @@ sidebar_label: Pan A continuous gesture handler that can recognize a panning (dragging) gesture and track its movement. -The handler [activates](/docs/under-the-hood/state#active) when a finger is placed on the screen and moved some initial distance. +The handler [activates](/docs/1.x/state#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](#minPointers) required for activation (allowing for multifinger swipes) may be specified. @@ -16,7 +16,7 @@ The handler is implemented using [UIPanGestureRecognizer](https://developer.appl ## Custom activation criteria -The `PanGestureHandler` component exposes a number of properties that can be used to customize the criteria under which a handler will [activate](/docs/under-the-hood/state#active) or [fail](/docs/under-the-hood/state#fail) when recognizing a gesture. +The `PanGestureHandler` component exposes a number of properties that can be used to customize the criteria under which a handler will [activate](/docs/1.x/state#active) or [fail](/docs/1.x/state#fail) when recognizing a gesture. When more than one of such a property is set, `PanGestureHandler` expects all criteria to be met for successful recognition and at most one of the criteria to be overstepped to fail recognition. For example when both [`minDeltaX`](#mindeltax) and [`minDeltaY`](#mindeltay) are set to 20 we expect the finger to travel by 20 points in both the X and Y axis before the handler activates. @@ -45,15 +45,15 @@ See [set of properties inherited from base handler class](common-gh#properties). ### `minDist` -Minimum distance the finger (or multiple finger) need to travel before the handler [activates](/docs/under-the-hood/state#active). Expressed in points. +Minimum distance the finger (or multiple finger) need to travel before the handler [activates](/docs/1.x/state#active). Expressed in points. ### `minPointers` -A number of fingers that is required to be placed before handler can [activate](/docs/under-the-hood/state#active). Should be a higher or equal to 0 integer. +A number of fingers that is required to be placed before handler can [activate](/docs/1.x/state#active). Should be a higher or equal to 0 integer. ### `maxPointers` -When the given number of fingers is placed on the screen and handler hasn't yet [activated](/docs/under-the-hood/state#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. +When the given number of fingers is placed on the screen and handler hasn't yet [activated](/docs/1.x/state#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. ### `activeOffsetX` diff --git a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pinch-gh.md b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pinch-gh.md index 6e3c60b9dc..53c0de7063 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pinch-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/pinch-gh.md @@ -5,7 +5,7 @@ sidebar_label: Pinch --- A continuous gesture handler that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. -The handler [activates](/docs/under-the-hood/state#active) when fingers are placed on the screen and change their position. +The handler [activates](/docs/1.x/state#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. diff --git a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/tap-gh.md b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/tap-gh.md index 26f648111e..7fbfe6b04c 100644 --- a/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/tap-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-1.x/api/gesture-handlers/tap-gh.md @@ -11,7 +11,7 @@ The fingers involved in these gestures must not move significantly from their in 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 handler to [activate](/docs/under-the-hood/state#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](/docs/under-the-hood/state#active), it will [END](/docs/under-the-hood/state#end). +In order for a handler to [activate](/docs/1.x/state#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](/docs/1.x/state#active), it will [END](/docs/1.x/state#end). ## Properties @@ -19,7 +19,7 @@ See [set of properties inherited from base handler class](common-gh#properties). ### `minPointers` -Minimum number of pointers (fingers) required to be placed before the handler [activates](/docs/under-the-hood/state#active). Should be a positive integer. The default value is 1. +Minimum number of pointers (fingers) required to be placed before the handler [activates](/docs/1.x/state#active). Should be a positive integer. The default value is 1. ### `maxDurationMs` @@ -31,19 +31,19 @@ Maximum time, expressed in milliseconds, that can pass before the next tap — i ### `numberOfTaps` -Number of tap gestures required to [activate](/docs/under-the-hood/state#active) the handler. The default value is 1. +Number of tap gestures required to [activate](/docs/1.x/state#active) the handler. The default value is 1. ### `maxDeltaX` -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 handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. +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 handler hasn't yet [activated](/docs/1.x/state#active), it will fail to recognize the gesture. ### `maxDeltaY` -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 handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. +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 handler hasn't yet [activated](/docs/1.x/state#active), it will fail to recognize the gesture. ### `maxDist` -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 handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. +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 handler hasn't yet [activated](/docs/1.x/state#active), it will fail to recognize the gesture. ## Event data diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/_category_.json b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/_category_.json new file mode 100644 index 0000000000..b209621c3f --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Components", + "position": 4, + "link": { + "type": "generated-index" + } +} diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/buttons.mdx b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/buttons.mdx new file mode 100644 index 0000000000..cde390a556 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/buttons.mdx @@ -0,0 +1,178 @@ +--- +id: buttons +title: Buttons +sidebar_label: Buttons +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import GifGallery from '@site/components/GifGallery'; + + + + + +Gesture handler library provides native components that can act as buttons. These can be treated as a replacement to `TouchableHighlight` or `TouchableOpacity` from RN core. Gesture handler's buttons recognize touches in native which makes the recognition process deterministic, allows for rendering ripples on Android in highly performant way (`TouchableNativeFeedback` requires that touch event does a roundtrip to JS before we can update ripple effect, which makes ripples lag a bit on older phones), and provides native and platform default interaction for buttons that are placed in a scrollable container (in which case the interaction is slightly delayed to prevent button from highlighting when you fling). + +Currently Gesture handler library exposes three components that render native touchable elements under the hood: + +- [`BaseButton`](/docs/2.x/components/buttons/#basebutton) +- [`RectButton`](/docs/2.x/components/buttons/#rectbutton) +- [`BorderlessButton`](/docs/2.x/components/buttons/#borderlessbutton) + +On top of that all the buttons are wrapped with `NativeViewGestureHandler` and therefore allow for all the [common gesture handler properties](/docs/2.x/gesture-handlers/common-gh/) and `NativeViewGestureHandler`'s [extra properties](/docs/2.x/gesture-handlers/nativeview-gh#properties) to be applied to them. + +**IMPORTANT**: In order to make buttons accessible, you have to wrap your children in a `View` with `accessible` and `accessibilityRole="button"` props. +Example: + +```javascript +// Not accessible: +const NotAccessibleButton = () => ( + + Foo + +); +// Accessible: +const AccessibleButton = () => ( + + + Bar + + +); +``` + +It is applicable for both iOS and Android platform. On iOS, you won't be able to even select the button, on Android you won't be able to click it in accessibility mode. + +## `BaseButton` + +Can be used as a base class if you'd like to implement some custom interaction for when the button is pressed. + +Below is a list of properties specific to `BaseButton` component: + +### `onActiveStateChange` + +function that gets triggered when button changes from inactive to active and vice versa. It passes active state as a boolean variable as a first parameter for that method. + +### `onPress` + +function that gets triggered when the button gets pressed (analogous to `onPress` in `TouchableHighlight` from RN core). + +### `onLongPress` + +function that gets triggered when the button gets pressed for at least `delayLongPress` milliseconds. + +### `rippleColor` (**Android only**) + +defines color of native [ripple](https://developer.android.com/reference/android/graphics/drawable/RippleDrawable) animation used since API level 21. + +### `exclusive` + +defines if more than one button could be pressed simultaneously. By default set `true`. + +### `delayLongPress` + +defines the delay, in milliseconds, after which the `onLongPress` callback gets called. By default set to 600. + +## `RectButton` + +This type of button component should be used when you deal with rectangular elements or blocks of content that can be pressed, for example table rows or buttons with text and icons. This component provides a platform specific interaction, rendering a rectangular ripple on Android or highlighting the background on iOS and on older versions of Android. In addition to the props of [`BaseButton`](/docs/2.x/components/buttons#basebutton), it accepts the following: + +Below is a list of properties specific to `RectButton` component: + +### `underlayColor` + +this is the background color that will be dimmed when button is in active state. + +### `activeOpacity` (**iOS only**) + +opacity applied to the underlay when button is in active state. + +## `BorderlessButton` + +This type of button component should be used with simple icon-only or text-only buttons. The interaction will be different depending on platform: on Android a borderless ripple will be rendered (it means that the ripple will animate into a circle that can span outside of the view bounds), whereas on iOS the button will be dimmed (similar to how `TouchableOpacity` works). In addition to the props of [`BaseButton`](/docs/2.x/components/buttons#basebutton), it accepts the following: + +Below is a list of properties specific to `BorderlessButton` component: + +### `borderless` (**Android only**) + +set this to `false` if you want the ripple animation to render only within view bounds. + +### `activeOpacity` (**iOS only**) + +opacity applied to the button when it is in an active state. + +## Design patterns + +Components listed here were not designed to behave and look in the same way on both platforms but rather to be used for handling similar behaviour on iOS and Android taking into consideration their's design concepts. + +If you wish to get specific information about platforms design patterns, visit [official Apple docs](https://developer.apple.com/design/human-interface-guidelines/components/menus-and-actions/buttons) and [Material.io guideline](https://material.io/components/buttons#text-button), which widely describe how to implement coherent design. + +This library allows to use native components with native feedback in adequate situations. + +If you do not wish to implement custom design approach, `RectButton` and `BorderlessButton` seem to be absolutely enough and there's no need to use anything else. In all the remaining cases you can always rely on `BaseButton` which is a superclass for the other button classes and can be used as a generic `Touchable` replacement that can be customized to your needs. + +Below we list some of the common usecases for button components to be used along with the type of button that should be used according to the platform specific design guidelines. + +### Lists and action buttons + +If you have a list with clickable items or have an action button that need to display as a separate UI block (vs being inlined in a text) you should use `RectButton`. It changes opacity on click and additionally supports a ripple effect on Android. + + + + + + +To determine emphasis of button it's vital to use fill color or leave it transparent especially on Android. +For medium emphasis you may consider outlined buttons which are used for lower impact than fill buttons. + + + + + +### Icon or text only buttons + +Use `BorderlessButton` for simple icon-only or text-only buttons. The interaction will be different depending on platform: on Android a borderless ripple will be rendered, whereas on iOS the button will be dimmed. +It should be used if you wish to handle non-crucial actions and supportive behaviour. + + + + + + +### `PureNativeButton` + +Use a `PureNativeButton` for accessing the native Component used for build more complex buttons listed above. +It's normally is not recommended to use, but it might be useful if we want to wrap it using Animated or Reanimated. + +```javascript +import { + createNativeWrapper, + PureNativeButton, +} from 'react-native-gesture-handler'; +import Animated from 'react-native-reanimated'; +const { event, Value, createAnimatedComponent } = Animated; + +const AnimatedRawButton = createNativeWrapper( + createAnimatedComponent(PureNativeButton), + { + shouldCancelWhenOutside: false, + shouldActivateOnStart: false, + } +); + +export default class App extends React.Component { + constructor(props) { + super(props); + const state = new Value(); + this._onGestureEvent = event([ + { + nativeEvent: { state }, + }, + ]); + } + + render() { + return ; + } +} +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/pressable.mdx b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/pressable.mdx new file mode 100644 index 0000000000..d7455d3973 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/pressable.mdx @@ -0,0 +1,162 @@ +--- +id: pressable +title: Pressable +sidebar_label: Pressable +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import GifGallery from '@site/components/GifGallery'; + + + + + +:::info +This component is a drop-in replacement for the `Pressable` component. +::: + +`Pressable` is a component that can detect various stages of tap, press, and hover interactions on any of its children. + +### Usage: + +To use `Pressable`, import it in the following way: + +```js +import { Pressable } from 'react-native-gesture-handler'; +``` + +## Properties + +### `children` + +either children or a render function that receives a boolean reflecting whether +the component is currently pressed. + +### `style` + +either view styles or a function that receives a boolean reflecting whether +the component is currently pressed and returns view styles. + +### `onPress` + +called after `onPressOut` when a single tap gesture is detected. + +### `onPressIn` + +called before `onPress` when a touch is engaged. + +### `onPressOut` + +called before `onPress` when a touch is released. + +### `onLongPress` + +called immediately after pointer has been down for at least `delayLongPress` milliseconds (`500` ms by default). + +After `onLongPress` has been called, `onPressOut` will be called as soon as the pointer is lifted and `onPress` will not be called at all. + +### `cancelable` + +whether a press gesture can be interrupted by a parent gesture such as a scroll event. Defaults to `true`. + +### `onHoverIn` (Web only) + +called when pointer is hovering over the element. + +### `onHoverOut` (Web only) + +called when pointer stops hovering over the element. + +### `delayHoverIn` (Web only) + +duration to wait after hover in before calling `onHoverIn`. + +### `delayHoverOut` (Web only) + +duration to wait after hover out before calling `onHoverOut`. + +### `delayLongPress` + +duration (in milliseconds) from `onPressIn` before `onLongPress` is called. + +### `disabled` + +whether the `Pressable` behavior is disabled. + +### `hitSlop` (Android & iOS only) + +additional distance outside of the view in which a press is detected and `onPressIn` is triggered. + +Accepts values of type `number` or [`Rect`](https://reactnative.dev/docs/rect) + +### `pressRetentionOffset` (Android & iOS only) + +additional distance outside of the view (or `hitSlop` if present) in which a touch is considered a +press before `onPressOut` is triggered. + +Accepts values of type `number` or [`Rect`](https://reactnative.dev/docs/rect) + +### `android_disableSound` (Android only) + +if `true`, doesn't play system sound on touch. + +### `android_ripple` (Android only) + +enables the Android ripple effect and configures its color, radius and other parameters. + +Accepts values of type [`RippleConfig`](https://reactnative.dev/docs/pressable#rippleconfig) + +### `testOnly_pressed` + +used only for documentation or testing (e.g. snapshot testing). + +### `unstable_pressDelay` + +duration (in milliseconds) to wait after press down before calling `onPressIn`. + +### Example: + +See the full [pressable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/apps/common-app/src/new_api/pressable/index.tsx) from `GestureHandler` example app. + +import GestureStateFlowExample from '@site/src/examples/GestureStateFlowExample'; + +```js +import { View, Text, StyleSheet } from 'react-native'; +import { Pressable } from 'react-native-gesture-handler'; + +export default function Example() { + return ( + (pressed ? styles.highlight : styles.pressable)} + hitSlop={20} + pressRetentionOffset={20}> + + Pressable! + + + ); +} + +const styles = StyleSheet.create({ + pressable: { + width: 120, + height: 120, + backgroundColor: 'mediumpurple', + borderWidth: StyleSheet.hairlineWidth, + }, + highlight: { + width: 120, + height: 120, + backgroundColor: 'red', + borderWidth: StyleSheet.hairlineWidth, + }, + textWrapper: { + flex: 1, + justifyContent: 'center', + alignItems: 'center', + }, + text: { + color: 'black', + }, +}); +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated-drawer-layout.mdx b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated-drawer-layout.mdx new file mode 100644 index 0000000000..8a5e2e6584 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated-drawer-layout.mdx @@ -0,0 +1,201 @@ +--- +id: reanimated-drawer-layout +title: Reanimated Drawer Layout +sidebar_label: Reanimated Drawer Layout +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +Cross-platform replacement for the React Native's [DrawerLayoutAndroid](http://reactnative.dev/docs/drawerlayoutandroid.html) component. +For detailed usage of standard parameters, please refer to the [React Native docs](http://reactnative.dev/docs/drawerlayoutandroid.html). + +### Usage: + +To use it, import it in the following way: + +```js +import ReanimatedDrawerLayout from 'react-native-gesture-handler/ReanimatedDrawerLayout'; +``` + +## Properties: + +### `drawerType` + +specifies the way the drawer will be displayed. +Accepts values of the `DrawerPosition` enum. Defaults to `FRONT`. + +- `FRONT` the drawer will be displayed above the content view. +- `BACK` the drawer will be displayed below the content view, revealed by sliding away the content view. +- `SLIDE` the drawer will appear attached to the content view, opening it slides both the drawer and the content view. + +| `FRONT` | `BACK` | `SLIDE` | +| ----------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------- | +| | | | + +### `edgeWidth` + +width of the invisible, draggable area on the edge of the content view, which can be dragged to open the drawer. + +### `hideStatusBar` + +a boolean value. When set to `true`, drawer component will use [StatusBar API](http://reactnative.dev/docs/statusbar.html) to hide the OS status bar when the drawer is dragged or idle in the `open` position. + +### `statusBarAnimation` + +a string with possible values: `slide`, `none` or `fade`. Defaults to `slide`. +May be used in combination with `hideStatusBar` to select the animation used for hiding the status bar. +See [StatusBar API](http://reactnative.dev/docs/statusbar.html#statusbaranimation) docs. + +### `overlayColor` + +color of the background overlay on top of the content window when the drawer is `open`. +This color's opacity animates from 0% to 100% as the drawer transitions from closed to open. Defaults to `rgba(0, 0, 0, 0.7)`. + +### `renderNavigationView` + +a renderer function for the drawer component, provided with a `progress` parameter. + +- `progress` - `SharedValue` that indicates the progress of drawer opening/closing animation. + - equals `0` when the `drawer` is closed and `1` when the `drawer` is opened + - can be used by the `drawer` component to animated its children while the `drawer` is opening or closing + +### `onDrawerClose` + +a function which is called when the drawer has been closed. + +### `onDrawerOpen` + +a function which is called when the drawer has been opened. + +### `onDrawerSlide` + +a function which is called when drawer is moving or animating, provided with a `progress` parameter. + +- `progress` - `SharedValue` that indicates the progress of drawer opening/closing animation. + - equals `0` when the `drawer` is closed and `1` when the `drawer` is opened + - can be used by the `drawer` component to animated its children while the `drawer` is opening or closing + +### `onDrawerStateChanged` + +a function which is called when the status of the drawer changes. It takes two arguments: + +- `newState` - interaction state of the drawer. It can be one of the following: + - `DrawerState.IDLE` + - `DrawerState.DRAGGING` + - `DrawerState.SETTLING` +- `drawerWillShow` - `true` when `drawer` started animating to `open` position, `false` otherwise. + +### `enableTrackpadTwoFingerGesture` (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. + +### `children` + +either a component that's rendered in the content view or a function. +If `children` is a function, it is provided with a `progress` parameter. + +- `progress` - `SharedValue` that indicates the progress of drawer opening/closing animation. + - equals `0` when the `drawer` is closed and `1` when the `drawer` is opened + - can be used by the `drawer` component to animated its children while the `drawer` is opening or closing + +### `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)`. Defaults to `MouseButton.LEFT`. + +### `enableContextMenu(value: boolean)` (Web only) + +specifies whether context menu should be enabled after clicking on underlying view with right mouse button. Defaults to `false`. + +## Methods + +### `openDrawer(options)` + +`openDrawer` accepts an optional `options` parameter, which is an object with the following optional properties: + +- `initialVelocity` - the initial velocity of the object attached to the spring. Defaults to `0`. +- `animationSpeed` - controls speed of the animation. Defaults to `1`. + +### `closeDrawer(options)` + +`closeDrawer` accepts an optional `options` parameter, which is an object with the following optional properties: + +- `initialVelocity` - initial velocity of the object attached to the spring. Defaults to `0`. +- `animationSpeed` - controls speed of the animation. Defaults to `1`. + +## Example: + +See the [reanimated drawer layout example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/apps/common-app/src/release_tests/reanimatedDrawerLayout/index.tsx) from GestureHandler example app. + +```js +import React, { useRef } from 'react'; +import { StyleSheet, Text, View } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; + +import ReanimatedDrawerLayout, { + DrawerType, + DrawerPosition, + DrawerLayoutMethods, +} from 'react-native-gesture-handler/ReanimatedDrawerLayout'; + +const DrawerPage = () => { + return ( + + Lorem ipsum + + ); +}; + +export default function ReanimatedDrawerExample() { + const drawerRef = useRef < DrawerLayoutMethods > null; + const tapGesture = Gesture.Tap() + .runOnJS(true) + .onStart(() => drawerRef.current?.openDrawer()); + + return ( + } + drawerPosition={DrawerPosition.LEFT} + drawerType={DrawerType.FRONT}> + + + + Open drawer + + + + + ); +} + +const styles = StyleSheet.create({ + drawerContainer: { + flex: 1, + justifyContent: 'center', + alignItems: 'center', + backgroundColor: 'pink', + }, + innerContainer: { + flex: 1, + backgroundColor: 'white', + alignItems: 'center', + justifyContent: 'center', + gap: 20, + }, + box: { + padding: 20, + backgroundColor: 'pink', + }, +}); +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated_swipeable.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated_swipeable.md new file mode 100644 index 0000000000..bbf58d07fc --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/reanimated_swipeable.md @@ -0,0 +1,251 @@ +--- +id: reanimated_swipeable +title: Reanimated Swipeable +sidebar_label: Reanimated Swipeable +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; +import GifGallery from '@site/components/GifGallery' + + + + + +:::info +This component is a drop-in replacement for the `Swipeable` component, rewritten using `Reanimated`. +::: + +Reanimated `Swipeable` allows for implementing swipeable rows or similar interaction. It renders its children within a panable container allows for horizontal swiping left and right. While swiping one of two "action" containers can be shown depends on whether user swipes left or right (containers can be rendered by `renderLeftActions` or `renderRightActions` props). + +### Usage: + +To use it, import it in the following way: + +```js +import Swipeable from 'react-native-gesture-handler/ReanimatedSwipeable'; +``` + +## Properties + +### `friction` + +a number that specifies how much the visual interaction will be delayed compared to the gesture distance. +e.g. value of `1` will indicate that the swipeable panel should exactly follow the gesture, `2` means it is going to be two times "slower". + +### `leftThreshold` + +distance from the left edge at which released panel will animate to the open state (or the open panel will animate into the closed state). By default it's a half of the panel's width. + +### `rightThreshold` + +distance from the right edge at which released panel will animate to the open state (or the open panel will animate into the closed state). By default it's a half of the panel's width. + +### `dragOffsetFromLeftEdge` + +distance that the panel must be dragged from the left edge to be considered a swipe. The default value is `10`. + +### `dragOffsetFromRightEdge` + +distance that the panel must be dragged from the right edge to be considered a swipe. The default value is `10`. + +### `overshootLeft` + +a boolean value indicating if the swipeable panel can be pulled further than the left actions panel's width. It is set to `true` by default as long as the left panel render function is present. + +### `overshootRight` + +a boolean value indicating if the swipeable panel can be pulled further than the right actions panel's width. It is set to `true` by default as long as the right panel render function is present. + +### `overshootFriction` + +a number that specifies how much the visual interaction will be delayed compared to the gesture distance at overshoot. Default value is `1`, it mean no friction, for a native feel, try `8` or above. + +### `onSwipeableOpen` + +a function that is called when `swipeable` is opened (either right or left). +Receives swipe direction as an argument. + +### `onSwipeableClose` + +a function that is called when `swipeable` is closed. +Receives swipe direction as an argument. + +### `onSwipeableWillOpen` + +a function that is called when `swipeable` starts animating on open (either right or left). +Receives swipe direction as an argument. + +### `onSwipeableWillClose` + +a function that is called when `swipeable` starts animating on close. +Receives swipe direction as an argument. + +### `onSwipeableOpenStartDrag` + +a function that is called when a user starts to drag the `swipable` to open. +Receives swipe direction as an argument. + +### `onSwipeableCloseStartDrag` + +a function that is called when a user starts to drag the `swipable` to close. +Receives swipe direction as an argument. + +### `renderLeftActions` + +a function that returns a component which will be rendered under the swipeable after swiping it to the right. +The function receives the following arguments: + +- `progress` - a `SharedValue` representing swiping progress relative to the width of the returned element. + - Equals `0` when `swipeable` is closed, `1` when `swipeable` is opened. + - When the element overshoots it's opened position the value tends towards `Infinity`. +- `translation` - a horizontal offset of the `swipeable` relative to its closed position. +- `swipeableMethods` - provides an object exposing the methods listed [here](#methods). + +This function must return a `ReactNode`. + +To support `rtl` flexbox layouts use `flexDirection` styling. + +### `renderRightActions` + +a function that returns a component which will be rendered under the swipeable after swiping it to the left. +The function receives the following arguments: + +- `progress` - a `SharedValue` representing swiping progress relative to the width of the returned element. + - Equals `0` when `swipeable` is closed, `1` when `swipeable` is opened. + - When the element overshoots it's opened position the value tends towards `Infinity`. +- `translation` - a horizontal offset of the `swipeable` relative to its closed position. +- `swipeableMethods` - provides an object exposing the methods listed [here](#methods). + +This function must return a `ReactNode`. + +To support `rtl` flexbox layouts use `flexDirection` styling. + +### `containerStyle` + +style object for the container (`Animated.View`), for example to override `overflow: 'hidden'`. + +### `childrenContainerStyle` + +style object for the children container (`Animated.View`), for example to apply `flex: 1`. + +### `simultaneousWithExternalGesture` + +A gesture configuration to be recognized simultaneously with the swipeable gesture. This is useful for allowing other gestures to work simultaneously with swipeable gesture handler. + +For example, to enable a pan gesture alongside the swipeable gesture: + +```jsx +const panGesture = Gesture.Pan(); + + + + +``` + +More details can be found in the [gesture composition documentation](../fundamentals/gesture-composition.md#simultaneouswithexternalgesture). + +### `enableTrackpadTwoFingerGesture` (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`. + +### `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`. + +## Methods + +Using reference to `Swipeable` it's possible to trigger some actions on it + +### `close` + +a method that closes component. + +### `openLeft` + +a method that opens component on left side. + +### `openRight` + +a method that opens component on right side. + +### `reset` + +a method that resets the swiping states of this `Swipeable` component. + +Unlike method `close`, this method does not trigger any animation. + +### Example: + +For a more in-depth presentation of differences between the new and the legacy implementations, +see [swipeable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/apps/common-app/src/release_tests/swipeableReanimation/index.tsx) from GestureHandler Example App. + +```jsx +import React from 'react'; +import { Text, StyleSheet } from 'react-native'; + +import { GestureHandlerRootView } from 'react-native-gesture-handler'; +import ReanimatedSwipeable from 'react-native-gesture-handler/ReanimatedSwipeable'; +import Reanimated, { + SharedValue, + useAnimatedStyle, +} from 'react-native-reanimated'; + +function RightAction(prog: SharedValue, drag: SharedValue) { + const styleAnimation = useAnimatedStyle(() => { + console.log('showRightProgress:', prog.value); + console.log('appliedTranslation:', drag.value); + + return { + transform: [{ translateX: drag.value + 50 }], + }; + }); + + return ( + + Text + + ); +} + +export default function Example() { + return ( + + + Swipe me! + + + ); +} + +const styles = StyleSheet.create({ + rightAction: { width: 50, height: 50, backgroundColor: 'purple' }, + separator: { + width: '100%', + borderTopWidth: 1, + }, + swipeable: { + height: 50, + backgroundColor: 'papayawhip', + alignItems: 'center', + }, +}); +``` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/components/touchables.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/touchables.md new file mode 100644 index 0000000000..6d1f19107f --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/components/touchables.md @@ -0,0 +1,56 @@ +--- +id: touchables +title: Touchables +sidebar_label: Touchables +--- + +:::warning +Touchables will be removed in the future version of Gesture Handler. Use Pressable instead. +::: + +Gesture Handler library provides an implementation of RN's touchable components that are based on [native buttons](buttons.mdx) and does not rely on JS responder system utilized by RN. Our touchable implementation follows the same API and aims to be a drop-in replacement for touchables available in React Native. + +React Native's touchables API can be found here: + +- [Touchable Native Feedback](https://reactnative.dev/docs/touchablenativefeedback) +- [Touchable Highlight](https://reactnative.dev/docs/touchablehighlight) +- [Touchable Opacity](https://reactnative.dev/docs/touchableopacity) +- [Touchable Without Feedback](https://reactnative.dev/docs/touchablewithoutfeedback) + +All major touchable properties (except from `pressRetentionOffset`) have been adopted and should behave in a similar way as with RN's touchables. + +The motivation for using RNGH touchables as a replacement for these imported from React Native is to follow built-in native behavior more closely by utilizing platform native touch system instead of relying on the JS responder system. +These touchables and their feedback behavior are deeply integrated with native +gesture ecosystem and could be connected with other native components (e.g. `ScrollView`) and Gesture Handlers easily and in a more predictable way, which +follows native apps' behavior. + +Our intention was to make switch for these touchables as simple as possible. In order to use RNGH's touchables the only thing you need to do is to change library from which you import touchable components. +need only to change imports of touchables. + +:::info +Gesture Handler's TouchableOpacity uses native driver for animations by default. If this causes problems for you, you can set `useNativeAnimations` prop to false. +::: + +### Example: + +```javascript +import { + TouchableNativeFeedback, + TouchableHighlight, + TouchableOpacity, + TouchableWithoutFeedback, +} from 'react-native'; +``` + +has to be replaced with: + +```javascript +import { + TouchableNativeFeedback, + TouchableHighlight, + TouchableOpacity, + TouchableWithoutFeedback, +} from 'react-native-gesture-handler'; +``` + +For a comparison of both touchable implementations see our [touchables example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/apps/common-app/src/release_tests/touchables/index.tsx) diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/_category_.json b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/_category_.json new file mode 100644 index 0000000000..ea8044f531 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Fundamentals", + "position": 1, + "link": { + "type": "generated-index" + } +} diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/gesture-composition.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/gesture-composition.md new file mode 100644 index 0000000000..31657f617c --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/gesture-composition.md @@ -0,0 +1,408 @@ +--- +id: gesture-composition +title: Gesture composition & interactions +sidebar_label: Gesture composition & interactions +sidebar_position: 3 +--- + +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', + }, +}); +``` \ No newline at end of file diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/installation.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/installation.md new file mode 100644 index 0000000000..43977e49e9 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/installation.md @@ -0,0 +1,177 @@ +--- +id: installation +title: Installation +sidebar_position: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Requirements + +`react-native-gesture-handler` supports the three latest minor releases of `react-native`. + +| version | `react-native` version | +| ------- | ---------------------- | +| 2.28.0+ | 0.79.0+ | +| 2.26.0+ | 0.78.0+ | +| 2.25.0+ | 0.76.0+ | +| 2.24.0+ | 0.75.0+ | +| 2.21.0+ | 0.74.0+ | +| 2.18.0+ | 0.73.0+ | +| 2.16.0+ | 0.68.0+ | +| 2.14.0+ | 0.67.0+ | +| 2.10.0+ | 0.64.0+ | +| 2.0.0+ | 0.63.0+ | + +In order to fully utilize the [touch events](/docs/2.x/gestures/touch-events/) you also need to use `react-native-reanimated` 2.3.0 or newer. + +Setting up `react-native-gesture-handler` is pretty straightforward: + +### 1. Start with installing the package from npm: + + + + ```bash + npx expo install react-native-gesture-handler + ``` + + + ```bash + npm install react-native-gesture-handler + ``` + + + ```bash + yarn add react-native-gesture-handler + ``` + + + +### 2. Wrap your app with `GestureHandlerRootView` component + +```jsx +import { GestureHandlerRootView } from 'react-native-gesture-handler'; + +export default function App() { + return ( + + + + ); +} +``` + +If you don't provide anything to the `styles` prop, it will default to `flex: 1`. If you want to customize the styling of the root view, don't forget to also include `flex: 1` in the custom style, otherwise your app won't render anything. Keep `GestureHandlerRootView` as close to the actual root of the app as possible. It's the entry point for all gestures and all gesture relations. The gestures won't be recognized outside of the root view, and relations only work between gestures mounted under the same root view. + +If you're unsure if one of your dependencies already renders `GestureHandlerRootView` on its own, don't worry and add one at the root anyway. In case of nested root views, Gesture Handler will only use the top-most one and ignore the nested ones. + +:::tip +If you're using gesture handler in your component library, you may want to wrap your library's code in the `GestureHandlerRootView` component. This will avoid extra configuration for the user. +::: + +:::tip +If you're having trouble with gestures not working when inside a component provided by a third-party library, even though you've wrapped the entry point with ``, you can try adding another `` closer to the place the gestures are defined. This way, you can prevent Android from canceling relevant gestures when one of the native views tries to grab lock for delivering touch events. +::: + +### 3. Platform specific setup + +#### [Expo development build](https://docs.expo.dev/develop/development-builds/introduction/) + +When using an Expo development build, run prebuild to update the native code in the ios and android directories. + +```bash +npx expo prebuild +``` + +#### Android + +Setting up Gesture Handler on Android doesn't require any more steps. Keep in mind that if you want to use gestures in Modals you need to wrap Modal's content with `GestureHandlerRootView`: + +```jsx +import { Modal } from 'react-native'; +import { GestureHandlerRootView } from 'react-native-gesture-handler'; + +export function CustomModal({ children, ...rest }) { + return ( + + {children} + + ); +} +``` + +##### Kotlin + +Gesture Handler on Android is implemented in Kotlin. If you need to set a specific Kotlin version to be used by the library, set the `kotlinVersion` ext property in `android/build.gradle` file and RNGH will use that version: + +```groovy +buildscript { + ext { + kotlinVersion = "1.6.21" + } +} +``` + +#### iOS + +While developing for iOS, make sure to install [pods](https://cocoapods.org/) first before running the app: + +```bash +cd ios && pod install && cd .. +``` + +#### Web + +There is no additional configuration required for the web. + +#### With [wix/react-native-navigation](https://github.com/wix/react-native-navigation) + +If you are using a native navigation library like [wix/react-native-navigation](https://github.com/wix/react-native-navigation) you need to make sure that every screen is wrapped with `GestureHandlerRootView`. This can be done for example at the stage when you register your screens. Here's an example: + +```js +import { Navigation } from 'react-native-navigation'; +import FirstTabScreen from './FirstTabScreen'; +import SecondTabScreen from './SecondTabScreen'; +import PushedScreen from './PushedScreen'; +// register all screens of the app (including internal ones) +export function registerScreens() { + Navigation.registerComponent( + 'example.FirstTabScreen', + () => { + return ( + + + + ); + }, + () => FirstTabScreen + ); + Navigation.registerComponent( + 'example.SecondTabScreen', + () => { + return ( + + + + ); + }, + () => SecondTabScreen + ); + Navigation.registerComponent( + 'example.PushedScreen', + () => { + return ( + + + + ); + }, + () => PushedScreen + ); +} +``` + +You can check out [this example project](https://github.com/henrikra/nativeNavigationGestureHandler) to see this kind of set up in action. + +Remember that you need to wrap each screen that you use in your app with `GestureHandlerRootView` as with native navigation libraries each screen maps to a separate root view. It will not be enough to wrap the main screen only. diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/introduction.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/introduction.md new file mode 100644 index 0000000000..f7dc0376d9 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/introduction.md @@ -0,0 +1,122 @@ +--- +id: introduction +title: Introduction +sidebar_label: Introduction +sidebar_position: 1 +slug: / +--- + +Gesture Handler provides a declarative API exposing the native platform's touch and gesture system to React Native. It's designed to be a replacement of React Native's built in touch system called [Gesture Responder System](http://reactnative.dev/docs/gesture-responder-system). Using native touch handling allows to address the performance limitations of React Native's Gesture Responder System. It also provides more control over the platform's native components that can handle gestures on their own. If you want to learn more, we recommend [this talk](https://www.youtube.com/watch?v=V8maYc4R2G0) by [Krzysztof Magiera](https://twitter.com/kzzzf) in which he explains issues with the responder system. + +The main benefits of using React Native Gesture Handler are: + +- A way to use a platform's native touch handling system for recognizing gestures (like pinch, rotation, pan and a few others). +- The ability to define relations between gestures to ensure gestures, and possibly native components, will not conflict with each other. +- Mechanisms to use touchable components that run in native thread and follow platform default behavior; e.g. in the event they are in a scrollable component, turning into pressed state is slightly delayed to prevent it from highlighting when you fling. +- Close integration with [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/) to process touch events on the UI thread. +- Support for different input devices like touch screens, pens and mice. +- Ability to include any native component into the Gesture Handler's touch system, making it work alongside your gestures. + +:::info +We recommended to use Reanimated to implement gesture-driven animations with Gesture Handler. Its more advanced features rely heavily on worklets and the UI runtime provided by Reanimated. +::: + +## Learning resources + +### Apps + +[Gesture Handler Example App](https://github.com/software-mansion/react-native-gesture-handler/tree/main/apps/expo-example) – official gesture handler "showcase" app. + +### Talks and workshops + +[Declarative future of gestures and animations in React Native](https://www.youtube.com/watch?v=kdq4z2708VM) by [Krzysztof Magiera](https://twitter.com/kzzzf) - talk that explains motivation behind creating gesture handler library. It also presents [react-native-reanimated](https://github.com/software-mansion/react-native-reanimated) and how and when it can be used with gesture handler. + +[React Native workshop with Expo team @ReactEurope 2018](https://youtu.be/JSIoE_ReeDk?t=41m49s) by [Brent Vatne](https://twitter.com/notbrent) – great workshop explaining gesture handler in details and presenting a few exercises that will help get you started. + +[Living in an async world of React Native](https://www.youtube.com/watch?v=-Izgons3mec) by [Krzysztof Magiera](https://twitter.com/kzzzf) – talk which highlights some issue with the React Native's touch system Gesture Handler aims to address. Also the motivation for building this library is explained. + +[React Native Touch & Gesture](https://www.youtube.com/watch?v=V8maYc4R2G0) by [Krzysztof Magiera](https://twitter.com/kzzzf) - talk explaining JS responder system limitations and points out some of the core features of Gesture Handler. + +## Contributing + +If you are interested in the project and want to contribute or support it in other ways don't hesitate to contact anyone from the team on Twitter or Bluesky (links below)! + +All PRs are welcome, but talk to us before you start working on something big. + +The easiest way to get started with contributing code is by: + +- Reviewing the list of [open issues](https://github.com/software-mansion/react-native-gesture-handler/issues) and trying to solve the one that seem approachable to you. +- Updating the [documentation](https://github.com/software-mansion/react-native-gesture-handler/blob/main/docs) whenever you see some information is unclear, missing or out of date. + +Code is only one way how you can contribute. You may want to consider [replying on issues](https://github.com/software-mansion/react-native-gesture-handler/issues) if you know how to help. + +## Community + +We are very proud of the community that has been build around this package. We really appreciate all your help regardless of it is a pull request, issue report, helping others by commenting on existing issues or posting some demo or video tutorial on social media. +If you've build something with this library you'd like to share, please contact us as we'd love to help share it with others. + +### Gesture Handler Team 🚀 + +
+ +
+
+ +
+
Jakub Piasecki
+ + +
+ +
+
+ +
+
Michał Bert
+ +
+ +
+
+ +
+
Ignacy Łątka
+ +
+ +
+
+ +
+
Krzysztof Magiera
+ + +
+ +
+ +### Sponsors + +We really appreciate our sponsors! Thanks to them we can develop our library and make the react-native world a better place. Special thanks for: + + diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/states-events.mdx b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/states-events.mdx new file mode 100644 index 0000000000..26df3bcd92 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/fundamentals/states-events.mdx @@ -0,0 +1,89 @@ +--- +id: states-events +title: Gesture states & events +sidebar_label: Gesture states & events +sidebar_position: 4 +--- + +Every gesture can be treated as ["state machine"](https://en.wikipedia.org/wiki/Finite-state_machine). +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 in certain circumstances. + +A gesture can be in one of the six possible states: + +- #### UNDETERMINED + + This is the initial state of each gesture recognizer and it goes into this state after it's done recognizing a gesture. + +- #### FAILED + + A gesture recognizer received some touches but for some reason didn't recognize them. For example, if a finger travels more distance than a defined `maxDist` property allows, then the gesture won't become active but will fail instead. Afterwards, it's state will be reset to `UNDETERMINED`. + +- #### BEGAN + + Gesture recognizer has started receiving touch stream but hasn't yet received enough data to either [fail](#failed) or [activate](#active). + +- #### CANCELLED + + The gesture recognizer has received a signal (possibly new touches or a command from the touch system controller) resulting in the cancellation of a continuous gesture. The gesture's state will become `CANCELLED` until it is finally reset to the initial state, `UNDETERMINED`. + +- #### ACTIVE + + Recognizer has recognized a gesture. It will become and stay in the `ACTIVE` state until the gesture finishes (e.g. when user lifts the finger) or gets cancelled by the touch system. Under normal circumstances the state will then turn into `END`. In the case that a gesture is cancelled by the touch system, its state would then become `CANCELLED`. + +- #### END + + The gesture recognizer has received touches signalling the end of a gesture. Its state will become `END` until it is reset to `UNDETERMINED`. + +## State flows + +The most typical flow of state is when a gesture picks up on an initial touch event, then recognizes it, then acknowledges its ending and resets itself back to the initial state. + +The flow looks as follows: + +import GestureStateFlowExample from '@site/src/examples/GestureStateFlowExample'; + +} + label="Drag or long-press the circle" + larger={true} +/> + +## Events + +There are three types of events in RNGH2: `StateChangeEvent`, `GestureEvent` and `PointerEvent`. The `StateChangeEvent` is send every time a gesture moves to a different state, while `GestureEvent` is send every time a gesture is updated. The first two carry a gesture-specific data and a `state` property, indicating the current state of the gesture. `StateChangeEvent` also carries a `oldState` property indicating the previous state of the gesture. `PointerEvent` carries information about raw touch events, like touching the screen or moving the finger. These events are handled internally before they are passed along to the correct callbacks: + +### `onBegin` + +Is called when a gesture transitions to the [`BEGAN`](#began) state. + +### `onStart` + +Is called when a gesture transitions to the [`ACTIVE`](#active) state. + +### `onEnd` + +Is called when a gesture transitions from the [`ACTIVE`](#active) state to the [`END`](#end), [`FAILED`](#failed), or [`CANCELLED`](#cancelled) state. If the gesture transitions to the [`END`](#end) state, the `success` argument is set to `true` otherwise it is set to `false`. + +### `onFinalize` + +Is called when a gesture transitions to the [`END`](#end), [`FAILED`](#failed), or [`CANCELLED`](#cancelled) state. If the gesture transitions to the [`END`](#end) state, the `success` argument is set to `true` otherwise it is set to `false`. If the gesture transitions from the [`ACTIVE`](#active) state, it will be called after `onEnd`. + +### `onUpdate` + +Is called every time a gesture is updated while it is in the [`ACTIVE`](#active) state. + +### `onPointerDown` + +Is called when new pointers are placed on the screen. It may carry information about more than one pointer because the events are batched. + +### `onPointerMove` + +Is called when pointers are moved on the screen. It may carry information about more than one pointer because the events are batched. + +### `onPointerUp` + +Is called when pointers are lifted from the screen. It may carry information about more than one pointer because the events are batched. + +### `onPointerCancelled` + +Is 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. diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/_category_.json b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/_category_.json similarity index 100% rename from packages/docs-gesture-handler/docs/gesture-handlers/_category_.json rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/_category_.json diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/about-handlers.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/about-handlers.md similarity index 70% rename from packages/docs-gesture-handler/docs/gesture-handlers/about-handlers.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/about-handlers.md index c67eb59173..6565c773a2 100644 --- a/packages/docs-gesture-handler/docs/gesture-handlers/about-handlers.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/about-handlers.md @@ -6,7 +6,7 @@ sidebar_position: 1 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: Gesture handlers are the core building blocks of this library. @@ -16,10 +16,10 @@ Each handler type is capable of recognizing one type of gesture (pan, pinch, etc Handlers analyze touch stream synchronously in the UI thread. This allows for uninterrupted interactions even when the Javascript thread is blocked. -Each handler works as an isolated state machine. It takes touch stream as an input and based on it, it can flip between [states](/docs/under-the-hood/state). +Each handler works as an isolated state machine. It takes touch stream as an input and based on it, it can flip between [states](/docs/2.x/under-the-hood/state). When a gesture starts, based on the position where the finger was placed, a set of handlers that may be interested in recognizing the gesture is selected. All the touch events (touch down, move, up, or when other fingers are placed or lifted) are delivered to all of the handlers selected initially. -When one gesture becomes [active](/docs/under-the-hood/state#active), it cancels all the other gestures (read more about how to influence this process in ["Cross handler interactions"](/docs/gesture-handlers/interactions) section). +When one gesture becomes [active](/docs/2.x/under-the-hood/state#active), it cancels all the other gestures (read more about how to influence this process in ["Cross handler interactions"](/docs/2.x/gesture-handlers/interactions) section). Gesture handler components do not instantiate a native view in the view hierarchy. Instead, they are kept in library's own registry and are only connected to native views. When using any of the gesture handler components, it is important for it to have a native view rendered as a child. Since handler components don't have corresponding views in the hierarchy, the events registered with them are actually hooked into the underlying view. @@ -28,23 +28,23 @@ Since handler components don't have corresponding views in the hierarchy, the ev Currently, the library provides the following list of gestures. Their parameters and attributes they provide to gesture events are documented under each gesture page: -- [`PanGestureHandler`](/docs/gesture-handlers/pan-gh) -- [`TapGestureHandler`](/docs/gesture-handlers/tap-gh) -- [`LongPressGestureHandler`](/docs/gesture-handlers/longpress-gh) -- [`RotationGestureHandler`](/docs/gesture-handlers/rotation-gh) -- [`FlingGestureHandler`](/docs/gesture-handlers/fling-gh) -- [`PinchGestureHandler`](/docs/gesture-handlers/pinch-gh) -- [`ForceTouchGestureHandler`](/docs/gesture-handlers/force-gh) +- [`PanGestureHandler`](/docs/2.x/gesture-handlers/pan-gh) +- [`TapGestureHandler`](/docs/2.x/gesture-handlers/tap-gh) +- [`LongPressGestureHandler`](/docs/2.x/gesture-handlers/longpress-gh) +- [`RotationGestureHandler`](/docs/2.x/gesture-handlers/rotation-gh) +- [`FlingGestureHandler`](/docs/2.x/gesture-handlers/fling-gh) +- [`PinchGestureHandler`](/docs/2.x/gesture-handlers/pinch-gh) +- [`ForceTouchGestureHandler`](/docs/2.x/gesture-handlers/force-gh) ### Discrete vs continuous We distinguish between two types of gestures: discrete and continuous. -Continuous gesture handlers can be [active](/docs/under-the-hood/state#active) for a long period of time and will generate a stream of [gesture events](/docs/gesture-handlers/common-gh#ongestureevent) until the gesture is [over](/docs/under-the-hood/state#ended). -An example of a continuous handler is [`PanGestureHandler`](/docs/gesture-handlers/pan-gh) that once [activated](/docs/under-the-hood/state#active), will start providing updates about [translation](/docs/gesture-handlers/pan-gh#translationx) and other properties. +Continuous gesture handlers can be [active](/docs/2.x/under-the-hood/state#active) for a long period of time and will generate a stream of [gesture events](/docs/2.x/gesture-handlers/common-gh#ongestureevent) until the gesture is [over](/docs/2.x/under-the-hood/state#ended). +An example of a continuous handler is [`PanGestureHandler`](/docs/2.x/gesture-handlers/pan-gh) that once [activated](/docs/2.x/under-the-hood/state#active), will start providing updates about [translation](/docs/2.x/gesture-handlers/pan-gh#translationx) and other properties. -On the other hand, discrete gesture handlers once [activated](/docs/under-the-hood/state#active) will not stay in the active state but will [end](/docs/under-the-hood/state#ended) immediately. -[`LongPressGestureHandler`](/docs/gesture-handlers/longpress-gh) is a discrete handler, as it only detects if the finger is placed for a sufficiently long period of time, it does not track finger movements (as that's the responsibility of [`PanGestureHandler`](/docs/gesture-handlers/pan-gh)). +On the other hand, discrete gesture handlers once [activated](/docs/2.x/under-the-hood/state#active) will not stay in the active state but will [end](/docs/2.x/under-the-hood/state#ended) immediately. +[`LongPressGestureHandler`](/docs/2.x/gesture-handlers/longpress-gh) is a discrete handler, as it only detects if the finger is placed for a sufficiently long period of time, it does not track finger movements (as that's the responsibility of [`PanGestureHandler`](/docs/2.x/gesture-handlers/pan-gh)). Keep in mind that `onGestureEvent` is only generated in continuous gesture handlers and shouldn't be used in the `TapGestureHandler` and other discrete handlers. @@ -77,7 +77,7 @@ class Multitap extends Component { ### Using native components -Gesture handler library exposes a set of components normally available in React Native that are wrapped in [`NativeViewGestureHandler`](/docs/gesture-handlers/nativeview-gh). +Gesture handler library exposes a set of components normally available in React Native that are wrapped in [`NativeViewGestureHandler`](/docs/2.x/gesture-handlers/nativeview-gh). Here is a list of exposed components: - `ScrollView` @@ -86,7 +86,7 @@ Here is a list of exposed components: - `TextInput` - `DrawerLayoutAndroid` (**Android only**) -If you want to use other handlers or [buttons](/docs/components/buttons) nested in a `ScrollView`, use the [`waitFor`](/docs/gesture-handlers/common-gh#waitfor) property to define interaction between a handler and `ScrollView` +If you want to use other handlers or [buttons](/docs/2.x/components/buttons) nested in a `ScrollView`, use the [`waitFor`](/docs/2.x/gesture-handlers/common-gh#waitfor) property to define interaction between a handler and `ScrollView` ### Events with `useNativeDriver` diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/common-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/common-gh.md similarity index 66% rename from packages/docs-gesture-handler/docs/gesture-handlers/common-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/common-gh.md index 58421e27ac..0133c4e096 100644 --- a/packages/docs-gesture-handler/docs/gesture-handlers/common-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/common-gh.md @@ -6,7 +6,7 @@ sidebar_position: 4 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: This page covers the common set of properties all gesture handler components expose. @@ -25,34 +25,34 @@ This section describes properties that can be used with all gesture handler comp Accepts a boolean value. 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/under-the-hood/state#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/under-the-hood/state#failed) or [`CANCELLED`](/docs/under-the-hood/state#cancelled) (depending on its current state). +When set to `false` we can be sure that the handler's state will **never** become [`ACTIVE`](/docs/2.x/under-the-hood/state#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/under-the-hood/state#failed) or [`CANCELLED`](/docs/2.x/under-the-hood/state#cancelled) (depending on its current state). Default value is `true`. ### `shouldCancelWhenOutside` Accepts a boolean value. -When `true` the handler will [cancel](/docs/under-the-hood/state#cancelled) or [fail](/docs/under-the-hood/state#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. +When `true` the handler will [cancel](/docs/2.x/under-the-hood/state#cancelled) or [fail](/docs/2.x/under-the-hood/state#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 [`LongPressGestureHandler`](/docs/gesture-handlers/longpress-gh) and [`TapGestureHandler`](/docs/gesture-handlers/tap-gh) which default to `true`. +Most handlers' `shouldCancelWhenOutside` property defaults to `false` except for the [`LongPressGestureHandler`](/docs/2.x/gesture-handlers/longpress-gh) and [`TapGestureHandler`](/docs/2.x/gesture-handlers/tap-gh) which default to `true`. ### `cancelsTouchesInView` (**iOS only**) Accepts a boolean value. -When `true`, the handler will cancel touches for native UI components (`UIButton`, `UISwitch`, etc) it's attached to when it becomes [`ACTIVE`](/docs/under-the-hood/state#active). +When `true`, the handler will cancel touches for native UI components (`UIButton`, `UISwitch`, etc) it's attached to when it becomes [`ACTIVE`](/docs/2.x/under-the-hood/state#active). Default value is `true`. ### `simultaneousHandlers` -Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set, the handler will be allowed to [activate](/docs/under-the-hood/state#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](/docs/under-the-hood/state#active) state. It will also prevent the provided handlers from [cancelling](/docs/under-the-hood/state#cancelled) the current handler when they [activate](/docs/under-the-hood/state#active). Read more in the [cross handler interaction](/docs/gesture-handlers/interactions#simultaneous-recognition) section. +Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set, the handler will be allowed to [activate](/docs/2.x/under-the-hood/state#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](/docs/2.x/under-the-hood/state#active) state. It will also prevent the provided handlers from [cancelling](/docs/2.x/under-the-hood/state#cancelled) the current handler when they [activate](/docs/2.x/under-the-hood/state#active). Read more in the [cross handler interaction](/docs/2.x/gesture-handlers/interactions#simultaneous-recognition) section. ### `waitFor` -Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set the handler will not [activate](/docs/under-the-hood/state#active) as long as the handlers provided by their refs are in the [`BEGAN`](/docs/under-the-hood/state#began) state. Read more in the [cross handler interaction](/docs/gesture-handlers/interactions#awaiting-other-handlers) section. +Accepts a react ref object or an array of refs to other handler components (refs should be created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html)). When set the handler will not [activate](/docs/2.x/under-the-hood/state#active) as long as the handlers provided by their refs are in the [`BEGAN`](/docs/2.x/under-the-hood/state#began) state. Read more in the [cross handler interaction](/docs/2.x/gesture-handlers/interactions#awaiting-other-handlers) section. ### `hitSlop` -This parameter enables control over what part of the connected view area can be used to [begin](/docs/under-the-hood/state#began) recognizing the gesture. +This parameter enables control over what part of the connected view area can be used to [begin](/docs/2.x/under-the-hood/state#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. @@ -74,17 +74,17 @@ This parameter allows to specify which cursor should be used when gesture activa ### `onGestureEvent` -Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](/docs/under-the-hood/state#active) state. Event payload depends on the particular handler type. Common set of event data attributes is documented [below](#event-data) and handler specific attributes are documented on the corresponding handler pages. E.g. event payload for [`PinchGestureHandler`](/docs/gesture-handlers/rotation-gh#event-data) contains `scale` attribute that represents how the distance between fingers changed since when the gesture started. +Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](/docs/2.x/under-the-hood/state#active) state. Event payload depends on the particular handler type. Common set of event data attributes is documented [below](#event-data) and handler specific attributes are documented on the corresponding handler pages. E.g. event payload for [`PinchGestureHandler`](/docs/2.x/gesture-handlers/rotation-gh#event-data) contains `scale` attribute that represents how the distance between fingers changed since when the gesture started. Instead of a callback [`Animated.event`](https://reactnative.dev/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. ### `onHandlerStateChange` -Takes a callback that is going to be triggered when [state](/docs/under-the-hood/state) of the given handler changes. +Takes a callback that is going to be triggered when [state](/docs/2.x/under-the-hood/state) of the given handler changes. The event payload contains the same payload as in case of [`onGestureEvent`](#ongestureevent) including handler specific event attributes some handlers may provide. -In addition `onHandlerStateChange` event payload contains `oldState` attribute which represents the [state](/docs/under-the-hood/state) of the handler right before the change. +In addition `onHandlerStateChange` event payload contains `oldState` attribute which represents the [state](/docs/2.x/under-the-hood/state) of the handler right before the change. Instead of a callback [`Animated.event`](https://reactnative.dev/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. @@ -94,7 +94,7 @@ This section describes the attributes of event object being provided to [`onGest ### `state` -Current [state](/docs/under-the-hood/state) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](/docs/under-the-hood/state) to learn more about how to use it. +Current [state](/docs/2.x/under-the-hood/state) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](/docs/2.x/under-the-hood/state) to learn more about how to use it. ### `numberOfPointers` diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/create-native-wrapper.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/create-native-wrapper.md similarity index 67% rename from packages/docs-gesture-handler/docs/gesture-handlers/create-native-wrapper.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/create-native-wrapper.md index aa84e63b37..1bd50a5485 100644 --- a/packages/docs-gesture-handler/docs/gesture-handlers/create-native-wrapper.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/create-native-wrapper.md @@ -6,7 +6,7 @@ sidebar_position: 13 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: Creates provided component with NativeViewGestureHandler, allowing it to be part of RNGH's @@ -20,7 +20,7 @@ The component we want to wrap. ### config -Config is an object with properties that can be used on [`NativeViewGestureHandler`](/docs/gesture-handlers/nativeview-gh) +Config is an object with properties that can be used on [`NativeViewGestureHandler`](/docs/2.x/gesture-handlers/nativeview-gh) ## Returns diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/fling-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/fling-gh.md similarity index 77% rename from packages/docs-gesture-handler/docs/gesture-handlers/fling-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/fling-gh.md index baedfc15e1..171f43087d 100644 --- a/packages/docs-gesture-handler/docs/gesture-handlers/fling-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/fling-gh.md @@ -6,18 +6,18 @@ sidebar_position: 9 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A discrete gesture handler that activates when the movement is sufficiently long and fast. -Handler gets [ACTIVE](/docs/under-the-hood/state#active) when movement is sufficiently long and it does not take too much time. -When handler gets activated it will turn into [END](/docs/under-the-hood/state#end) state when finger is released. +Handler gets [ACTIVE](/docs/2.x/under-the-hood/state#active) when movement is sufficiently long and it does not take too much time. +When handler gets activated it will turn into [END](/docs/2.x/under-the-hood/state#end) state when finger is released. The handler will fail to recognize if the finger is lifted before being activated. The handler is implemented using [UISwipeGestureRecognizer](https://developer.apple.com/documentation/uikit/uiswipegesturerecognizer) on iOS and from scratch on Android. ## Properties -See [set of properties inherited from base handler class](/docs/gesture-handlers/common-gh#properties). Below is a list of properties specific to `FlingGestureHandler` component: +See [set of properties inherited from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). Below is a list of properties specific to `FlingGestureHandler` component: ### `direction` @@ -39,7 +39,7 @@ Determine exact number of points required to handle the fling gesture. ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `FlingGestureHandler`: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `FlingGestureHandler`: ### `x` diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/force-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/force-gh.md similarity index 71% rename from packages/docs-gesture-handler/docs/gesture-handlers/force-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/force-gh.md index 6e23205984..110ca1780d 100644 --- a/packages/docs-gesture-handler/docs/gesture-handlers/force-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/force-gh.md @@ -6,11 +6,11 @@ sidebar_position: 11 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A continuous gesture handler that recognizes force of a touch. It allows for tracking pressure of touch on some iOS devices. -The handler [activates](/docs/under-the-hood/state#active) when pressure of touch if greater or equal than `minForce`. It fails if pressure is greater than `maxForce` +The handler [activates](/docs/2.x/under-the-hood/state#active) when pressure of touch if greater or equal than `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. @@ -20,15 +20,15 @@ Since this behaviour is only provided on some iOS devices, this handler should n # Properties -See [set of properties inherited from base handler class](/docs/gesture-handlers/common-gh#properties). Below is a list of properties specific to `ForceTouchGestureHandler` component: +See [set of properties inherited from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). Below is a list of properties specific to `ForceTouchGestureHandler` component: ### `minForce` -A minimal pressure that is required before handler can [activate](/docs/under-the-hood/state#active). Should be a value from range `[0.0, 1.0]`. Default is `0.2`. +A minimal pressure that is required before handler can [activate](/docs/2.x/under-the-hood/state#active). Should be a value from range `[0.0, 1.0]`. Default is `0.2`. ### `maxForce` -A maximal pressure that could be applied for handler. If the pressure is greater, handler [fails](/docs/under-the-hood/state#failed). Should be a value from range `[0.0, 1.0]`. +A maximal pressure that could be applied for handler. If the pressure is greater, handler [fails](/docs/2.x/under-the-hood/state#failed). Should be a value from range `[0.0, 1.0]`. ### `feedbackOnActivation` @@ -36,7 +36,7 @@ Boolean value defining if haptic feedback has to be performed on activation. ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `ForceTouchGestureHandler`: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `ForceTouchGestureHandler`: ### `force` diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/interactions.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/interactions.md similarity index 77% rename from packages/docs-gesture-handler/docs/gesture-handlers/interactions.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/interactions.md index 64b9636051..e225e0e2b0 100644 --- a/packages/docs-gesture-handler/docs/gesture-handlers/interactions.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/interactions.md @@ -6,10 +6,10 @@ sidebar_position: 3 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: -Gesture handlers can "communicate" with each other to support complex gestures and control how they _[activate](/docs/under-the-hood/state#active)_ in certain scenarios. +Gesture handlers can "communicate" with each other to support complex gestures and control how they _[activate](/docs/2.x/under-the-hood/state#active)_ in certain scenarios. There are two means of achieving that described in the sections below. In each case, it is necessary to provide a reference of one handler as a property to the other. @@ -17,17 +17,17 @@ Gesture handler relies on ref objects created using [`React.createRef()`](https: ## Simultaneous recognition -By default, only one gesture handler is allowed to be in the [`ACTIVE`](/docs/under-the-hood/state#active) state. -So when a gesture handler recognizes a gesture it [cancels](/docs/under-the-hood/state#cancelled) all other handlers in the [`BEGAN`](/docs/under-the-hood/state#began) state and prevents any new handlers from receiving a stream of touch events as long as it remains [`ACTIVE`](/docs/under-the-hood/state#active). +By default, only one gesture handler is allowed to be in the [`ACTIVE`](/docs/2.x/under-the-hood/state#active) state. +So when a gesture handler recognizes a gesture it [cancels](/docs/2.x/under-the-hood/state#cancelled) all other handlers in the [`BEGAN`](/docs/2.x/under-the-hood/state#began) state and prevents any new handlers from receiving a stream of touch events as long as it remains [`ACTIVE`](/docs/2.x/under-the-hood/state#active). -This behavior can be altered using the [`simultaneousHandlers`](/docs/gesture-handlers/common-gh#simultaneoushandlers) property (available for all types of handlers). +This behavior can be altered using the [`simultaneousHandlers`](/docs/2.x/gesture-handlers/common-gh#simultaneoushandlers) property (available for all types of handlers). This property accepts a ref or an array of refs to other handlers. -Handlers connected in this way will be allowed to remain in the [`ACTIVE`](/docs/under-the-hood/state#active) state at the same time. +Handlers connected in this way will be allowed to remain in the [`ACTIVE`](/docs/2.x/under-the-hood/state#active) state at the same time. ### Use cases Simultaneous recognition needs to be used when implementing a photo preview component that supports zooming (scaling) the photo, rotating and panning it while zoomed in. -In this case we would use a [`PinchGestureHandler`](/docs/gesture-handlers/pinch-gh), [`RotationGestureHandler`](/docs/gesture-handlers/rotation-gh) and [`PanGestureHandler`](/docs/gesture-handlers/pan-gh) that would have to simultaneously recognize gestures. +In this case we would use a [`PinchGestureHandler`](/docs/2.x/gesture-handlers/pinch-gh), [`RotationGestureHandler`](/docs/2.x/gesture-handlers/rotation-gh) and [`PanGestureHandler`](/docs/2.x/gesture-handlers/pan-gh) that would have to simultaneously recognize gestures. ### Example @@ -75,7 +75,7 @@ class PinchableBox extends React.Component { A good example where awaiting is necessary is when we want to have single and double tap handlers registered for one view (a button). In such a case we need to make single tap handler await a double tap. -Otherwise if we try to perform a double tap the single tap handler will fire just after we hit the button for the first time, consequently [cancelling](/docs/under-the-hood/state#cancelled) the double tap handler. +Otherwise if we try to perform a double tap the single tap handler will fire just after we hit the button for the first time, consequently [cancelling](/docs/2.x/under-the-hood/state#cancelled) the double tap handler. ### Example diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/longpress-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/longpress-gh.md similarity index 80% rename from packages/docs-gesture-handler/docs/gesture-handlers/longpress-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/longpress-gh.md index 2b2e751b99..4d01bab2a5 100644 --- a/packages/docs-gesture-handler/docs/gesture-handlers/longpress-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/longpress-gh.md @@ -6,18 +6,18 @@ sidebar_position: 7 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A discrete gesture handler that activates when the corresponding view is pressed for a sufficiently long time. -This handler's state will turn into [END](/docs/under-the-hood/state#end) immediately after the finger is released. +This handler's state will turn into [END](/docs/2.x/under-the-hood/state#end) immediately after the finger is released. The handler will fail to recognize a touch event if the finger is lifted before the [minimum required time](#mindurationms) or if the finger is moved further than the [allowable distance](#maxdist). The handler is implemented using [UILongPressGestureRecognizer](https://developer.apple.com/documentation/uikit/uilongpressgesturerecognizer) on iOS and [LongPressGestureHandler](https://github.com/software-mansion/react-native-gesture-handler/blob/main/android/src/main/java/com/swmansion/gesturehandler/core/LongPressGestureHandler.kt) on Android. ## Properties -See [set of properties inherited from base handler class](/docs/gesture-handlers/common-gh#properties). Below is a list of properties specific to the `LongPressGestureHandler` component: +See [set of properties inherited from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). Below is a list of properties specific to the `LongPressGestureHandler` component: ### `minDurationMs` @@ -25,11 +25,11 @@ Minimum time, expressed in milliseconds, that a finger must remain pressed on th ### `maxDist` -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 handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. The default value is 10. +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 handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active), it will fail to recognize the gesture. The default value is 10. ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to the `LongPressGestureHandler` component: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to the `LongPressGestureHandler` component: ### `x` diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/nativeview-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/nativeview-gh.md similarity index 64% rename from packages/docs-gesture-handler/docs/gesture-handlers/nativeview-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/nativeview-gh.md index 5c494c9bff..f8712a0d24 100644 --- a/packages/docs-gesture-handler/docs/gesture-handlers/nativeview-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/nativeview-gh.md @@ -6,17 +6,17 @@ sidebar_position: 12 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A gesture handler that allows other touch handling components to participate in RNGH's gesture system. -Used by [`createNativeWrapper()`](/docs/gesture-handlers/create-native-wrapper). +Used by [`createNativeWrapper()`](/docs/2.x/gesture-handlers/create-native-wrapper). ## Properties -See [set of properties inherited from base handler class](/docs/gesture-handlers/common-gh#properties). Below is a list of properties specific to `NativeViewGestureHandler` component: +See [set of properties inherited from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). Below is a list of properties specific to `NativeViewGestureHandler` component: ### `shouldActivateOnStart` (**Android only**) diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/pan-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pan-gh.md similarity index 80% rename from packages/docs-gesture-handler/docs/gesture-handlers/pan-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pan-gh.md index d70c80cdd0..3cf8218652 100644 --- a/packages/docs-gesture-handler/docs/gesture-handlers/pan-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pan-gh.md @@ -6,12 +6,12 @@ sidebar_position: 5 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A continuous gesture handler that can recognize a panning (dragging) gesture and track its movement. -The handler [activates](/docs/under-the-hood/state#active) when a finger is placed on the screen and moved some initial distance. +The handler [activates](/docs/2.x/under-the-hood/state#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](#minPointers) required for activation (allowing for multifinger swipes) may be specified. @@ -21,7 +21,7 @@ The handler is implemented using [UIPanGestureRecognizer](https://developer.appl ## Custom activation criteria -The `PanGestureHandler` component exposes a number of properties that can be used to customize the criteria under which a handler will [activate](/docs/under-the-hood/state#active) or [fail](/docs/under-the-hood/state#fail) when recognizing a gesture. +The `PanGestureHandler` component exposes a number of properties that can be used to customize the criteria under which a handler will [activate](/docs/2.x/under-the-hood/state#active) or [fail](/docs/2.x/under-the-hood/state#fail) when recognizing a gesture. When more than one of such a property is set, `PanGestureHandler` expects all criteria to be met for successful recognition and at most one of the criteria to be overstepped to fail recognition. For example when both [`minDeltaX`](#mindeltax) and [`minDeltaY`](#mindeltay) are set to 20 we expect the finger to travel by 20 points in both the X and Y axis before the handler activates. @@ -46,19 +46,19 @@ If you wish to track the "center of mass" virtual pointer and account for its ch ## Properties -See [set of properties inherited from base handler class](/docs/gesture-handlers/common-gh#properties). Below is a list of properties specific to `PanGestureHandler` component: +See [set of properties inherited from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). Below is a list of properties specific to `PanGestureHandler` component: ### `minDist` -Minimum distance the finger (or multiple finger) need to travel before the handler [activates](/docs/under-the-hood/state#active). Expressed in points. +Minimum distance the finger (or multiple finger) need to travel before the handler [activates](/docs/2.x/under-the-hood/state#active). Expressed in points. ### `minPointers` -A number of fingers that is required to be placed before handler can [activate](/docs/under-the-hood/state#active). Should be a higher or equal to 0 integer. +A number of fingers that is required to be placed before handler can [activate](/docs/2.x/under-the-hood/state#active). Should be a higher or equal to 0 integer. ### `maxPointers` -When the given number of fingers is placed on the screen and handler hasn't yet [activated](/docs/under-the-hood/state#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. +When the given number of fingers is placed on the screen and handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. ### `activeOffsetX` @@ -88,37 +88,37 @@ If only one number `p` is given a range of `(-inf, p)` will be used if `p` is hi > This method is deprecated but supported for backward compatibility. Instead of using `maxDeltaX={N}` you can do `failOffsetX={[-N, N]}`. -When the finger travels the given distance expressed in points along X axis and handler hasn't yet [activated](/docs/under-the-hood/state#active) it will fail recognizing the gesture. +When the finger travels the given distance expressed in points along X axis and handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active) it will fail recognizing the gesture. ### `maxDeltaY` > This method is deprecated but supported for backward compatibility. Instead of using `maxDeltaY={N}` you can do `failOffsetY={[-N, N]}`. -When the finger travels the given distance expressed in points along Y axis and handler hasn't yet [activated](/docs/under-the-hood/state#active) it will fail recognizing the gesture. +When the finger travels the given distance expressed in points along Y axis and handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active) it will fail recognizing the gesture. ### `minOffsetX` > This method is deprecated but supported for backward compatibility. Instead of using `minOffsetX={N}` you can do `activeOffsetX={N}`. -Minimum distance along X (in points) axis the finger (or multiple finger) need to travel before the handler [activates](/docs/under-the-hood/state#active). If set to a lower or equal to 0 value we expect the finger to travel "left" by the given distance. When set to a higher or equal to 0 number the handler will activate on a movement to the "right". If you wish for the movement direction to be ignored use [`minDeltaX`](#mindeltax) instead. +Minimum distance along X (in points) axis the finger (or multiple finger) need to travel before the handler [activates](/docs/2.x/under-the-hood/state#active). If set to a lower or equal to 0 value we expect the finger to travel "left" by the given distance. When set to a higher or equal to 0 number the handler will activate on a movement to the "right". If you wish for the movement direction to be ignored use [`minDeltaX`](#mindeltax) instead. ### `minOffsetY` > This method is deprecated but supported for backward compatibility. Instead of using `minOffsetY={N}` you can do `activeOffsetY={N}`. -Minimum distance along Y (in points) axis the finger (or multiple finger) need to travel before the handler [activates](/docs/under-the-hood/state#active). If set to a lower or equal to 0 value we expect the finger to travel "up" by the given distance. When set to a higher or equal to 0 number the handler will activate on a movement to the "bottom". If you wish for the movement direction to be ignored use [`minDeltaY`](#mindeltay) instead. +Minimum distance along Y (in points) axis the finger (or multiple finger) need to travel before the handler [activates](/docs/2.x/under-the-hood/state#active). If set to a lower or equal to 0 value we expect the finger to travel "up" by the given distance. When set to a higher or equal to 0 number the handler will activate on a movement to the "bottom". If you wish for the movement direction to be ignored use [`minDeltaY`](#mindeltay) instead. ### `minDeltaX` > This method is deprecated but supported for backward compatibility. Instead of using `minDeltaX={N}` you can do `activeOffsetX={[-N, N]}`. -Minimum distance along X (in points) axis the finger (or multiple finger) need to travel (left or right) before the handler [activates](/docs/under-the-hood/state#active). Unlike [`minoffsetx`](#minoffsetx) this parameter accepts only non-lower or equal to 0 numbers that represents the distance in point units. If you want for the handler to [activate](/docs/under-the-hood/state#active) for the movement in one particular direction use [`minOffsetX`](#minoffsetx) instead. +Minimum distance along X (in points) axis the finger (or multiple finger) need to travel (left or right) before the handler [activates](/docs/2.x/under-the-hood/state#active). Unlike [`minoffsetx`](#minoffsetx) this parameter accepts only non-lower or equal to 0 numbers that represents the distance in point units. If you want for the handler to [activate](/docs/2.x/under-the-hood/state#active) for the movement in one particular direction use [`minOffsetX`](#minoffsetx) instead. ### `minDeltaY` > This method is deprecated but supported for backward compatibility. Instead of using `minDeltaY={N}` you can do `activeOffsetY={[-N, N]}`. -Minimum distance along Y (in points) axis the finger (or multiple finger) need to travel (top or bottom) before the handler [activates](/docs/under-the-hood/state#active). Unlike [`minOffsetY`](#minoffsety) this parameter accepts only non-lower or equal to 0 numbers that represents the distance in point units. If you want for the handler to [activate](/docs/under-the-hood/state#active) for the movement in one particular direction use [`minOffsetY`](#minoffsety) instead. +Minimum distance along Y (in points) axis the finger (or multiple finger) need to travel (top or bottom) before the handler [activates](/docs/2.x/under-the-hood/state#active). Unlike [`minOffsetY`](#minoffsety) this parameter accepts only non-lower or equal to 0 numbers that represents the distance in point units. If you want for the handler to [activate](/docs/2.x/under-the-hood/state#active) for the movement in one particular direction use [`minOffsetY`](#minoffsety) instead. ### `avgTouches` (Android only) @@ -130,7 +130,7 @@ Enables two-finger gestures on supported devices, for example iPads with trackpa ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `PanGestureHandler`: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `PanGestureHandler`: ### `translationX` diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/pinch-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pinch-gh.md similarity index 83% rename from packages/docs-gesture-handler/docs/gesture-handlers/pinch-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pinch-gh.md index adf4ae9442..c1b52f36d8 100644 --- a/packages/docs-gesture-handler/docs/gesture-handlers/pinch-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/pinch-gh.md @@ -6,11 +6,11 @@ sidebar_position: 10 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A continuous gesture handler that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. -The handler [activates](/docs/under-the-hood/state#active) when fingers are placed on the screen and change their position. +The handler [activates](/docs/2.x/under-the-hood/state#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. @@ -22,11 +22,11 @@ The handler is implemented using [UIPinchGestureRecognizer](https://developer.ap ## Properties -Properties provided to `PinchGestureHandler` do not extend [common set of properties from base handler class](/docs/gesture-handlers/common-gh#properties). +Properties provided to `PinchGestureHandler` do not extend [common set of properties from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `PinchGestureHandler`: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `PinchGestureHandler`: ### `scale` diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/rotation-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/rotation-gh.md similarity index 80% rename from packages/docs-gesture-handler/docs/gesture-handlers/rotation-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/rotation-gh.md index b6b20f931c..c43f798163 100644 --- a/packages/docs-gesture-handler/docs/gesture-handlers/rotation-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/rotation-gh.md @@ -6,12 +6,12 @@ sidebar_position: 8 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A continuous gesture handler that can recognize a rotation gesture and track its movement. -The handler [activates](/docs/under-the-hood/state#active) when fingers are placed on the screen and change position in a proper way. +The handler [activates](/docs/2.x/under-the-hood/state#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. @@ -19,11 +19,11 @@ The handler is implemented using [UIRotationGestureRecognizer](https://developer ## Properties -Properties provided to `RotationGestureHandler` do not extend [common set of properties from base handler class](/docs/gesture-handlers/common-gh#properties). +Properties provided to `RotationGestureHandler` do not extend [common set of properties from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `RotationGestureHandler`: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to `RotationGestureHandler`: ### `rotation` diff --git a/packages/docs-gesture-handler/docs/gesture-handlers/tap-gh.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/tap-gh.md similarity index 70% rename from packages/docs-gesture-handler/docs/gesture-handlers/tap-gh.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/tap-gh.md index c151632c03..349c1fab5f 100644 --- a/packages/docs-gesture-handler/docs/gesture-handlers/tap-gh.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gesture-handlers/tap-gh.md @@ -6,7 +6,7 @@ sidebar_position: 6 --- :::warning -The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/gestures/gesture) instead. Check out our [upgrading guide](/docs/guides/upgrading-to-2) for more information. +The old API will be removed in the future version of Gesture Handler. Please migrate to [gestures API](/docs/2.x/gestures/gesture) instead. Check out our [upgrading guide](/docs/2.x/guides/upgrading-to-2) for more information. ::: A discrete gesture handler that recognizes one or many taps. @@ -16,15 +16,15 @@ The fingers involved in these gestures must not move significantly from their in 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 handler to [activate](/docs/under-the-hood/state#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](/docs/under-the-hood/state#active), it will [END](/docs/under-the-hood/state#end). +In order for a handler to [activate](/docs/2.x/under-the-hood/state#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](/docs/2.x/under-the-hood/state#active), it will [END](/docs/2.x/under-the-hood/state#end). ## Properties -See [set of properties inherited from base handler class](/docs/gesture-handlers/common-gh#properties). Below is a list of properties specific to the `TapGestureHandler` component: +See [set of properties inherited from base handler class](/docs/2.x/gesture-handlers/common-gh#properties). Below is a list of properties specific to the `TapGestureHandler` component: ### `minPointers` -Minimum number of pointers (fingers) required to be placed before the handler [activates](/docs/under-the-hood/state#active). Should be a positive integer. The default value is 1. +Minimum number of pointers (fingers) required to be placed before the handler [activates](/docs/2.x/under-the-hood/state#active). Should be a positive integer. The default value is 1. ### `maxDurationMs` @@ -36,23 +36,23 @@ Maximum time, expressed in milliseconds, that can pass before the next tap — i ### `numberOfTaps` -Number of tap gestures required to [activate](/docs/under-the-hood/state#active) the handler. The default value is 1. +Number of tap gestures required to [activate](/docs/2.x/under-the-hood/state#active) the handler. The default value is 1. ### `maxDeltaX` -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 handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. +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 handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active), it will fail to recognize the gesture. ### `maxDeltaY` -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 handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. +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 handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active), it will fail to recognize the gesture. ### `maxDist` -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 handler hasn't yet [activated](/docs/under-the-hood/state#active), it will fail to recognize the gesture. +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 handler hasn't yet [activated](/docs/2.x/under-the-hood/state#active), it will fail to recognize the gesture. ## Event data -See [set of event attributes from base handler class](/docs/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to the `TapGestureHandler` component: +See [set of event attributes from base handler class](/docs/2.x/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to the `TapGestureHandler` component: ### `x` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_category_.json b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_category_.json new file mode 100644 index 0000000000..26dbe96e2b --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Gestures", + "position": 3, + "link": { + "type": "generated-index" + } +} diff --git a/packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-callbacks.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-continuous-gesture-callbacks.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/_shared/base-continuous-gesture-callbacks.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-continuous-gesture-callbacks.md diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-continuous-gesture-config.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-continuous-gesture-config.md new file mode 100644 index 0000000000..f829d626e9 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/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/gestures/_shared/base-gesture-callbacks.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-callbacks.md similarity index 100% rename from packages/docs-gesture-handler/docs/gestures/_shared/base-gesture-callbacks.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-callbacks.md diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-config.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-config.md new file mode 100644 index 0000000000..6a39d4cb75 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/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/versioned_docs/version-2.x/gestures/_shared/base-gesture-event-data.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/base-gesture-event-data.md new file mode 100644 index 0000000000..674f2fb478 --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/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/versioned_docs/version-2.x/gestures/_shared/gesture-detector-functional1.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/_shared/gesture-detector-functional1.md new file mode 100644 index 0000000000..2397af9dfa --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/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/gestures/composed-gestures.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/composed-gestures.md similarity index 88% rename from packages/docs-gesture-handler/docs/gestures/composed-gestures.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/composed-gestures.md index f9fd18f36a..5eb0ef45c5 100644 --- a/packages/docs-gesture-handler/docs/gestures/composed-gestures.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/composed-gestures.md @@ -5,7 +5,7 @@ sidebar_label: Composed gestures sidebar_position: 13 --- -Composed gestures (`Race`, `Simultaneous`, `Exclusive`) provide a simple way of building relations between gestures. See [Gesture Composition](/docs/fundamentals/gesture-composition) for more details. +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 diff --git a/packages/docs-gesture-handler/docs/gestures/fling-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/fling-gesture.md similarity index 94% rename from packages/docs-gesture-handler/docs/gestures/fling-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/fling-gesture.md index fef89e4868..58a6812429 100644 --- a/packages/docs-gesture-handler/docs/gestures/fling-gesture.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/fling-gesture.md @@ -30,8 +30,8 @@ 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/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/fundamentals/states-events#end) state when finger is released. +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.
diff --git a/packages/docs-gesture-handler/docs/gestures/force-touch-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/force-touch-gesture.md similarity index 84% rename from packages/docs-gesture-handler/docs/gestures/force-touch-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/force-touch-gesture.md index d3f85e6edd..8227c7dea2 100644 --- a/packages/docs-gesture-handler/docs/gestures/force-touch-gesture.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/force-touch-gesture.md @@ -16,7 +16,7 @@ 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/fundamentals/states-events#active) when pressure of touch is greater than or equal to `minForce`. It fails if pressure is greater than `maxForce`. +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. @@ -47,11 +47,11 @@ function App() { ### `minForce(value: number)` -A minimal pressure that is required before gesture can [activate](/docs/fundamentals/states-events#active). Should be a value from range `[0.0, 1.0]`. Default is `0.2`. +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/fundamentals/states-events#failed). Should be a value from range `[0.0, 1.0]`. +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)` diff --git a/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture-detector.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture-detector.md new file mode 100644 index 0000000000..a4184af36b --- /dev/null +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture-detector.md @@ -0,0 +1,81 @@ +--- +id: gesture-detector +title: GestureDetector +sidebar_label: Gesture detector +sidebar_position: 1 +--- + +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/gestures/gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture.md similarity index 66% rename from packages/docs-gesture-handler/docs/gestures/gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture.md index 08bc5888d7..94454ad961 100644 --- a/packages/docs-gesture-handler/docs/gestures/gesture.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/gesture.md @@ -26,43 +26,43 @@ function App() { ### Gesture.Tap() -Creates a new instance of [`TapGesture`](/docs/gestures/tap-gesture.md) with its default config and no callbacks. +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/gestures/pan-gesture.md) with its default config and no callbacks. +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/gestures/long-press-gesture.md) with its default config and no callbacks. +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/gestures/fling-gesture.md) with its default config and no callbacks. +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/gestures/pinch-gesture.md) with its default config and no callbacks. +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/gestures/rotation-gesture.md) with its default config and no callbacks. +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/gestures/hover-gesture.md) with its default config and no callbacks. +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/gestures/force-touch-gesture.md) with its default config and no callbacks. +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/gestures/manual-gesture.md) with its default config and no callbacks. +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/gestures/native-gesture.md) with its default config and no callbacks. +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 diff --git a/packages/docs-gesture-handler/docs/gestures/hover-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/hover-gesture.md similarity index 92% rename from packages/docs-gesture-handler/docs/gestures/hover-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/hover-gesture.md index 5ad5628dca..6b794fd4bf 100644 --- a/packages/docs-gesture-handler/docs/gestures/hover-gesture.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/hover-gesture.md @@ -59,10 +59,9 @@ function App() { } ``` - ## 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/fundamentals/gesture-composition) it with [`Pan` gesture](/docs/gestures/pan-gesture). +- 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 @@ -95,11 +94,11 @@ Defaults to `HoverEffect.None` ### `x` -X coordinate of the current position of the pointer relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). Expressed in point units. +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/gestures/gesture-detector). Expressed in point units. +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` diff --git a/packages/docs-gesture-handler/docs/gestures/long-press-gesture.md b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/long-press-gesture.md similarity index 84% rename from packages/docs-gesture-handler/docs/gestures/long-press-gesture.md rename to packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/long-press-gesture.md index f92814e255..61f5431703 100644 --- a/packages/docs-gesture-handler/docs/gestures/long-press-gesture.md +++ b/packages/docs-gesture-handler/versioned_docs/version-2.x/gestures/long-press-gesture.md @@ -30,8 +30,8 @@ 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/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/gestures/long-press-gesture#mindurationvalue-number) or if the finger is moved further than the [allowable distance](/docs/gestures/long-press-gesture#maxdistancevalue-number). +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).