diff --git a/docs/docs/api/components/drawer-layout.mdx b/docs/docs/api/components/drawer-layout.mdx deleted file mode 100644 index 04abc42c72..0000000000 --- a/docs/docs/api/components/drawer-layout.mdx +++ /dev/null @@ -1,147 +0,0 @@ ---- -id: drawer-layout -title: Drawer Layout -sidebar_label: DrawerLayout ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import GifGallery from '@site/components/GifGallery'; - -This is a cross-platform replacement for React Native's [DrawerLayoutAndroid](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) component. It provides a compatible API but allows for the component to be used on both Android and iOS. Please refer to [React Native docs](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) for the detailed usage for standard parameters. - -## Usage: - -`DrawerLayout` component isn't exported by default from the `react-native-gesture-handler` package. To use it, import it in the following way: - -```js -import DrawerLayout from 'react-native-gesture-handler/DrawerLayout'; -``` - -## Properties: - -On top of the standard list of parameters DrawerLayout has an additional set of attributes to customize its behavior. Please refer to the list below: - -### `drawerType` - -possible values are: `front`, `back` or `slide` (default is `front`). It specifies the way the drawer will be displayed. When set to `front` the drawer will slide in and out along with the gesture and will display on top of the content view. When `back` is used the drawer displays behind the content view and can be revealed with gesture of pulling the content view to the side. Finally `slide` option makes the drawer appear like it is attached to the side of the content view; when you pull both content view and drawer will follow the gesture. - -Type `slide`: - - - - - -Type `front`: - - - - - -Type `back`: - - - - - -### `edgeWidth` - -number, allows for defining how far from the edge of the content view the gesture should activate. - -### `hideStatusBar` - -boolean, when set to `true` Drawer component will use [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html) API to hide the OS status bar whenever the drawer is pulled or when its in an "open" state. - -### `statusBarAnimation` - -possible values are: `slide`, `none` or `fade` (defaults to `slide`). Can be used when `hideStatusBar` is set to `true` and will select the animation used for hiding/showing the status bar. See [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html#statusbaranimation) documentation for more details. - -### `overlayColor` - -color (default to `"black"`) of a semi-transparent overlay to be displayed on top of the content view when drawer gets open. A solid color should be used as the opacity is added by the Drawer itself and the opacity of the overlay is animated (from 0% to 70%). - -### `renderNavigationView` - -function. This attribute is present in the standard implementation already and is one of the required params. Gesture handler version of DrawerLayout make it possible for the function passed as `renderNavigationView` to take an Animated value as a parameter that indicates the progress of drawer opening/closing animation (progress value is 0 when closed and 1 when opened). This can be used by the drawer component to animated its children while the drawer is opening or closing. - -### `onDrawerClose` - -function. This function is called when the drawer is closed. - -### `onDrawerOpen` - -function. This function is called when the drawer is opened. - -### `onDrawerSlide` - -function. This function is called as a drawer sliding open from touch events. The progress of the drawer opening/closing is passed back as 0 when closed and 1 when opened. - -### `onDrawerStateChanged` - -function. This function is called when the status of the drawer changes. Possible values that can be passed back are: 'Idle', 'Dragging', and 'Settling'. - -### `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` - -component or function. Children is a component which is rendered by default and is wrapped by drawer. However, it could be also a render function which takes an Animated value as a parameter that indicates the progress of drawer opening/closing animation (progress value is 0 when closed and 1 when opened) is the same way like `renderNavigationView` prop. - -## Methods - -### `openDrawer(options)` - -`openDrawer` can take an optional `options` parameter which is an object, enabling further customization of the open animation. - -`options` has two optional properties: - -`velocity`: number, the initial velocity of the object attached to the spring. Default 0 (object is at rest). -`speed`: number, controls speed of the animation. Default 12. - -### `closeDrawer(options)` - -`closeDrawer` can take an optional `options` parameter which is an object, enabling further customization of the close animation. - -`options` has two optional properties: - -`velocity`: number, the initial velocity of the object attached to the spring. Default 0 (object is at rest). -`speed`: number, controls speed of the animation. Default 12. - -## Example: - -See the [drawer example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/horizontalDrawer/index.tsx) from GestureHandler Example App or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -class Drawerable extends Component { - handleDrawerSlide = (status) => { - // outputs a value between 0 and 1 - console.log(status); - }; - - renderDrawer = () => { - return ( - - I am in the drawer! - - ); - }; - - render() { - return ( - - - - Hello, it's me - - - - ); - } -} -``` diff --git a/docs/docs/api/components/touchables.md b/docs/docs/api/components/touchables.md deleted file mode 100644 index 4b45292f72..0000000000 --- a/docs/docs/api/components/touchables.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -id: touchables -title: Touchables -sidebar_label: Touchables ---- - -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://facebook.github.io/react-native/docs/touchablenativefeedback) -- [Touchable Highlight](https://facebook.github.io/react-native/docs/touchablehighlight) -- [Touchable Opacity](https://facebook.github.io/react-native/docs/touchableopacity) -- [Touchable Without Feedback](https://facebook.github.io/react-native/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/example/src/release_tests/touchables/index.tsx) diff --git a/docs/docs/api/gestures/base-continous-gesture-callbacks.md b/docs/docs/api/gestures/base-continous-gesture-callbacks.md deleted file mode 100644 index 5504b2db8d..0000000000 --- a/docs/docs/api/gestures/base-continous-gesture-callbacks.md +++ /dev/null @@ -1,9 +0,0 @@ -### Callbacks common to all continous gestures: - -### `onUpdate(callback)` - -Set the callback that is being called every time the gesture receives an update while it's active. - -### `onChange(callback)` - -Set the callback that is being called every time the gesture receives an update while it's active. This callback will receive information about change in value in relation to the last received event. diff --git a/docs/docs/api/gestures/base-gesture-event-data.md b/docs/docs/api/gestures/base-gesture-event-data.md deleted file mode 100644 index 4d9056b1e5..0000000000 --- a/docs/docs/api/gestures/base-gesture-event-data.md +++ /dev/null @@ -1,9 +0,0 @@ -### Event attributes common to all gestures: - -### `state` - -Current [state](.../../under-the-hood/states-events.md) 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. diff --git a/docs/docs/api/gestures/composed-gestures.md b/docs/docs/api/gestures/composed-gestures.md deleted file mode 100644 index 84e2e451bd..0000000000 --- a/docs/docs/api/gestures/composed-gestures.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: composed-gestures -title: Composed gestures -sidebar_label: Composed gestures ---- - -Composed gestures (`Race`, `Simultaneous`, `Exclusive`) provide a simple way of building relations between gestures. diff --git a/docs/docs/api/gestures/fling-gesture.md b/docs/docs/api/gestures/fling-gesture.md deleted file mode 100644 index 09c2846276..0000000000 --- a/docs/docs/api/gestures/fling-gesture.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -id: fling-gesture -title: Fling gesture -sidebar_label: Fling gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; - -A discrete gesture that activates when the movement is sufficiently long and fast. -Gesture gets [ACTIVE](../../under-the-hood/states-events.md#active) when movement is sufficiently long and it does not take too much time. -When gesture gets activated it will turn into [END](../../under-the-hood/states-events.md#end) state when finger is released. -The gesture will fail to recognize if the finger is lifted before being activated. - -## Config - -### Properties specific to `FlingGesture`: - -### `direction(value: Directions)` - -Expressed allowed direction of movement. Expected values are exported as constants in the `Directions` object. It's possible to pass one or many directions in one parameter: - -```js -fling.direction(Directions.RIGHT | Directions.LEFT); -``` - -or - -```js -fling.direction(Directions.DOWN); -``` - -### `numberOfPointers(value: number)` - -Determine exact number of points required to handle the fling gesture. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `FlingGesture`: - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - - - -## Example - -```jsx -const position = useSharedValue(0); - -const flingGesture = Gesture.Fling() - .direction(Directions.RIGHT) - .onStart((e) => { - position.value = withTiming(position.value + 10, { duration: 100 }); - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ translateX: position.value }], -})); - -return ( - - - -); -``` diff --git a/docs/docs/api/gestures/force-touch-gesture.md b/docs/docs/api/gestures/force-touch-gesture.md deleted file mode 100644 index 8280f944b1..0000000000 --- a/docs/docs/api/gestures/force-touch-gesture.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -id: force-touch-gesture -title: Force touch gesture (iOS only) -sidebar_label: Force touch gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-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](../../under-the-hood/states-events.md#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. - -There's no implementation provided on Android and it simply renders children without any wrappers. -Since this behaviour is only provided on some iOS devices, this gesture should not be used for defining any crucial behaviors. Use it only as an additional improvement and make all features to be accessed without this gesture as well. - -## Config - -### Properties specific to `ForceTouchGesture`: - -### `minForce(value: number)` - -A minimal pressure that is required before gesture can [activate](../../under-the-hood/states-events.md#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](../../under-the-hood/states-events.md#failed). Should be a value from range `[0.0, 1.0]`. - -### `feedbackOnActivation(value: boolean)` - -Value defining if haptic feedback has to be performed on activation. - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `ForceTouchGesture`: - -### `force` - -The pressure of a touch. - - diff --git a/docs/docs/api/gestures/gesture.md b/docs/docs/api/gestures/gesture.md deleted file mode 100644 index b8131ffc58..0000000000 --- a/docs/docs/api/gestures/gesture.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -id: gesture -title: Gesture -sidebar_label: Gesture ---- - -`Gesture` is the object that allows you to create and compose gestures. - -:::tip -Consider wrapping your gesture configurations with `useMemo`, as it will reduce the amount of work Gesture Handler has to do under the hood when updating gestures. For example: -```jsx -const gesture = useMemo( - () => - Gesture.Tap().onStart(() => { - console.log('Number of taps:', tapNumber + 1); - setTapNumber((value) => value + 1); - }), - [tapNumber, setTapNumber] -); -``` -::: - -### Gesture.Tap() - -Creates a new instance of [`TapGesture`](./tap-gesture.md) with its default config and no callbacks. - -### Gesture.Pan() - -Creates a new instance of [`PanGesture`](./pan-gesture.md) with its default config and no callbacks. - -### Gesture.LongPress() - -Creates a new instance of [`LongPressGesture`](./long-press-gesture.md) with its default config and no callbacks. - -### Gesture.Fling() - -Creates a new instance of [`FlingGesture`](./fling-gesture.md) with its default config and no callbacks. - -### Gesture.Pinch() - -Creates a new instance of [`PinchGesture`](./pinch-gesture.md) with its default config and no callbacks. - -### Gesture.Rotation() - -Creates a new instance of [`RotationGesture`](./rotation-gesture.md) with its default config and no callbacks. - -### Gesture.ForceTouch() - -Creates a new instance of [`ForceTouchGesture`](./force-touch-gesture.md) with its default config and no callbacks. - -### Gesture.Manual() - -Creates a new instance of [`ManualGesture`](./manual-gesture.md) with its default config and no callbacks. - -### Gesture.Native() - -Creates a new instance of [`NativeGesture`](./native-gesture.md) with its default config and no callbacks. - -### Gesture.Race(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. Only one of those can become active and there are no restrictions to the activation of the gesture. The first one to activate will cancel all the others. - -### Gesture.Simultaneous(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. All of them can become active without cancelling the others. - -### Gesture.Exclusive(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. Only one of them can become active, but the first one has a higher priority than the second one, the second one has a higher priority than the third one, and so on. When all gestures are in the `BEGAN` state and the activation criteria for the second one is met, instead of activating it will wait until the first one fails (and only then it will activate) or until the first one activates (and then the second one will get cancelled). It is useful when you want to compose gestures with similar activation criteria (e.g. single and double tap at the same component, without Exclusive the single tap would activate every time user taps thus cancelling the double tap). diff --git a/docs/docs/api/gestures/long-press-gesture.md b/docs/docs/api/gestures/long-press-gesture.md deleted file mode 100644 index 9f174d58e7..0000000000 --- a/docs/docs/api/gestures/long-press-gesture.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -id: long-press-gesture -title: Long press gesture -sidebar_label: Long press gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './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](../../under-the-hood/states-events.md#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](#mindurationms) or if the finger is moved further than the [allowable distance](#maxdist). - -## Config - -### Properties specific to `LongPressGesture`: - -### `minDuration(value: number)` - -Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. - -### `maxDistance(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. The default value is 10. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `LongPressGesture`: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `duration` - -Duration of the long press (time since the start of the gesture), expressed in milliseconds. - - - -## Example - -```jsx -const longPressGesture = Gesture.LongPress().onEnd((e, success) => { - if (success) { - Alert.alert(`Long pressed for ${e.duration} ms!`); - } -}); - -return ( - - - -); -``` diff --git a/docs/docs/api/gestures/manual-gesture.md b/docs/docs/api/gestures/manual-gesture.md deleted file mode 100644 index a92c6986ef..0000000000 --- a/docs/docs/api/gestures/manual-gesture.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -id: manual-gesture -title: Manual gesture -sidebar_label: Manual gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A plain gesture that has no specific activation criteria nor event data set. Its state has to be controlled manually using a [state manager](./state-manager.md). It will not fail when all the pointers are lifted from the screen. - -## Config - - - -## Callbacks - - - - -## Event data - - diff --git a/docs/docs/api/gestures/native-gesture.md b/docs/docs/api/gestures/native-gesture.md deleted file mode 100644 index 6fa7249eed..0000000000 --- a/docs/docs/api/gestures/native-gesture.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -id: native-gesture -title: Native gesture -sidebar_label: Native gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A gesture that allows other touch handling components to participate in RNGH's gesture system. When used, the other component should be the direct child of a `GestureDetector`. - -## Config - -### Properties specific to `NativeGesture`: - -### `shouldActivateOnStart(value: boolean)` (**Android only**) - -When `true`, underlying handler will activate unconditionally when in `BEGAN` or `UNDETERMINED` state. - -### `disallowInterruption(value: boolean)` - -When `true`, cancels all other gesture handlers when this `NativeViewGestureHandler` receives an `ACTIVE` state event. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `NativeGesture`: - -### `pointerInside` - -True if gesture was performed inside of containing view, false otherwise. - - diff --git a/docs/docs/api/gestures/pinch-gesture.md b/docs/docs/api/gestures/pinch-gesture.md deleted file mode 100644 index 5b56e7d043..0000000000 --- a/docs/docs/api/gestures/pinch-gesture.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -id: pinch-gesture -title: Pinch gesture -sidebar_label: Pinch gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. -The gesture [activates](../../under-the-hood/states-events.md#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. - -## Config - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `PinchGesture`: - -### `scale` - -The scale factor relative to the points of the two touches in screen coordinates. - -### `velocity` - -Velocity of the pan gesture the current moment. The value is expressed in point units per second. - -### `focalX` - -Position expressed in points along X axis of center anchor point of gesture - -### `focalY` - -Position expressed in points along Y axis of center anchor point of gesture - - - -## Example - -```jsx -const scale = useSharedValue(1); -const savedScale = useSharedValue(1); - -const pinchGesture = Gesture.Pinch() - .onUpdate((e) => { - scale.value = savedScale.value * e.scale; - }) - .onEnd(() => { - savedScale.value = scale.value; - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ scale: scale.value }], -})); - -return ( - - - -); -``` diff --git a/docs/docs/api/gestures/rotation-gesture.md b/docs/docs/api/gestures/rotation-gesture.md deleted file mode 100644 index 6550e0ea98..0000000000 --- a/docs/docs/api/gestures/rotation-gesture.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -id: rotation-gesture -title: Rotation gesture -sidebar_label: Rotation gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that can recognize a rotation gesture and track its movement. - -The gesture [activates](../../under-the-hood/states-events.md#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. - -## Config - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `RotationGesture`: - -### `rotation` - -Amount rotated, expressed in radians, from the gesture's focal point (anchor). - -### `velocity` - -Instantaneous velocity, expressed in point units per second, of the gesture. - -### `anchorX` - -X coordinate, expressed in points, of the gesture's central focal point (anchor). - -### `anchorY` - -Y coordinate, expressed in points, of the gesture's central focal point (anchor). - - - -## Example - -```jsx -const rotation = useSharedValue(1); -const savedRotation = useSharedValue(1); - -const rotationGesture = Gesture.Rotation() - .onUpdate((e) => { - rotation.value = savedRotation.value + e.rotation; - }) - .onEnd(() => { - savedRotation.value = rotation.value; - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ rotateZ: `${(rotation.value / Math.PI) * 180}deg` }], -})); - -return ( - - - -); -``` diff --git a/docs/docs/api/gestures/state-manager.md b/docs/docs/api/gestures/state-manager.md deleted file mode 100644 index cb50e8212b..0000000000 --- a/docs/docs/api/gestures/state-manager.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: state-manager -title: Gesture state manager -sidebar_label: Gesture state manager ---- - -`GestureStateManager` allows to manually control the state of the gestures. Please note that `react-native-reanimated` is required to use it, since it allows for synchronously executing methods in worklets. - -## Methods - -### `begin()` - -Transition the gesture to the [`BEGAN`](../../under-the-hood/states-events.md#began) state. This method will have no effect if the gesture has already activated or finished. - -### `activate()` - -Transition the gesture to the [`ACTIVE`](../../under-the-hood/states-events.md#active) state. This method will have no effect if the handler is already active, or has finished. -If the gesture is [`exclusive`](../../gesture-composition) with another one, the activation will be delayed until the gesture with higher priority fails. - -### `end()` - -Transition the gesture to the [`END`](../../under-the-hood/states-events.md#end) state. This method will have no effect if the handler has already finished. - -### `fail()` - -Transition the gesture to the [`FAILED`](../../under-the-hood/states-events.md#failed) state. This method will have no effect if the handler has already finished. diff --git a/docs/docs/api/gestures/tap-gesture.md b/docs/docs/api/gestures/tap-gesture.md deleted file mode 100644 index d20bc5cbd1..0000000000 --- a/docs/docs/api/gestures/tap-gesture.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -id: tap-gesture -title: Tap gesture -sidebar_label: Tap gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; - -A discrete gesture that recognizes one or many taps. - -Tap gestures detect one or more fingers briefly touching the screen. -The fingers involved in these gestures must not move significantly from their initial touch positions. -The required number of taps and allowed distance from initial position may be configured. -For example, you might configure tap gesture recognizers to detect single taps, double taps, or triple taps. - -In order for a gesture to [activate](../../under-the-hood/states-events.md#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDuration, and maxDelayMs (explained below) must be met. Immediately after the gesture [activates](../../under-the-hood/states-events.md#active), it will [end](../../under-the-hood/states-events.md#end). - -## Config - -### Properties specific to `TapGesture`: - -### `minPointers(value: number)` - -Minimum number of pointers (fingers) required to be placed before the gesture [activates](../../under-the-hood/states-events.md#active). Should be a positive integer. The default value is 1. - -### `maxDuration(value: number)` - -Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch. The default value is 500. - -### `maxDelay(value: number)` - -Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required. The default value is 500. - -### `numberOfTaps(value: number)` - -Number of tap gestures required to [activate](../../under-the-hood/states-events.md#active) the gesture. The default value is 1. - -### `maxDeltaX(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the X axis during a tap gesture. If the finger travels further than the defined distance along the X axis and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - -### `maxDeltaY(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the Y axis during a tap gesture. If the finger travels further than the defined distance along the Y axis and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - -### `maxDistance(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a tap gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `TapGesture`: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - - - -## Example - -```jsx -const singleTap = Gesture.Tap() - .maxDuration(250) - .onStart(() => { - Alert.alert('Single tap!'); - }); - -const doubleTap = Gesture.Tap() - .maxDuration(250) - .numberOfTaps(2) - .onStart(() => { - Alert.alert('Double tap!'); - }); - -return ( - - - -); -``` diff --git a/docs/docs/api/gestures/touch-events.md b/docs/docs/api/gestures/touch-events.md deleted file mode 100644 index 58103d7b25..0000000000 --- a/docs/docs/api/gestures/touch-events.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -id: touch-events -title: Touch events -sidebar_label: Touch events ---- - -### Touch event attributes: - -### `eventType` - -Type of the current event - whether the finger was placed on the screen, moved, lifted or cancelled. - -### `changedTouches` - -An array of objects where every object represents a single touch. Contains information only about the touches that were affected by the event i.e. those that were placed down, moved, lifted or cancelled. - -### `allTouches` - -An array of objects where every object represents a single touch. Contains information about all active touches. - -### `numberOfTouches` - -Number representing the count of currently active touches. - -:::caution -Don't rely on the order of items in the `touches` as it may change during the gesture, instead use the `id` attribute to track individual touches across events. -::: - -### PointerData attributes: - -### `id` - -A number representing id of the touch. It may be used to track the touch between events as the id will not change while it is being tracked. - -### `x` - -X coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the touch relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the touch relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. diff --git a/docs/docs/api/test-api.md b/docs/docs/api/test-api.md deleted file mode 100644 index 2eacd0c711..0000000000 --- a/docs/docs/api/test-api.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -id: test-api -title: Testing ---- - -:::info -If you want to use `fireGestureHandler` and `getByGestureTestId`, you need to import them from `react-native-gesture-handler/jest-utils` package. -::: - -## fireGestureHandler(gestureOrHandler, eventList) - -Simulates one event stream (i.e. event sequence starting with `BEGIN` state and ending -with one of `END`/`FAIL`/`CANCEL` states), calling appropriate callbacks associated with given gesture handler. - -### Arguments - -#### `gestureOrHandler` - -Represents either: - -1. Gesture handler component found by Jest queries (e.g. `getByTestId`) -2. Gesture found by [`getByGestureTestId()`](#getbygestureidtestid) - -#### `eventList` - -Event data passed to appropriate callback. RNGH fills event list if required -data is missing using these rules: - -1. `oldState` is filled using state of the previous event. `BEGIN` events use - `UNDETERMINED` value as previous event. -2. Events after first `ACTIVE` state can omit `state` field. -3. Handler specific data is filled (e.g. `numberOfTouches`, `x` fields) with - defaults. -4. Missing `BEGIN` and `END` events are added with data copied from first and last - passed event, respectively. -5. If first event don't have `state` field, the `ACTIVE` state is assumed. - -Some examples: - -```jsx -const oldStateFilled = [ - { state: State.BEGAN }, - { state: State.ACTIVE }, - { state: State.END }, -]; // three events with specified state are fired. - -const implicitActiveState = [ - { state: State.BEGAN }, - { state: State.ACTIVE }, - { x: 5 }, - { state: State.END }, -]; // 4 events, including two ACTIVE events (second one has overriden additional data). - -const implicitBegin = [ - { x: 1, y: 11 }, - { x: 2, y: 12, state: State.FAILED }, -]; // 3 events, including implicit BEGAN, one ACTIVE, and one FAILED event with additional data. - -const implicitBeginAndEnd = [ - { x: 5, y: 15 }, - { x: 6, y: 16 }, - { x: 7, y: 17 }, -]; // 5 events, including 3 ACTIVE events and implicit BEGAN and END events. BEGAN uses first event's additional data, END uses last event's additional data. - -const allImplicits = []; // 3 events, one BEGIN, one ACTIVE, one END with defaults. -``` - -### Example - -Extracted from RNGH tests, check `Events.test.tsx` for full implementation. - -```tsx -it('sends events with additional data to handlers', () => { - const panHandlers = mockedEventHandlers(); - render(); - fireGestureHandler(getByGestureTestId('pan'), [ - { state: State.BEGAN, translationX: 0 }, - { state: State.ACTIVE, translationX: 10 }, - { translationX: 20 }, - { translationX: 20 }, - { state: State.END, translationX: 30 }, - ]); - - expect(panHandlers.active).toBeCalledTimes(3); - expect(panHandlers.active).toHaveBeenLastCalledWith( - expect.objectContaining({ translationX: 20 }) - ); -}); -``` - -## getByGestureTestId(testID) - -Returns opaque data type associated with gesture. Gesture is found via `testID` attribute in rendered -components (see [`withTestID` method](./gestures/base-gesture-config.md#withrefref)). - -### Arguments - -#### `testID` - -String identifying gesture. - -### Notes - -`testID` must be unique among components rendered in test. - -### Example - -See above example for `fireGestureHandler`. diff --git a/docs/docs/components/_category_.json b/docs/docs/components/_category_.json new file mode 100644 index 0000000000..640bf58fed --- /dev/null +++ b/docs/docs/components/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Components", + "position": 3, + "link": { + "type": "generated-index" + } +} diff --git a/docs/docs/api/components/buttons.mdx b/docs/docs/components/buttons.mdx similarity index 93% rename from docs/docs/api/components/buttons.mdx rename to docs/docs/components/buttons.mdx index b69da43cc0..e20bff3256 100644 --- a/docs/docs/api/components/buttons.mdx +++ b/docs/docs/components/buttons.mdx @@ -15,11 +15,11 @@ Gesture handler library provides native components that can act as buttons. Thes Currently Gesture handler library exposes three components that render native touchable elements under the hood: -- `BaseButton` -- `RectButton` -- `BorderlessButton` +- [`BaseButton`](/docs/components/buttons/#basebutton) +- [`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](#common-gesturehandler-properties) and `NativeViewGestureHandler`'s [extra properties](#nativeviewgesturehandler-extra-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/gesture-handlers/common-gh/) and `NativeViewGestureHandler`'s [extra properties](/docs/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: @@ -75,7 +75,7 @@ defines the delay, in milliseconds, after which the `onLongPress` callback gets ## `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`](#basebutton-component), it accepts the following: +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/components/buttons#basebutton), it accepts the following: Below is a list of properties specific to `RectButton` component: @@ -89,7 +89,7 @@ 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`](#basebutton-component), it accepts the following: +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/components/buttons#basebutton), it accepts the following: Below is a list of properties specific to `BorderlessButton` component: diff --git a/docs/versioned_docs/version-2.3.0/api/components/drawer-layout.mdx b/docs/docs/components/drawer-layout.mdx similarity index 90% rename from docs/versioned_docs/version-2.3.0/api/components/drawer-layout.mdx rename to docs/docs/components/drawer-layout.mdx index 04abc42c72..b6ac2c18fb 100644 --- a/docs/versioned_docs/version-2.3.0/api/components/drawer-layout.mdx +++ b/docs/docs/components/drawer-layout.mdx @@ -7,7 +7,7 @@ sidebar_label: DrawerLayout import useBaseUrl from '@docusaurus/useBaseUrl'; import GifGallery from '@site/components/GifGallery'; -This is a cross-platform replacement for React Native's [DrawerLayoutAndroid](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) component. It provides a compatible API but allows for the component to be used on both Android and iOS. Please refer to [React Native docs](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) for the detailed usage for standard parameters. +This is a cross-platform replacement for React Native's [DrawerLayoutAndroid](http://reactnative.dev/docs/drawerlayoutandroid.html) component. It provides a compatible API but allows for the component to be used on both Android and iOS. Please refer to [React Native docs](http://reactnative.dev/docs/drawerlayoutandroid.html) for the detailed usage for standard parameters. ## Usage: @@ -49,11 +49,11 @@ number, allows for defining how far from the edge of the content view the gestur ### `hideStatusBar` -boolean, when set to `true` Drawer component will use [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html) API to hide the OS status bar whenever the drawer is pulled or when its in an "open" state. +boolean, when set to `true` Drawer component will use [StatusBar](http://reactnative.dev/docs/statusbar.html) API to hide the OS status bar whenever the drawer is pulled or when its in an "open" state. ### `statusBarAnimation` -possible values are: `slide`, `none` or `fade` (defaults to `slide`). Can be used when `hideStatusBar` is set to `true` and will select the animation used for hiding/showing the status bar. See [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html#statusbaranimation) documentation for more details. +possible values are: `slide`, `none` or `fade` (defaults to `slide`). Can be used when `hideStatusBar` is set to `true` and will select the animation used for hiding/showing the status bar. See [StatusBar](http://reactnative.dev/docs/statusbar.html#statusbaranimation) documentation for more details. ### `overlayColor` diff --git a/docs/docs/api/components/swipeable.md b/docs/docs/components/swipeable.md similarity index 100% rename from docs/docs/api/components/swipeable.md rename to docs/docs/components/swipeable.md diff --git a/docs/versioned_docs/version-2.4.0/api/components/touchables.md b/docs/docs/components/touchables.md similarity index 84% rename from docs/versioned_docs/version-2.4.0/api/components/touchables.md rename to docs/docs/components/touchables.md index 4b45292f72..1882c08c66 100644 --- a/docs/versioned_docs/version-2.4.0/api/components/touchables.md +++ b/docs/docs/components/touchables.md @@ -8,10 +8,10 @@ Gesture Handler library provides an implementation of RN's touchable components React Native's touchables API can be found here: -- [Touchable Native Feedback](https://facebook.github.io/react-native/docs/touchablenativefeedback) -- [Touchable Highlight](https://facebook.github.io/react-native/docs/touchablehighlight) -- [Touchable Opacity](https://facebook.github.io/react-native/docs/touchableopacity) -- [Touchable Without Feedback](https://facebook.github.io/react-native/docs/touchablewithoutfeedback) +- [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. diff --git a/docs/docs/fundamentals/_category_.json b/docs/docs/fundamentals/_category_.json new file mode 100644 index 0000000000..ea8044f531 --- /dev/null +++ b/docs/docs/fundamentals/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Fundamentals", + "position": 1, + "link": { + "type": "generated-index" + } +} diff --git a/docs/docs/fundamentals/gesture-composition.md b/docs/docs/fundamentals/gesture-composition.md new file mode 100644 index 0000000000..fc5093aeb1 --- /dev/null +++ b/docs/docs/fundamentals/gesture-composition.md @@ -0,0 +1,206 @@ +--- +id: gesture-composition +title: Composing gestures +sidebar_label: Composing gestures +sidebar_position: 4 +--- + +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); + s; + 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 ( + + + + ); +} +``` + +## Composition vs `simultaneousWithExternalGesture` and `requireExternalGestureToFail` + +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. If you want to make a relation between gestures that are attached to separate `GestureDetectors`, we have a separate mechanism for that: `simultaneousWithExternalGesture` and `requireExternalGestureToFail` methods that are available on every base gesture. They work exactly the same way as `simultaneousHandlers` and `waitFor` on gesture handlers, that is they just mark the relation between the gestures without joining them into single object. diff --git a/docs/docs/installation.md b/docs/docs/fundamentals/installation.md similarity index 93% rename from docs/docs/installation.md rename to docs/docs/fundamentals/installation.md index 0603304f83..c80689904b 100644 --- a/docs/docs/installation.md +++ b/docs/docs/fundamentals/installation.md @@ -1,6 +1,7 @@ --- id: installation title: Installation +sidebar_position: 2 --- ## Requirements @@ -16,9 +17,9 @@ title: Installation It may be possible to use newer versions of react-native-gesture-handler on React Native with version <= 0.59 by reverse Jetifying. Read more on that here https://github.com/mikehardy/jetifier#to-reverse-jetify--convert-node_modules-dependencies-to-support-libraries -Note that if you wish to use [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html) support for [interactions](./gesture-handlers/basics/interactions.md) you need to use v16.3 of [React](https://reactjs.org/) +Note that if you wish to use [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html) support for [interactions](/docs/gesture-handlers/interactions/) you need to use v16.3 of [React](https://reactjs.org/) -In order to fully utilize the [touch events](./api/gestures/touch-events.md) you also need to use `react-native-reanimated` 2.3.0-beta.4 or newer. +In order to fully utilize the [touch events](/docs/gestures/touch-events/) you also need to use `react-native-reanimated` 2.3.0-beta.4 or newer. ## Expo @@ -28,7 +29,7 @@ To use the version of react-native-gesture-handler that is compatible with your The Expo SDK incorporates the latest version of react-native-gesture-handler available at the time of each SDK release, so managed Expo apps might not always support all our latest features as soon as they are available. -### Bare [React Native](http://facebook.github.io/react-native/) +### Bare [React Native](http://reactnative.dev/) Since the library uses native support for handling gestures, it requires an extended installation to the norm. If you are starting a new project, you may want to initialize it with [expo-cli](https://docs.expo.io/versions/latest/workflow/expo-cli/) and use a bare template, they come pre-installed with react-native-gesture-handler. @@ -52,6 +53,8 @@ After installation, wrap your entry point with `` or For example: ```js +import { GestureHandlerRootView } from 'react-native-gesture-handler'; + export default function App() { return ( @@ -135,6 +138,8 @@ To fix that, components need to be wrapped with `gestureHandlerRootHOC` (it's no For example: ```js +import { gestureHandlerRootHOC } from 'react-native-gesture-handler'; + const ExampleWithHoc = gestureHandlerRootHOC(() => ( diff --git a/docs/docs/introduction.md b/docs/docs/fundamentals/introduction.md similarity index 94% rename from docs/docs/introduction.md rename to docs/docs/fundamentals/introduction.md index e076b6f562..5d96d42832 100644 --- a/docs/docs/introduction.md +++ b/docs/docs/fundamentals/introduction.md @@ -2,10 +2,11 @@ id: introduction title: Introduction sidebar_label: Introduction +sidebar_position: 1 slug: / --- -Gesture Handler aims to replace React Native's built in touch system called [Gesture Responder System](http://facebook.github.io/react-native/docs/gesture-responder-system). +Gesture Handler aims to replace React Native's built in touch system called [Gesture Responder System](http://reactnative.dev/docs/gesture-responder-system). The motivation for building this library was to address the performance limitations of React Native's Gesture Responder System and to provide more control over the built-in native components that can handle gestures. 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. @@ -23,8 +24,8 @@ It is recommended to use Reanimated 2 for animations when using React Native Ges ## RNGH 2.0 RNGH2 introduces a new way of creating gestures. Instead of creating a gesture handler component for every gesture you want to create, you just need to create a `GestureDetector` component and assign to it all the gestures you want it to recognize. It is also designed to work seamlessly with `Reanimated 2` and it will automatically detect if it is installed, and start using it if it is. -You can create gestures using the `Gesture` object and methods it provides, and configure them in the builder-like pattern. If you want to specify behavior between the gestures instead of using `waitFor` and `simultaneousGestures` you can use the new system of [gesture composition](./gesture-composition). -Along the new API, version 2.0 brings one of the most requested features: [touch events and manual gestures](manual-gestures). Thanks to great work done by the Reanimated team, we were able to provide synchronous communication between gestures and their native implementation using worklets. This allows to manage gesture state from the JS without risking race-conditions. +You can create gestures using the `Gesture` object and methods it provides, and configure them in the builder-like pattern. If you want to specify behavior between the gestures instead of using `waitFor` and `simultaneousGestures` you can use the new system of [gesture composition](/docs/fundamentals/gesture-composition). +Along the new API, version 2.0 brings one of the most requested features: [touch events and manual gestures](/docs/fundamentals/manual-gestures). Thanks to great work done by the Reanimated team, we were able to provide synchronous communication between gestures and their native implementation using worklets. This allows to manage gesture state from the JS without risking race-conditions. ### Interoperability with gesture handlers @@ -37,12 +38,15 @@ This should allow you to migrate your codebase from the gesture handlers to gest ### Automatic workletization of gesture callbacks Reanimated's Babel plugin is setup in a way that automatically marks callbacks passed to gestures in the configuration chain as worklets. This means that as long as all your callbacks are defined in a single chain, you don't need to add a `'worklet';` directive at the beginning of the functions. Here is an example that will be automatically workletized: + ```jsx const gesture = Gesture.Tap().onBegin(() => { console.log(_WORKLET); }); ``` + And here are some examples that won't: + ```jsx const gesture = Gesture.Tap(); gesture.onBegin(() => { diff --git a/docs/docs/manual-gestures/step1.md b/docs/docs/fundamentals/manual-gestures/_steps/step1.md similarity index 100% rename from docs/docs/manual-gestures/step1.md rename to docs/docs/fundamentals/manual-gestures/_steps/step1.md diff --git a/docs/versioned_docs/version-2.1.1/manual-gestures/step2.md b/docs/docs/fundamentals/manual-gestures/_steps/step2.md similarity index 84% rename from docs/versioned_docs/version-2.1.1/manual-gestures/step2.md rename to docs/docs/fundamentals/manual-gestures/_steps/step2.md index 3137d334ef..40079ee2bd 100644 --- a/docs/versioned_docs/version-2.1.1/manual-gestures/step2.md +++ b/docs/docs/fundamentals/manual-gestures/_steps/step2.md @@ -1,4 +1,10 @@ ```jsx +import { StyleSheet } from 'react-native'; +import Animated, { + useAnimatedStyle, + useSharedValue, +} from 'react-native-reanimated'; + function PointerElement(props: { pointer: Animated.SharedValue, active: Animated.SharedValue, @@ -19,7 +25,7 @@ function PointerElement(props: { return ; } -... +// ... const styles = StyleSheet.create({ pointer: { diff --git a/docs/docs/manual-gestures/step3.md b/docs/docs/fundamentals/manual-gestures/_steps/step3.md similarity index 89% rename from docs/docs/manual-gestures/step3.md rename to docs/docs/fundamentals/manual-gestures/_steps/step3.md index c9b32e5c2a..4486b0a123 100644 --- a/docs/docs/manual-gestures/step3.md +++ b/docs/docs/fundamentals/manual-gestures/_steps/step3.md @@ -1,4 +1,6 @@ ```jsx +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; + export default function Example() { const trackedPointers: Animated.SharedValue[] = []; const active = useSharedValue(false); diff --git a/docs/docs/manual-gestures/step4.md b/docs/docs/fundamentals/manual-gestures/_steps/step4.md similarity index 100% rename from docs/docs/manual-gestures/step4.md rename to docs/docs/fundamentals/manual-gestures/_steps/step4.md diff --git a/docs/docs/manual-gestures/step5.md b/docs/docs/fundamentals/manual-gestures/_steps/step5.md similarity index 100% rename from docs/docs/manual-gestures/step5.md rename to docs/docs/fundamentals/manual-gestures/_steps/step5.md diff --git a/docs/docs/manual-gestures/step6.md b/docs/docs/fundamentals/manual-gestures/_steps/step6.md similarity index 100% rename from docs/docs/manual-gestures/step6.md rename to docs/docs/fundamentals/manual-gestures/_steps/step6.md diff --git a/docs/docs/manual-gestures/step7.md b/docs/docs/fundamentals/manual-gestures/_steps/step7.md similarity index 100% rename from docs/docs/manual-gestures/step7.md rename to docs/docs/fundamentals/manual-gestures/_steps/step7.md diff --git a/docs/docs/manual-gestures/manual-gestures.md b/docs/docs/fundamentals/manual-gestures/index.md similarity index 92% rename from docs/docs/manual-gestures/manual-gestures.md rename to docs/docs/fundamentals/manual-gestures/index.md index eae7fffd2d..9d2f70ff31 100644 --- a/docs/docs/manual-gestures/manual-gestures.md +++ b/docs/docs/fundamentals/manual-gestures/index.md @@ -2,16 +2,17 @@ id: manual-gestures title: Manual gestures sidebar_label: Manual gestures +sidebar_position: 5 --- import Step, { Divider } from '@site/src/theme/Step'; -import Step1 from './step1.md'; -import Step2 from './step2.md'; -import Step3 from './step3.md'; -import Step4 from './step4.md'; -import Step5 from './step5.md'; -import Step6 from './step6.md'; -import Step7 from './step7.md'; +import Step1 from './\_steps/step1.md'; +import Step2 from './\_steps/step2.md'; +import Step3 from './\_steps/step3.md'; +import Step4 from './\_steps/step4.md'; +import Step5 from './\_steps/step5.md'; +import Step6 from './\_steps/step6.md'; +import Step7 from './\_steps/step7.md'; RNGH2 finally brings one of the most requested features: manual gestures and touch events. To demonstrate how to make a manual gesture we will make a simple one that tracks all pointers on the screen. diff --git a/docs/versioned_docs/version-2.1.1/quickstart/step1.md b/docs/docs/fundamentals/quickstart/_steps/step1.md similarity index 79% rename from docs/versioned_docs/version-2.1.1/quickstart/step1.md rename to docs/docs/fundamentals/quickstart/_steps/step1.md index 1995cd907c..6e5c8de76b 100644 --- a/docs/versioned_docs/version-2.1.1/quickstart/step1.md +++ b/docs/docs/fundamentals/quickstart/_steps/step1.md @@ -1,4 +1,6 @@ ```jsx +import { StyleSheet } from 'react-native'; + const styles = StyleSheet.create({ ball: { width: 100, diff --git a/docs/versioned_docs/version-2.0.0/quickstart/step2.md b/docs/docs/fundamentals/quickstart/_steps/step2.md similarity index 54% rename from docs/versioned_docs/version-2.0.0/quickstart/step2.md rename to docs/docs/fundamentals/quickstart/_steps/step2.md index 34c528266b..7292504d92 100644 --- a/docs/versioned_docs/version-2.0.0/quickstart/step2.md +++ b/docs/docs/fundamentals/quickstart/_steps/step2.md @@ -1,4 +1,7 @@ ```jsx +import { GestureDetector } from 'react-native-gesture-handler'; +import Animated from 'react-native-reanimated'; + function Ball() { return ( diff --git a/docs/docs/fundamentals/quickstart/_steps/step3.md b/docs/docs/fundamentals/quickstart/_steps/step3.md new file mode 100644 index 0000000000..5060a4d788 --- /dev/null +++ b/docs/docs/fundamentals/quickstart/_steps/step3.md @@ -0,0 +1,25 @@ +```jsx +import { + useSharedValue, + useAnimatedStyle, + withSpring, +} from 'react-native-reanimated'; + +function App() { + const isPressed = useSharedValue(false); + const offset = useSharedValue({ x: 0, y: 0 }); + + const animatedStyles = useAnimatedStyle(() => { + return { + transform: [ + { translateX: offset.value.x }, + { translateY: offset.value.y }, + { scale: withSpring(isPressed.value ? 1.2 : 1) }, + ], + backgroundColor: isPressed.value ? 'yellow' : 'blue', + }; + }); + + // ... +} +``` diff --git a/docs/versioned_docs/version-2.0.0/quickstart/step4.md b/docs/docs/fundamentals/quickstart/_steps/step4.md similarity index 90% rename from docs/versioned_docs/version-2.0.0/quickstart/step4.md rename to docs/docs/fundamentals/quickstart/_steps/step4.md index 8e2112a3cd..7750e97e3b 100644 --- a/docs/versioned_docs/version-2.0.0/quickstart/step4.md +++ b/docs/docs/fundamentals/quickstart/_steps/step4.md @@ -1,9 +1,9 @@ ```jsx {4} -... +// ... return ( ); -... +// ... ``` diff --git a/docs/docs/fundamentals/quickstart/_steps/step5.md b/docs/docs/fundamentals/quickstart/_steps/step5.md new file mode 100644 index 0000000000..036edee6df --- /dev/null +++ b/docs/docs/fundamentals/quickstart/_steps/step5.md @@ -0,0 +1,38 @@ +```jsx +import { Gesture } from 'react-native-gesture-handler'; + +function App() { + // ... + const start = useSharedValue({ x: 0, y: 0 }); + const gesture = Gesture.Pan() + .onBegin(() => { + isPressed.value = 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, + }; + }) + .onFinalize(() => { + isPressed.value = false; + }); + // ... +} +``` + +```jsx {3} +// ... +return ( + + + +); +// ... +``` diff --git a/docs/versioned_docs/version-2.1.1/quickstart/quickstart.md b/docs/docs/fundamentals/quickstart/index.md similarity index 84% rename from docs/versioned_docs/version-2.1.1/quickstart/quickstart.md rename to docs/docs/fundamentals/quickstart/index.md index c1ba3d7219..77a9457d1b 100644 --- a/docs/versioned_docs/version-2.1.1/quickstart/quickstart.md +++ b/docs/docs/fundamentals/quickstart/index.md @@ -2,16 +2,17 @@ id: quickstart title: Quick start sidebar_label: Quick start +sidebar_position: 3 --- import Step, { Divider } from '@site/src/theme/Step'; -import Step1 from './step1.md'; -import Step2 from './step2.md'; -import Step3 from './step3.md'; -import Step4 from './step4.md'; -import Step5 from './step5.md'; +import Step1 from './\_steps/step1.md'; +import Step2 from './\_steps/step2.md'; +import Step3 from './\_steps/step3.md'; +import Step4 from './\_steps/step4.md'; +import Step5 from './\_steps/step5.md'; -RNGH2 provides much simpler way to add gestures to your app. All you need to do is wrap the view that you want your gesture to work on with [`GestureDetector`](../api/gestures/gesture-detector), define the gesture and pass it to detector. That's all! +RNGH2 provides much simpler way to add gestures to your app. All you need to do is wrap the view that you want your gesture to work on with [`GestureDetector`](/docs/gestures/gesture-detector), define the gesture and pass it to detector. That's all! To demonstrate how you would use the new API, let's make a simple app where you can drag a ball around. You will need to add `react-native-gesture-handler` (for gestures) and `react-native-reanimated` (for animations) modules. diff --git a/docs/versioned_docs/version-2.1.1/under-the-hood/states-events.md b/docs/docs/fundamentals/states-events.md similarity index 99% rename from docs/versioned_docs/version-2.1.1/under-the-hood/states-events.md rename to docs/docs/fundamentals/states-events.md index 600f16a5cc..39347ebe5b 100644 --- a/docs/versioned_docs/version-2.1.1/under-the-hood/states-events.md +++ b/docs/docs/fundamentals/states-events.md @@ -2,6 +2,7 @@ id: states-events title: Gesture states & events sidebar_label: Gesture states & events +sidebar_position: 6 --- Every gesture can be treated as ["state machine"](https://en.wikipedia.org/wiki/Finite-state_machine). diff --git a/docs/docs/gesture-composition.md b/docs/docs/gesture-composition.md deleted file mode 100644 index e55e06fae6..0000000000 --- a/docs/docs/gesture-composition.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -id: gesture-composition -title: Composing gestures -sidebar_label: Composing gestures ---- - -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 -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 -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 -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 ( - - - -); -``` - -## Composition vs `simultaneousWithExternalGesture` and `requireExternalGestureToFail` - -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. If you want to make a relation between gestures that are attached to separate `GestureDetectors`, we have a separate mechanism for that: `simultaneousWithExternalGesture` and `requireExternalGestureToFail` methods that are available on every base gesture. They work exactly the same way as `simultaneousHandlers` and `waitFor` on gesture handlers, that is they just mark the relation between the gestures without joining them into single object. diff --git a/docs/docs/gesture-handlers/_category_.json b/docs/docs/gesture-handlers/_category_.json new file mode 100644 index 0000000000..ba4a9561bd --- /dev/null +++ b/docs/docs/gesture-handlers/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Gesture handlers (legacy)", + "position": 4, + "link": { + "type": "generated-index" + } +} diff --git a/docs/docs/gesture-handlers/basics/about-handlers.md b/docs/docs/gesture-handlers/about-handlers.md similarity index 68% rename from docs/docs/gesture-handlers/basics/about-handlers.md rename to docs/docs/gesture-handlers/about-handlers.md index 4c2062a24f..4f20ddabe5 100644 --- a/docs/docs/gesture-handlers/basics/about-handlers.md +++ b/docs/docs/gesture-handlers/about-handlers.md @@ -2,8 +2,13 @@ id: about-handlers title: About Gesture Handlers sidebar_label: About Gesture Handlers +sidebar_position: 1 --- +:::warning +Consider using the new [gestures API](/docs/gestures/gesture) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](/docs/#rngh-20) for more information. +::: + Gesture handlers are the core building blocks of this library. We use this term to describe elements of the native touch system that the library allows us to instantiate and control from Javascript using [React's Component](https://reactjs.org/docs/react-component.html) interface. @@ -11,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](./state.md). +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). 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](./state.md#active), it cancels all the other gestures (read more about how to influence this process in ["Cross handler interactions"](./interactions.md) section). +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). 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. @@ -23,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`](../api/pan-gh.md) -- [`TapGestureHandler`](../api/tap-gh.md) -- [`LongPressGestureHandler`](../api/longpress-gh.md) -- [`RotationGestureHandler`](../api/rotation-gh.md) -- [`FlingGestureHandler`](../api/fling-gh.md) -- [`PinchGestureHandler`](../api/pinch-gh.md) -- [`ForceTouchGestureHandler`](../api/force-gh.md) +- [`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) ### Discrete vs continuous We distinguish between two types of gestures: discrete and continuous. -Continuous gesture handlers can be [active](./state.md#active) for a long period of time and will generate a stream of [gesture events](../api/common-gh.md#ongestureevent) until the gesture is [over](./state.md#ended). -An example of a continuous handler is [`PanGestureHandler`](../api/pan-gh.md) that once [activated](./state.md#active), will start providing updates about [translation](../api/pan-gh.md#translationx) and other properties. +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. -On the other hand, discrete gesture handlers once [activated](./state.md#active) will not stay in the active state but will [end](./state.md#ended) immediately. -[`LongPressGestureHandler`](../api/longpress-gh.md) 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`](../api/pan-gh.md)). +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)). Keep in mind that `onGestureEvent` is only generated in continuous gesture handlers and shouldn't be used in the `TapGestureHandler` and other discrete handlers. @@ -72,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`](../api/nativeview-gh.md). +Gesture handler library exposes a set of components normally available in React Native that are wrapped in [`NativeViewGestureHandler`](/docs/gesture-handlers/nativeview-gh). Here is a list of exposed components: - `ScrollView` @@ -81,7 +86,7 @@ Here is a list of exposed components: - `TextInput` - `DrawerLayoutAndroid` (**Android only**) -If you want to use other handlers or [buttons](../../api/components/buttons.mdx) nested in a `ScrollView`, use the [`waitFor`](../api/common-gh.md#waitfor) property to define interaction between a handler and `ScrollView` +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` ### Events with `useNativeDriver` diff --git a/docs/docs/gesture-handlers/api/create-native-wrapper.md b/docs/docs/gesture-handlers/api/create-native-wrapper.md deleted file mode 100644 index a33fd58d36..0000000000 --- a/docs/docs/gesture-handlers/api/create-native-wrapper.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: create-native-wrapper -title: createNativeWrapper -sidebar_label: createNativeWrapper() ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -Creates provided component with NativeViewGestureHandler, allowing it to be part of RNGH's -gesture system. - -## Arguments - -### Component - -The component we want to wrap. - -### config - -Config is an object with properties that can be used on [`NativeViewGestureHandler`](./nativeview-gh.md) - -## Returns - -Wrapped component. diff --git a/docs/docs/gesture-handlers/api/fling-gh.md b/docs/docs/gesture-handlers/api/fling-gh.md deleted file mode 100644 index b356e09cc0..0000000000 --- a/docs/docs/gesture-handlers/api/fling-gh.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -id: fling-gh -title: FlingGestureHandler -sidebar_label: Fling ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A discrete gesture handler that activates when the movement is sufficiently long and fast. -Handler gets [ACTIVE](../basics/state#active) when movement is sufficiently long and it does not take too much time. -When handler gets activated it will turn into [END](../basics/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](./common-gh.md#properties). Below is a list of properties specific to `FlingGestureHandler` component: - -### `direction` - -Expressed allowed direction of movement. It's possible to pass one or many directions in one parameter: - -```js -direction={Directions.RIGHT | Directions.LEFT} -``` - -or - -```js -direction={Directions.DOWN} -``` - -### `numberOfPointers` - -Determine exact number of points required to handle the fling gesture. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `FlingGestureHandler`: - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - -## Example - -See the [fling example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/release_tests/fling/index.tsx) from Gesture Handler Example App. - -```js -const LongPressButton = () => ( - { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert("I'm flinged!"); - } - }}> - - -); -``` diff --git a/docs/docs/gesture-handlers/api/force-gh.md b/docs/docs/gesture-handlers/api/force-gh.md deleted file mode 100644 index ea3bb6835e..0000000000 --- a/docs/docs/gesture-handlers/api/force-gh.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -id: force-gh -title: ForceTouchGestureHandler (iOS only) -sidebar_label: Force touch ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) 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](../basics/state.md#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. - -The handler is implemented using custom [UIGestureRecognizer](https://developer.apple.com/documentation/uikit/uigesturerecognizer) on iOS. There's no implementation provided on Android and it simply render children without any wrappers. -Since this behaviour is only provided on some iOS devices, this handler should not be used for defining any crucial behaviors. Use it only as an additional improvement and make all features to be accessed without this handler as well. - -# Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to `ForceTouchGestureHandler` component: - -### `minForce` - -A minimal pressure that is required before handler can [activate](../basics/state.md#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](../basics/state.md#failed). Should be a value from range `[0.0, 1.0]`. - -### `feedbackOnActivation` - -Boolean value defining if haptic feedback has to be performed on activation. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `ForceTouchGestureHandler`: - -### `force` - -The pressure of a touch. - -## Static method - -### `forceTouchAvailable` - -You may check if it's possible to use `ForceTouchGestureHandler` with `ForceTouchGestureHandler.forceTouchAvailable` - -## Example - -See the [force touch handler example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/forcetouch/index.tsx) from Gesture Handler Example App. - -```js - - - -``` diff --git a/docs/docs/gesture-handlers/api/longpress-gh.md b/docs/docs/gesture-handlers/api/longpress-gh.md deleted file mode 100644 index 1402df76df..0000000000 --- a/docs/docs/gesture-handlers/api/longpress-gh.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -id: longpress-gh -title: LongPressGestureHandler -sidebar_label: Long press ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) 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](../basics/state.md#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.java) on Android. - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to the `LongPressGestureHandler` component: - -### `minDurationMs` - -Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. - -### `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](../basics/state.md#active), it will fail to recognize the gesture. The default value is 10. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to the `LongPressGestureHandler` component: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `duration` - -Duration of the long press (time since the start of the event), expressed in milliseconds. - -## Example - -See the [multitap example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from GestureHandler Example App. - -```js -const LongPressButton = () => ( - { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert("I'm being pressed for so long"); - } - }} - minDurationMs={800}> - - -); -``` diff --git a/docs/docs/gesture-handlers/api/nativeview-gh.md b/docs/docs/gesture-handlers/api/nativeview-gh.md deleted file mode 100644 index d515560d36..0000000000 --- a/docs/docs/gesture-handlers/api/nativeview-gh.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: nativeview-gh -title: NativeViewGestureHandler -sidebar_label: NativeView ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A gesture handler that allows other touch handling components to participate in -RNGH's gesture system. - -Used by [`createNativeWrapper()`](./create-native-wrapper.md). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to `NativeViewGestureHandler` component: - -### `shouldActivateOnStart` (**Android only**) - -When `true`, underlying handler will activate unconditionally when in `BEGAN` or `UNDETERMINED` state. - -### `disallowInterruption` - -When `true`, cancels all other gesture handlers when this `NativeViewGestureHandler` receives an `ACTIVE` state event. diff --git a/docs/docs/gesture-handlers/api/pinch-gh.md b/docs/docs/gesture-handlers/api/pinch-gh.md deleted file mode 100644 index beaa3fb778..0000000000 --- a/docs/docs/gesture-handlers/api/pinch-gh.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: pinch-gh -title: PinchGestureHandler -sidebar_label: Pinch ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) 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](../basics/state.md#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. - -The handler is implemented using [UIPinchGestureRecognizer](https://developer.apple.com/documentation/uikit/uipinchgesturerecognizer) on iOS and from scratch on Android. - -## Properties - -Properties provided to `PinchGestureHandler` do not extend [common set of properties from base handler class](./common-gh.md#properties). - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `PinchGestureHandler`: - -### `scale` - -The scale factor relative to the points of the two touches in screen coordinates. - -### `velocity` - -Velocity of the pan gesture the current moment. The value is expressed in point units per second. - -### `focalX` - -Position expressed in points along X axis of center anchor point of gesture - -### `focalY` - -Position expressed in points along Y axis of center anchor point of gesture - -## Example - -See the [scale and rotation example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from Gesture Handler Example App. - -```js -export class PinchableBox extends React.Component { - _baseScale = new Animated.Value(1); - _pinchScale = new Animated.Value(1); - _scale = Animated.multiply(this._baseScale, this._pinchScale); - _lastScale = 1; - _onPinchGestureEvent = Animated.event( - [{ nativeEvent: { scale: this._pinchScale } }], - { useNativeDriver: USE_NATIVE_DRIVER } - ); - - _onPinchHandlerStateChange = (event) => { - if (event.nativeEvent.oldState === State.ACTIVE) { - this._lastScale *= event.nativeEvent.scale; - this._baseScale.setValue(this._lastScale); - this._pinchScale.setValue(1); - } - }; - - render() { - return ( - - - - - - ); - } -} -``` diff --git a/docs/docs/gesture-handlers/api/rotation-gh.md b/docs/docs/gesture-handlers/api/rotation-gh.md deleted file mode 100644 index 862e703afe..0000000000 --- a/docs/docs/gesture-handlers/api/rotation-gh.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -id: rotation-gh -title: RotationGestureHandler -sidebar_label: Rotation ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A continuous gesture handler that can recognize a rotation gesture and track its movement. - -The handler [activates](../basics/state.md#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. - -The handler is implemented using [UIRotationGestureRecognizer](https://developer.apple.com/documentation/uikit/uirotationgesturerecognizer) on iOS and from scratch on Android. - -## Properties - -Properties provided to `RotationGestureHandler` do not extend [common set of properties from base handler class](./common-gh.md#properties). - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `RotationGestureHandler`: - -### `rotation` - -Amount rotated, expressed in radians, from the gesture's focal point (anchor). - -### `velocity` - -Instantaneous velocity, expressed in point units per second, of the gesture. - -### `anchorX` - -X coordinate, expressed in points, of the gesture's central focal point (anchor). - -### `anchorY` - -Y coordinate, expressed in points, of the gesture's central focal point (anchor). - -## Example - -See the [scale and rotation example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from Gesture Handler Example App. - -```js -class RotableBox extends React.Component { - _rotate = new Animated.Value(0); - _rotateStr = this._rotate.interpolate({ - inputRange: [-100, 100], - outputRange: ['-100rad', '100rad'], - }); - _lastRotate = 0; - _onRotateGestureEvent = Animated.event( - [{ nativeEvent: { rotation: this._rotate } }], - { useNativeDriver: USE_NATIVE_DRIVER } - ); - _onRotateHandlerStateChange = (event) => { - if (event.nativeEvent.oldState === State.ACTIVE) { - this._lastRotate += event.nativeEvent.rotation; - this._rotate.setOffset(this._lastRotate); - this._rotate.setValue(0); - } - }; - render() { - return ( - - - - ); - } -} -``` diff --git a/docs/docs/gesture-handlers/api/tap-gh.md b/docs/docs/gesture-handlers/api/tap-gh.md deleted file mode 100644 index 74fa3ee114..0000000000 --- a/docs/docs/gesture-handlers/api/tap-gh.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -id: tap-gh -title: TapGestureHandler -sidebar_label: Tap ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A discrete gesture handler 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 handler to [activate](../basics/state.md#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](../basics/state.md#active), it will [END](../basics/state.md#end). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#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](../basics/state.md#active). Should be a positive integer. The default value is 1. - -### `maxDurationMs` - -Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch. The default value is 500. - -### `maxDelayMs` - -Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required. The default value is 500. - -### `numberOfTaps` - -Number of tap gestures required to [activate](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#active), it will fail to recognize the gesture. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to the `TapGestureHandler` component: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -## Example - -See the [multitap example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from GestureHandler Example App. - -```js -export class PressBox extends Component { - doubleTapRef = React.createRef(); - render() { - return ( - - - - - - ); - } -} -``` diff --git a/docs/docs/gesture-handlers/basics/interactions.md b/docs/docs/gesture-handlers/basics/interactions.md deleted file mode 100644 index 5b7408cf5f..0000000000 --- a/docs/docs/gesture-handlers/basics/interactions.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -id: interactions -title: Cross handler interactions -sidebar_label: Cross handler interactions ---- - -Gesture handlers can "communicate" with each other to support complex gestures and control how they _[activate](./state.md#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. -Gesture handler relies on ref objects created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html) and introduced in [React 16.3](https://reactjs.org/blog/2018/03/29/react-v-16-3.html#createref-api). - -## Simultaneous recognition - -By default, only one gesture handler is allowed to be in the [`ACTIVE`](./state.md#active) state. -So when a gesture handler recognizes a gesture it [cancels](./state.md#cancelled) all other handlers in the [`BEGAN`](./state.md#began) state and prevents any new handlers from receiving a stream of touch events as long as it remains [`ACTIVE`](./state.md#active). - -This behavior can be altered using the [`simultaneousHandlers`](../api/common-gh.md#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`](./state.md#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`](../api/pinch-gh.md), [`RotationGestureHandler`](../api/rotation-gh.md) and [`PanGestureHandler`](../api/pan-gh.md) that would have to simultaneously recognize gestures. - -### Example - -See the ["Scale, rotate & tilt" example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from the GestureHandler Example App or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -class PinchableBox extends React.Component { - // ...take a look on full implementation in an Example app - render() { - const imagePinch = React.createRef(); - const imageRotation = React.createRef(); - return ( - - - - - - - - - - ); - } -} -``` - -## Awaiting other handlers - -### Use cases - -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](./state.md#cancelled) the double tap handler. - -### Example - -See the ["Multitap" example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from GestureHandler Example App or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -const doubleTap = React.createRef(); -const PressBox = () => ( - - nativeEvent.state === State.ACTIVE && Alert.alert('Single tap!') - } - waitFor={doubleTap}> - - nativeEvent.state === State.ACTIVE && Alert.alert("You're so fast") - } - numberOfTaps={2}> - - - -); -``` diff --git a/docs/docs/gesture-handlers/basics/state.md b/docs/docs/gesture-handlers/basics/state.md deleted file mode 100644 index 1f15f94f2f..0000000000 --- a/docs/docs/gesture-handlers/basics/state.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: state -title: Handler State -sidebar_label: Handler State ---- - -As described in ["About Gesture Handlers"](./about-handlers.md), 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: - -- [UNDETERMINED](#undetermined) -- [FAILED](#failed) -- [BEGAN](#began) -- [CANCELLED](#cancelled) -- [ACTIVE](#active) -- [END](#end) - -Each state has its own description below. - -## Accessing state - -We can monitor a handler's state changes by using the [`onHandlerStateChange`](../api/common-gh.md#onhandlerstatechange) callback and the destructured `nativeEvent` argument passed to it. -This can be done by comparing the `nativeEvent`'s [`state`](../api/common-gh.md#state) attribute to one of the constants exported under the `State` object (see example below). - -``` -import { State, LongPressGestureHandler } from 'react-native-gesture-handler'; - -class Demo extends Component { - _handleStateChange = ({ nativeEvent }) => { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert('Longpress'); - } - }; - render() { - return ( - - Longpress me - - ); - } -} -``` - -## State flows - -The most typical flow of state is when a gesture handler picks up on an initial touch event then recognizes it then acknowledges its ending then resets itself back to the initial state. - -The flow looks as follows (longer arrows represent that there are possibly more touch events received before the state changes): - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`END`](#end) -> [`UNDETERMINED`](#undetermined) - -Another possible flow is when a handler receives touches that cause a recognition failure: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`FAILED`](#failed) -> [`UNDETERMINED`](#undetermined) - -At last, when a handler does properly recognize the gesture but then is interrupted by the touch system. In that case, the gesture recognition is canceled and the flow looks as follows: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`CANCELLED`](#cancelled) -> [`UNDETERMINED`](#undetermined) - -## States - -The section below describes all possible handler states: - -### UNDETERMINED - -This is the initial state of each handler and it goes into this state after it's done recognizing a gesture. - -### FAILED - -A handler 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 handler won't become active but will fail instead. Afterwards, it's state will be reset to `UNDETERMINED`. - -### BEGAN - -Handler 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 - -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](about-handlers#discrete-vs-continuous) to understand how long a handler can be kept in the `ACTIVE` state. - -### END - -The gesture recognizer has received touches signalling the end of a gesture. Its state will become `END` until it is reset to `UNDETERMINED`. diff --git a/docs/docs/gesture-handlers/api/common-gh.md b/docs/docs/gesture-handlers/common-gh.md similarity index 58% rename from docs/docs/gesture-handlers/api/common-gh.md rename to docs/docs/gesture-handlers/common-gh.md index e933c6334d..57cb9e555f 100644 --- a/docs/docs/gesture-handlers/api/common-gh.md +++ b/docs/docs/gesture-handlers/common-gh.md @@ -2,10 +2,11 @@ id: common-gh title: Common handler properties sidebar_label: Common handler properties +sidebar_position: 4 --- :::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. +Consider using the new [gestures API](/docs/gestures/gesture) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](/docs/#rngh-20) for more information. ::: This page covers the common set of properties all gesture handler components expose. @@ -13,7 +14,7 @@ This page covers the common set of properties all gesture handler components exp ### Units All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". -These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://facebook.github.io/react-native/docs/flexbox.html)). +These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://reactnative.dev/docs/flexbox.html)). They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. ## Properties @@ -24,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`](../basics/state.md#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`](../basics/state.md#failed) or [`CANCELLED`](../basics/state.md#cancelled) (depending on its current state). +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). Default value is `true`. ### `shouldCancelWhenOutside` Accepts a boolean value. -When `true` the handler will [cancel](../basics/state.md#cancelled) or [fail](../basics/state.md#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. +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. 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.md) and [`TapGestureHandler`](./tap-gh.md) which default to `true`. +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`. ### `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`](../basics/state.md#active). +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). 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](../basics/state.md#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](../basics/state.md#active) state. It will also prevent the provided handlers from [cancelling](../basics/state.md#cancelled) the current handler when they [activate](../basics/state.md#active). Read more in the [cross handler interaction](../basics/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/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. ### `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](../basics/state.md#active) as long as the handlers provided by their refs are in the [`BEGAN`](../basics/state.md#began) state. Read more in the [cross handler interaction](../basics/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/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. ### `hitSlop` -This parameter enables control over what part of the connected view area can be used to [begin](../basics/state.md#began) recognizing the gesture. +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. 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. @@ -61,7 +62,7 @@ When `width` is set it is only allow to specify one of the sides `right` or `lef 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://facebook.github.io/react-native/docs/view.html#props) property. +**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#props) property. ### `userSelect` (**web only**) @@ -73,19 +74,19 @@ 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](../basics/state.md#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.md#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/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. -Instead of a callback [`Animated.event`](https://facebook.github.io/react-native/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. +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](../basics/state.md) of the given handler changes. +Takes a callback that is going to be triggered when [state](/docs/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](../basics/state.md) of the handler right before the change. +In addition `onHandlerStateChange` event payload contains `oldState` attribute which represents the [state](/docs/under-the-hood/state) of the handler right before the change. -Instead of a callback [`Animated.event`](https://facebook.github.io/react-native/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. +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**. ## Event data @@ -93,7 +94,7 @@ This section describes the attributes of event object being provided to [`onGest ### `state` -Current [state](../basics/state.md) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](../basics/state.md) to learn more about how to use it. +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. ### `numberOfPointers` diff --git a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/create-native-wrapper.md b/docs/docs/gesture-handlers/create-native-wrapper.md similarity index 55% rename from docs/versioned_docs/version-2.4.0/gesture-handlers/api/create-native-wrapper.md rename to docs/docs/gesture-handlers/create-native-wrapper.md index a33fd58d36..40bdeb0a12 100644 --- a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/create-native-wrapper.md +++ b/docs/docs/gesture-handlers/create-native-wrapper.md @@ -2,10 +2,11 @@ id: create-native-wrapper title: createNativeWrapper sidebar_label: createNativeWrapper() +sidebar_position: 13 --- :::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. +Consider using the new [gestures API](/docs/gestures/gesture) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](/docs/#rngh-20) for more information. ::: Creates provided component with NativeViewGestureHandler, allowing it to be part of RNGH's @@ -19,7 +20,7 @@ The component we want to wrap. ### config -Config is an object with properties that can be used on [`NativeViewGestureHandler`](./nativeview-gh.md) +Config is an object with properties that can be used on [`NativeViewGestureHandler`](/docs/gesture-handlers/nativeview-gh) ## Returns diff --git a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/fling-gh.md b/docs/docs/gesture-handlers/fling-gh.md similarity index 73% rename from docs/versioned_docs/version-2.6.0/gesture-handlers/api/fling-gh.md rename to docs/docs/gesture-handlers/fling-gh.md index b356e09cc0..2709aa6558 100644 --- a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/fling-gh.md +++ b/docs/docs/gesture-handlers/fling-gh.md @@ -2,21 +2,22 @@ id: fling-gh title: FlingGestureHandler sidebar_label: Fling +sidebar_position: 9 --- :::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. +Consider using the new [gestures API](/docs/gestures/gesture) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](/docs/#rngh-20) for more information. ::: A discrete gesture handler that activates when the movement is sufficiently long and fast. -Handler gets [ACTIVE](../basics/state#active) when movement is sufficiently long and it does not take too much time. -When handler gets activated it will turn into [END](../basics/state#end) state when finger is released. +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. 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](./common-gh.md#properties). Below is a list of properties specific to `FlingGestureHandler` component: +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: ### `direction` @@ -38,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](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `FlingGestureHandler`: +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`: ### `x` diff --git a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/force-gh.md b/docs/docs/gesture-handlers/force-gh.md similarity index 66% rename from docs/versioned_docs/version-2.3.0/gesture-handlers/api/force-gh.md rename to docs/docs/gesture-handlers/force-gh.md index ea3bb6835e..62cc74224a 100644 --- a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/force-gh.md +++ b/docs/docs/gesture-handlers/force-gh.md @@ -2,14 +2,15 @@ id: force-gh title: ForceTouchGestureHandler (iOS only) sidebar_label: Force touch +sidebar_position: 11 --- :::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. +Consider using the new [gestures API](/docs/gestures/gesture) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](/docs/#rngh-20) 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](../basics/state.md#active) when pressure of touch if greater or equal than `minForce`. It fails if pressure is greater than `maxForce` +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` 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,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](./common-gh.md#properties). Below is a list of properties specific to `ForceTouchGestureHandler` component: +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: ### `minForce` -A minimal pressure that is required before handler can [activate](../basics/state.md#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/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](../basics/state.md#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/under-the-hood/state#failed). Should be a value from range `[0.0, 1.0]`. ### `feedbackOnActivation` @@ -35,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](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `ForceTouchGestureHandler`: +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`: ### `force` diff --git a/docs/versioned_docs/version-2.4.0/gesture-handlers/basics/interactions.md b/docs/docs/gesture-handlers/interactions.md similarity index 74% rename from docs/versioned_docs/version-2.4.0/gesture-handlers/basics/interactions.md rename to docs/docs/gesture-handlers/interactions.md index 5b7408cf5f..a6d480507c 100644 --- a/docs/versioned_docs/version-2.4.0/gesture-handlers/basics/interactions.md +++ b/docs/docs/gesture-handlers/interactions.md @@ -2,9 +2,14 @@ id: interactions title: Cross handler interactions sidebar_label: Cross handler interactions +sidebar_position: 3 --- -Gesture handlers can "communicate" with each other to support complex gestures and control how they _[activate](./state.md#active)_ in certain scenarios. +:::warning +Consider using the new [gestures API](/docs/gestures/gesture) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](/docs/#rngh-20) 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. 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. @@ -12,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`](./state.md#active) state. -So when a gesture handler recognizes a gesture it [cancels](./state.md#cancelled) all other handlers in the [`BEGAN`](./state.md#began) state and prevents any new handlers from receiving a stream of touch events as long as it remains [`ACTIVE`](./state.md#active). +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). -This behavior can be altered using the [`simultaneousHandlers`](../api/common-gh.md#simultaneousHandlers) property (available for all types of handlers). +This behavior can be altered using the [`simultaneousHandlers`](/docs/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`](./state.md#active) state at the same time. +Handlers connected in this way will be allowed to remain in the [`ACTIVE`](/docs/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`](../api/pinch-gh.md), [`RotationGestureHandler`](../api/rotation-gh.md) and [`PanGestureHandler`](../api/pan-gh.md) that would have to simultaneously recognize gestures. +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. ### Example @@ -70,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](./state.md#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/under-the-hood/state#cancelled) the double tap handler. ### Example diff --git a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/longpress-gh.md b/docs/docs/gesture-handlers/longpress-gh.md similarity index 73% rename from docs/versioned_docs/version-2.3.0/gesture-handlers/api/longpress-gh.md rename to docs/docs/gesture-handlers/longpress-gh.md index 1402df76df..bffa54774b 100644 --- a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/longpress-gh.md +++ b/docs/docs/gesture-handlers/longpress-gh.md @@ -2,21 +2,22 @@ id: longpress-gh title: LongPressGestureHandler sidebar_label: Long press +sidebar_position: 7 --- :::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. +Consider using the new [gestures API](/docs/gestures/gesture) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](/docs/#rngh-20) 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](../basics/state.md#end) immediately after the finger is released. +This handler's state will turn into [END](/docs/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/lib/src/main/java/com/swmansion/gesturehandler/LongPressGestureHandler.java) on Android. +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](./common-gh.md#properties). Below is a list of properties specific to the `LongPressGestureHandler` component: +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: ### `minDurationMs` @@ -24,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](../basics/state.md#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/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](./common-gh.md#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/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to the `LongPressGestureHandler` component: ### `x` diff --git a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/nativeview-gh.md b/docs/docs/gesture-handlers/nativeview-gh.md similarity index 50% rename from docs/versioned_docs/version-2.4.0/gesture-handlers/api/nativeview-gh.md rename to docs/docs/gesture-handlers/nativeview-gh.md index d515560d36..01de75e1b5 100644 --- a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/nativeview-gh.md +++ b/docs/docs/gesture-handlers/nativeview-gh.md @@ -2,20 +2,21 @@ id: nativeview-gh title: NativeViewGestureHandler sidebar_label: NativeView +sidebar_position: 12 --- :::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. +Consider using the new [gestures API](/docs/gestures/gesture) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](/docs/#rngh-20) for more information. ::: A gesture handler that allows other touch handling components to participate in RNGH's gesture system. -Used by [`createNativeWrapper()`](./create-native-wrapper.md). +Used by [`createNativeWrapper()`](/docs/gesture-handlers/create-native-wrapper). ## Properties -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to `NativeViewGestureHandler` component: +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: ### `shouldActivateOnStart` (**Android only**) diff --git a/docs/docs/gesture-handlers/api/pan-gh.md b/docs/docs/gesture-handlers/pan-gh.md similarity index 79% rename from docs/docs/gesture-handlers/api/pan-gh.md rename to docs/docs/gesture-handlers/pan-gh.md index 963e1c527f..05c195e2eb 100644 --- a/docs/docs/gesture-handlers/api/pan-gh.md +++ b/docs/docs/gesture-handlers/pan-gh.md @@ -2,15 +2,16 @@ id: pan-gh title: PanGestureHandler sidebar_label: Pan +sidebar_position: 5 --- :::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. +Consider using the new [gestures API](/docs/gestures/gesture) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](/docs/#rngh-20) for more information. ::: A continuous gesture handler that can recognize a panning (dragging) gesture and track its movement. -The handler [activates](../basics/state.md#active) when a finger is placed on the screen and moved some initial distance. +The handler [activates](/docs/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. @@ -20,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](../basics/state.md#active) or [fail](../basics/state.md#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/under-the-hood/state#active) or [fail](/docs/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. @@ -45,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](./common-gh.md#properties). Below is a list of properties specific to `PanGestureHandler` component: +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: ### `minDist` -Minimum distance the finger (or multiple finger) need to travel before the handler [activates](../basics/state.md#active). Expressed in points. +Minimum distance the finger (or multiple finger) need to travel before the handler [activates](/docs/under-the-hood/state#active). Expressed in points. ### `minPointers` -A number of fingers that is required to be placed before handler can [activate](../basics/state.md#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/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](../basics/state.md#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/under-the-hood/state#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. ### `activeOffsetX` @@ -87,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](../basics/state.md#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/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](../basics/state.md#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/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](../basics/state.md#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/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](../basics/state.md#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/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](../basics/state.md#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](../basics/state.md#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/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. ### `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](../basics/state.md#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](../basics/state.md#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/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. ### `avgTouches` (Android only) @@ -129,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](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `PanGestureHandler`: +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`: ### `translationX` diff --git a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/pinch-gh.md b/docs/docs/gesture-handlers/pinch-gh.md similarity index 81% rename from docs/versioned_docs/version-2.6.0/gesture-handlers/api/pinch-gh.md rename to docs/docs/gesture-handlers/pinch-gh.md index beaa3fb778..55fac39ad2 100644 --- a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/pinch-gh.md +++ b/docs/docs/gesture-handlers/pinch-gh.md @@ -2,14 +2,15 @@ id: pinch-gh title: PinchGestureHandler sidebar_label: Pinch +sidebar_position: 10 --- :::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. +Consider using the new [gestures API](/docs/gestures/gesture) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](/docs/#rngh-20) 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](../basics/state.md#active) when fingers are placed on the screen and change their position. +The handler [activates](/docs/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. @@ -21,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](./common-gh.md#properties). +Properties provided to `PinchGestureHandler` do not extend [common set of properties from base handler class](/docs/gesture-handlers/common-gh#properties). ## Event data -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `PinchGestureHandler`: +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`: ### `scale` diff --git a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/rotation-gh.md b/docs/docs/gesture-handlers/rotation-gh.md similarity index 77% rename from docs/versioned_docs/version-2.4.0/gesture-handlers/api/rotation-gh.md rename to docs/docs/gesture-handlers/rotation-gh.md index 862e703afe..1605c21288 100644 --- a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/rotation-gh.md +++ b/docs/docs/gesture-handlers/rotation-gh.md @@ -2,15 +2,16 @@ id: rotation-gh title: RotationGestureHandler sidebar_label: Rotation +sidebar_position: 8 --- :::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. +Consider using the new [gestures API](/docs/gestures/gesture) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](/docs/#rngh-20) for more information. ::: A continuous gesture handler that can recognize a rotation gesture and track its movement. -The handler [activates](../basics/state.md#active) when fingers are placed on the screen and change position in a proper way. +The handler [activates](/docs/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. @@ -18,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](./common-gh.md#properties). +Properties provided to `RotationGestureHandler` do not extend [common set of properties from base handler class](/docs/gesture-handlers/common-gh#properties). ## Event data -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `RotationGestureHandler`: +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`: ### `rotation` diff --git a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/tap-gh.md b/docs/docs/gesture-handlers/tap-gh.md similarity index 67% rename from docs/versioned_docs/version-2.3.0/gesture-handlers/api/tap-gh.md rename to docs/docs/gesture-handlers/tap-gh.md index 74fa3ee114..83eeb74bb6 100644 --- a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/tap-gh.md +++ b/docs/docs/gesture-handlers/tap-gh.md @@ -2,10 +2,11 @@ id: tap-gh title: TapGestureHandler sidebar_label: Tap +sidebar_position: 6 --- :::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. +Consider using the new [gestures API](/docs/gestures/gesture) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](/docs/#rngh-20) for more information. ::: A discrete gesture handler that recognizes one or many taps. @@ -15,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](../basics/state.md#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](../basics/state.md#active), it will [END](../basics/state.md#end). +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). ## Properties -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to the `TapGestureHandler` component: +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: ### `minPointers` -Minimum number of pointers (fingers) required to be placed before the handler [activates](../basics/state.md#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/under-the-hood/state#active). Should be a positive integer. The default value is 1. ### `maxDurationMs` @@ -35,23 +36,23 @@ Maximum time, expressed in milliseconds, that can pass before the next tap — i ### `numberOfTaps` -Number of tap gestures required to [activate](../basics/state.md#active) the handler. The default value is 1. +Number of tap gestures required to [activate](/docs/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](../basics/state.md#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/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](../basics/state.md#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/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](../basics/state.md#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/under-the-hood/state#active), it will fail to recognize the gesture. ## Event data -See [set of event attributes from base handler class](./common-gh.md#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/gesture-handlers/common-gh#event-data). Below is a list of gesture event attributes specific to the `TapGestureHandler` component: ### `x` diff --git a/docs/docs/gestures/_category_.json b/docs/docs/gestures/_category_.json new file mode 100644 index 0000000000..c96c8395fe --- /dev/null +++ b/docs/docs/gestures/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Gestures", + "position": 2, + "link": { + "type": "generated-index" + } +} diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/base-continous-gesture-callbacks.md b/docs/docs/gestures/_shared/base-continous-gesture-callbacks.md similarity index 87% rename from docs/versioned_docs/version-2.1.1/api/gestures/base-continous-gesture-callbacks.md rename to docs/docs/gestures/_shared/base-continous-gesture-callbacks.md index 5504b2db8d..60e2af2c48 100644 --- a/docs/versioned_docs/version-2.1.1/api/gestures/base-continous-gesture-callbacks.md +++ b/docs/docs/gestures/_shared/base-continous-gesture-callbacks.md @@ -1,4 +1,4 @@ -### Callbacks common to all continous gestures: +### Callbacks common to all continuous gestures: ### `onUpdate(callback)` diff --git a/docs/docs/api/gestures/base-continous-gesture-config.md b/docs/docs/gestures/_shared/base-continous-gesture-config.md similarity index 61% rename from docs/docs/api/gestures/base-continous-gesture-config.md rename to docs/docs/gestures/_shared/base-continous-gesture-config.md index a19473784e..79ff2fbc43 100644 --- a/docs/docs/api/gestures/base-continous-gesture-config.md +++ b/docs/docs/gestures/_shared/base-continous-gesture-config.md @@ -1,5 +1,5 @@ -### Properties common to all continous gestures: +### Properties common to all continuous gestures: ### `manualActivation(value: boolead)` -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](./state-manager.md). +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/docs/docs/api/gestures/base-gesture-callbacks.md b/docs/docs/gestures/_shared/base-gesture-callbacks.md similarity index 100% rename from docs/docs/api/gestures/base-gesture-callbacks.md rename to docs/docs/gestures/_shared/base-gesture-callbacks.md diff --git a/docs/docs/api/gestures/base-gesture-config.md b/docs/docs/gestures/_shared/base-gesture-config.md similarity index 72% rename from docs/docs/api/gestures/base-gesture-config.md rename to docs/docs/gestures/_shared/base-gesture-config.md index 4c45278d30..7f87f244df 100644 --- a/docs/docs/api/gestures/base-gesture-config.md +++ b/docs/docs/gestures/_shared/base-gesture-config.md @@ -3,19 +3,19 @@ ### `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`](../../under-the-hood/states-events.md#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`](../../under-the-hood/states-events.md#failed) or [`CANCELLED`](../../under-the-hood/states-events.md#cancelled) (depending on its current state). +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)` -When `true` the handler will [cancel](../../under-the-hood/states-events.md#cancelled) or [fail](../../under-the-hood/states-events.md#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. +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`](./long-press-gesture.md) and [`TapGesture`](./tap-gesture.md) which default to `true`. +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)` -This parameter enables control over what part of the connected view area can be used to [begin](../../under-the-hood/states-events.md#began) recognizing the gesture. +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. 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. @@ -25,7 +25,7 @@ When `width` is set it is only allow to specify one of the sides `right` or `lef 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://facebook.github.io/react-native/docs/view.html#props) property. +**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)` @@ -39,7 +39,7 @@ Sets a `testID` property for gesture object, allowing for querying for it in tes ### `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`](../../under-the-hood/states-events.md#active). +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)` @@ -51,13 +51,13 @@ Defaults to `false`. 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](../../gesture-composition). [`GestureDetector`](gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. +**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, ...)` Adds a relation requiring another gesture to fail, before this one can activate. -**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](../../gesture-composition).[`GestureDetector`](gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. +**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**) diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/base-gesture-event-data.md b/docs/docs/gestures/_shared/base-gesture-event-data.md similarity index 51% rename from docs/versioned_docs/version-2.0.0/api/gestures/base-gesture-event-data.md rename to docs/docs/gestures/_shared/base-gesture-event-data.md index 4d9056b1e5..35990d83f8 100644 --- a/docs/versioned_docs/version-2.0.0/api/gestures/base-gesture-event-data.md +++ b/docs/docs/gestures/_shared/base-gesture-event-data.md @@ -2,7 +2,7 @@ ### `state` -Current [state](.../../under-the-hood/states-events.md) of the handler. Expressed as one of the constants exported under `State` object by the library. +Current [state](/docs/fundamentals/states-events) of the handler. Expressed as one of the constants exported under `State` object by the library. ### `numberOfPointers` diff --git a/docs/docs/api/gestures/gesture-detector-functional1.md b/docs/docs/gestures/_shared/gesture-detector-functional1.md similarity index 100% rename from docs/docs/api/gestures/gesture-detector-functional1.md rename to docs/docs/gestures/_shared/gesture-detector-functional1.md diff --git a/docs/docs/gestures/composed-gestures.md b/docs/docs/gestures/composed-gestures.md new file mode 100644 index 0000000000..9bb90f49c9 --- /dev/null +++ b/docs/docs/gestures/composed-gestures.md @@ -0,0 +1,28 @@ +--- +id: composed-gestures +title: Composed gestures +sidebar_label: Composed gestures +sidebar_position: 13 +--- + +Composed gestures (`Race`, `Simultaneous`, `Exclusive`) provide a simple way of building relations between gestures. + +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + const pan = Gesture.Pan(); + const longPress = Gesture.LongPress(); + + // highlight-next-line + const composed = Gesture.Race(pan, longPress); + + return ( + + + + ); +} +``` diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/fling-gesture.md b/docs/docs/gestures/fling-gesture.md similarity index 50% rename from docs/versioned_docs/version-2.3.0/api/gestures/fling-gesture.md rename to docs/docs/gestures/fling-gesture.md index 09c2846276..e7d1adc525 100644 --- a/docs/versioned_docs/version-2.3.0/api/gestures/fling-gesture.md +++ b/docs/docs/gestures/fling-gesture.md @@ -2,17 +2,43 @@ id: fling-gesture title: Fling gesture sidebar_label: Fling gesture +sidebar_position: 8 --- -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; +import useBaseUrl from '@docusaurus/useBaseUrl'; + +
+ +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; A discrete gesture that activates when the movement is sufficiently long and fast. -Gesture gets [ACTIVE](../../under-the-hood/states-events.md#active) when movement is sufficiently long and it does not take too much time. -When gesture gets activated it will turn into [END](../../under-the-hood/states-events.md#end) state when finger is released. +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. +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const fling = Gesture.Fling(); + + return ( + + + + ); +} +``` + ## Config ### Properties specific to `FlingGesture`: @@ -22,6 +48,7 @@ The gesture will fail to recognize if the finger is lifted before being activate Expressed allowed direction of movement. Expected values are exported as constants in the `Directions` object. It's possible to pass one or many directions in one parameter: ```js +import { Directions } from 'react-native-gesture-handler'; fling.direction(Directions.RIGHT | Directions.LEFT); ``` @@ -66,21 +93,45 @@ Y coordinate of the current position of the pointer (finger or a leading pointer ## Example ```jsx -const position = useSharedValue(0); - -const flingGesture = Gesture.Fling() - .direction(Directions.RIGHT) - .onStart((e) => { - position.value = withTiming(position.value + 10, { duration: 100 }); - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ translateX: position.value }], -})); - -return ( - - - -); +import { StyleSheet } from 'react-native'; +import { + Gesture, + GestureDetector, + Directions, +} from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, + withTiming, +} from 'react-native-reanimated'; + +export default function App() { + const position = useSharedValue(0); + + const flingGesture = Gesture.Fling() + .direction(Directions.RIGHT) + .onStart((e) => { + position.value = withTiming(position.value + 10, { duration: 100 }); + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ translateX: position.value }], + })); + + return ( + + + + ); +} + +const styles = StyleSheet.create({ + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); ``` diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/force-touch-gesture.md b/docs/docs/gestures/force-touch-gesture.md similarity index 57% rename from docs/versioned_docs/version-2.1.1/api/gestures/force-touch-gesture.md rename to docs/docs/gestures/force-touch-gesture.md index 8280f944b1..667879f8e3 100644 --- a/docs/versioned_docs/version-2.1.1/api/gestures/force-touch-gesture.md +++ b/docs/docs/gestures/force-touch-gesture.md @@ -2,16 +2,17 @@ id: force-touch-gesture title: Force touch gesture (iOS only) sidebar_label: Force touch gesture +sidebar_position: 10 --- -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseContinousEventConfig from './\_shared/base-continous-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinousEventCallbacks from './\_shared/base-continous-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](../../under-the-hood/states-events.md#active) when pressure of touch if greater or equal than `minForce`. It fails if pressure is greater than `maxForce` +The gesture [activates](/docs/fundamentals/states-events#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,17 +20,34 @@ At the beginning of the gesture, the pressure factor is 0.0. As the pressure inc There's no implementation provided on Android and it simply renders children without any wrappers. Since this behaviour is only provided on some iOS devices, this gesture should not be used for defining any crucial behaviors. Use it only as an additional improvement and make all features to be accessed without this gesture as well. +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const forceTouch = Gesture.ForceTouch(); + + return ( + + + + ); +} +``` + ## Config ### Properties specific to `ForceTouchGesture`: ### `minForce(value: number)` -A minimal pressure that is required before gesture can [activate](../../under-the-hood/states-events.md#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/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](../../under-the-hood/states-events.md#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/fundamentals/states-events#failed). Should be a value from range `[0.0, 1.0]`. ### `feedbackOnActivation(value: boolean)` diff --git a/docs/docs/api/gestures/gesture-detector.md b/docs/docs/gestures/gesture-detector.md similarity index 50% rename from docs/docs/api/gestures/gesture-detector.md rename to docs/docs/gestures/gesture-detector.md index 6533c65d57..bab53b6b11 100644 --- a/docs/docs/api/gestures/gesture-detector.md +++ b/docs/docs/gestures/gesture-detector.md @@ -2,17 +2,29 @@ id: gesture-detector title: GestureDetector sidebar_label: Gesture detector +sidebar_position: 1 --- -import FunctionalComponents from './gesture-detector-functional1.md'; +import FunctionalComponents from './\_shared/gesture-detector-functional1.md'; -`GestureDetector` is the main component of the RNGH2. It is responsible for creating and updating native gesture handlers based on the config of provided gesture. The most significant difference between it and old gesture handlers is that the `GestureDetector` can recognize more than one gesture at the time thanks to gesture composition. Keep in mind that `GestureDetector` is not compatible with the [Animated API](https://reactnative.dev/docs/animated), nor with [Reanimated 1](https://docs.swmansion.com/react-native-reanimated/docs/1.x.x/). +`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/). -:::caution -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. -::: +## Reference + +```javascript +import { GestureDetector } from 'react-native-gesture-handler'; + +function App() { + const tap = Gesture.Tap(); + return ( + // highlight-next-line + + + // highlight-next-line + + ); +} +``` ## Properties @@ -21,11 +33,17 @@ If we were to remove the collapsable prop from the View, the gesture would stop 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 synchrously. +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-beta.4 Gesture Handler will provide a [StateManager](./state-manager.md) in the [touch events](./touch-events.md) that allows for managing the state of the gesture. +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. ::: ### `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"`. + +## 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. diff --git a/docs/docs/gestures/gesture.md b/docs/docs/gestures/gesture.md new file mode 100644 index 0000000000..08bc5888d7 --- /dev/null +++ b/docs/docs/gestures/gesture.md @@ -0,0 +1,97 @@ +--- +id: gesture +title: Gesture +sidebar_label: Gesture +sidebar_position: 2 +--- + +`Gesture` is the object that allows you to create and compose gestures. + +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const tap = Gesture.Tap(); + + return ( + + + + ); +} +``` + +### Gesture.Tap() + +Creates a new instance of [`TapGesture`](/docs/gestures/tap-gesture.md) 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. + +### Gesture.LongPress() + +Creates a new instance of [`LongPressGesture`](/docs/gestures/long-press-gesture.md) 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. + +### Gesture.Pinch() + +Creates a new instance of [`PinchGesture`](/docs/gestures/pinch-gesture.md) 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. + +### Gesture.Hover() + +Creates a new instance of [`HoverGesture`](/docs/gestures/hover-gesture.md) 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. + +### Gesture.Manual() + +Creates a new instance of [`ManualGesture`](/docs/gestures/manual-gesture.md) 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. + +### Gesture.Race(gesture1, gesture2, gesture3, ...): ComposedGesture + +Creates a gesture composed of those provided as arguments. Only one of those can become active and there are no restrictions to the activation of the gesture. The first one to activate will cancel all the others. + +### Gesture.Simultaneous(gesture1, gesture2, gesture3, ...): ComposedGesture + +Creates a gesture composed of those provided as arguments. All of them can become active without cancelling the others. + +### Gesture.Exclusive(gesture1, gesture2, gesture3, ...): ComposedGesture + +Creates a gesture composed of those provided as arguments. Only one of them can become active, but the first one has a higher priority than the second one, the second one has a higher priority than the third one, and so on. When all gestures are in the `BEGAN` state and the activation criteria for the second one is met, instead of activating it will wait until the first one fails (and only then it will activate) or until the first one activates (and then the second one will get cancelled). It is useful when you want to compose gestures with similar activation criteria (e.g. single and double tap at the same component, without Exclusive the single tap would activate every time user taps thus cancelling the double tap). + +## Remarks + +- Consider wrapping your gesture configurations with `useMemo`, as it will reduce the amount of work Gesture Handler has to do under the hood when updating gestures. For example: + +```jsx +import React from 'react'; + +function App() { + const gesture = React.useMemo( + () => + Gesture.Tap().onStart(() => { + console.log('Number of taps:', tapNumber + 1); + setTapNumber((value) => value + 1); + }), + [tapNumber, setTapNumber] + ); + // ... +} +``` diff --git a/docs/docs/api/gestures/hover-gesture.md b/docs/docs/gestures/hover-gesture.md similarity index 50% rename from docs/docs/api/gestures/hover-gesture.md rename to docs/docs/gestures/hover-gesture.md index e3c0f28fe5..b0db6b327e 100644 --- a/docs/docs/api/gestures/hover-gesture.md +++ b/docs/docs/gestures/hover-gesture.md @@ -2,20 +2,42 @@ id: hover-gesture title: Hover gesture sidebar_label: Hover gesture +sidebar_position: 9 --- -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; +import useBaseUrl from '@docusaurus/useBaseUrl'; + +
+ +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinousEventCallbacks from './\_shared/base-continous-gesture-callbacks.md'; A continuous gesture that can recognize hovering above the view it's attached to. The hover effect may be activated by moving a mouse or a stylus over the view. On iOS additional visual effects may be configured. -:::info -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](../../gesture-composition.md) it with [`Pan` gesture](./pan-gesture.md). -::: +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const hover = Gesture.Hover(); + + return ( + + + + ); +} +``` ## Config @@ -23,6 +45,10 @@ Don't rely on `Hover` gesture to continue after the mouse button is clicked or t ### `effect(effect: HoverEffect)` (iOS only) +```js +import { HoverEffect } from 'react-native-gesture-handler'; +``` + Visual effect applied to the view while the view is hovered. The possible values are: - `HoverEffect.None` @@ -44,11 +70,11 @@ Defaults to `HoverEffect.None` ### `x` -X coordinate of the current position of the pointer relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. +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` -Y coordinate of the current position of the pointer relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. +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` @@ -59,3 +85,7 @@ X coordinate of the current position of the pointer relative to the window. The 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. + +## 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). diff --git a/docs/docs/gestures/long-press-gesture.md b/docs/docs/gestures/long-press-gesture.md new file mode 100644 index 0000000000..3d9bf7aefe --- /dev/null +++ b/docs/docs/gestures/long-press-gesture.md @@ -0,0 +1,114 @@ +--- +id: long-press-gesture +title: Long press gesture +sidebar_label: Long press gesture +sidebar_position: 5 +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +
+ +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; + +A discrete gesture that activates when the corresponding view is pressed for a sufficiently long time. +This gesture's state will turn into [END](/docs/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). + +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const longPress = Gesture.LongPress(); + + return ( + + + + ); +} +``` + +## Config + +### Properties specific to `LongPressGesture`: + +### `minDuration(value: number)` + +Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. + +### `maxDistance(value: number)` + +Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](/docs/fundamentals/states-events#active), it will fail to recognize the gesture. The default value is 10. + + + +## Callbacks + + + +## Event data + +### Event attributes specific to `LongPressGesture`: + +### `x` + +X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). + +### `y` + +Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector). + +### `absoluteX` + +X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector) can be transformed as an effect of the gesture. + +### `absoluteY` + +Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](/docs/gestures/gesture-detector) can be transformed as an effect of the gesture. + +### `duration` + +Duration of the long press (time since the start of the gesture), expressed in milliseconds. + + + +## Example + +```jsx +import { View, StyleSheet, Alert } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; + +export default function App() { + const longPressGesture = Gesture.LongPress().onEnd((e, success) => { + if (success) { + Alert.alert(`Long pressed for ${e.duration} ms!`); + } + }); + + return ( + + + + ); +} + +const styles = StyleSheet.create({ + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` diff --git a/docs/docs/gestures/manual-gesture.md b/docs/docs/gestures/manual-gesture.md new file mode 100644 index 0000000000..072175e3af --- /dev/null +++ b/docs/docs/gestures/manual-gesture.md @@ -0,0 +1,43 @@ +--- +id: manual-gesture +title: Manual gesture +sidebar_label: Manual gesture +sidebar_position: 12 +--- + +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinousEventCallbacks from './\_shared/base-continous-gesture-callbacks.md'; + +A plain gesture that has no specific activation criteria nor event data set. Its state has to be controlled manually using a [state manager](/docs/gestures/state-manager). It will not fail when all the pointers are lifted from the screen. + +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const manual = Gesture.Manual(); + + return ( + + + + ); +} +``` + +## Config + + + +## Callbacks + + + + +## Event data + + diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/native-gesture.md b/docs/docs/gestures/native-gesture.md similarity index 60% rename from docs/versioned_docs/version-2.1.1/api/gestures/native-gesture.md rename to docs/docs/gestures/native-gesture.md index 6fa7249eed..82754464a5 100644 --- a/docs/versioned_docs/version-2.1.1/api/gestures/native-gesture.md +++ b/docs/docs/gestures/native-gesture.md @@ -2,15 +2,33 @@ id: native-gesture title: Native gesture sidebar_label: Native gesture +sidebar_position: 11 --- -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinousEventCallbacks from './\_shared/base-continous-gesture-callbacks.md'; A gesture that allows other touch handling components to participate in RNGH's gesture system. When used, the other component should be the direct child of a `GestureDetector`. +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const native = Gesture.Native(); + + return ( + + + + ); +} +``` + ## Config ### Properties specific to `NativeGesture`: diff --git a/docs/docs/api/gestures/pan-gesture.md b/docs/docs/gestures/pan-gesture.md similarity index 64% rename from docs/docs/api/gestures/pan-gesture.md rename to docs/docs/gestures/pan-gesture.md index b6a7e1ba1d..3f228fef25 100644 --- a/docs/docs/api/gestures/pan-gesture.md +++ b/docs/docs/gestures/pan-gesture.md @@ -2,22 +2,48 @@ id: pan-gesture title: Pan gesture sidebar_label: Pan gesture +sidebar_position: 3 --- -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; +import useBaseUrl from '@docusaurus/useBaseUrl'; + +
+ +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseContinousEventConfig from './\_shared/base-continous-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinousEventCallbacks from './\_shared/base-continous-gesture-callbacks.md'; A continuous gesture that can recognize a panning (dragging) gesture and track its movement. -The gesture [activates](../../under-the-hood/states-events.md#active) when a finger is placed on the screen and moved some initial distance. +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](#minPointers) required for activation (allowing for multifinger swipes) may be specified. +Configurations such as a minimum initial distance, specific vertical or horizontal pan detection and [number of fingers](/docs/gestures/pan-gesture#minpointersvalue-number) required for activation (allowing for multifinger swipes) may be specified. Gesture callback can be used for continuous tracking of the pan gesture. It provides information about the gesture such as its XY translation from the starting point as well as its instantaneous velocity. +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const pan = Gesture.Pan(); + + return ( + + + + ); +} +``` + ## 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. @@ -26,9 +52,9 @@ The difference in multi touch pan handling lies in the way how translation prope 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. -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. +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 [`avgTouches`](#avgtouches-android-only) flag. +This behavior can be changed on Android using [`averageTouches`](#averagetouchesvalue-boolean-android-only) flag. Note that on both Android and iOS when the additional finger is placed on the screen that translation prop is not affected even though the position of the pointer being tracked might have changed. Therefore it is safe to rely on translation most of the time as it only reflects the movement that happens regardless of how many fingers are placed on the screen and if that number changes over time. @@ -40,19 +66,19 @@ If you wish to track the "center of mass" virtual pointer and account for its ch ### `minDistance(value: number)` -Minimum distance the finger (or multiple finger) need to travel before the gesture [activates](../../under-the-hood/states-events.md#active). Expressed in points. +Minimum distance the finger (or multiple finger) need to travel before the gesture [activates](/docs/fundamentals/states-events#active). Expressed in points. ### `minPointers(value: number)` -A number of fingers that is required to be placed before gesture can [activate](../../under-the-hood/states-events.md#active). Should be a higher or equal to 0 integer. +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(value: number)` -When the given number of fingers is placed on the screen and gesture hasn't yet [activated](../../under-the-hood/states-events.md#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 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(duration: number)` -Duration in milliseconds of the `LongPress` gesture before `Pan` is allowed to [activate](../../under-the-hood/states-events.md#active). If the finger is moved during that period, the gesture will [fail](../../under-the-hood/states-events.md#failed). Should be a higher or equal to 0 integer. Default value is 0, meaning no `LongPress` is required to [activate](../../under-the-hood/states-events.md#active) the `Pan`. +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(value: number | number[])` @@ -116,11 +142,11 @@ Velocity of the pan gesture along the Y axis in the current moment. The value is ### `x` -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. +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` -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. +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` @@ -135,35 +161,58 @@ Y coordinate of the current position of the pointer (finger or a leading pointer ## Example ```jsx +import { StyleSheet } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + withTiming, + useAnimatedStyle, +} from 'react-native-reanimated'; + const END_POSITION = 200; -const onLeft = useSharedValue(true); -const position = useSharedValue(0); - -const panGesture = Gesture.Pan() - .onUpdate((e) => { - if (onLeft.value) { - position.value = e.translationX; - } else { - position.value = END_POSITION + e.translationX; - } - }) - .onEnd((e) => { - if (position.value > END_POSITION / 2) { - position.value = withTiming(END_POSITION, { duration: 100 }); - onLeft.value = false; - } else { - position.value = withTiming(0, { duration: 100 }); - onLeft.value = true; - } - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ translateX: position.value }], -})); - -return ( - - - -); + +export default function App() { + const onLeft = useSharedValue(true); + const position = useSharedValue(0); + + // highlight-next-line + const panGesture = Gesture.Pan() + .onUpdate((e) => { + if (onLeft.value) { + position.value = e.translationX; + } else { + position.value = END_POSITION + e.translationX; + } + }) + .onEnd((e) => { + if (position.value > END_POSITION / 2) { + position.value = withTiming(END_POSITION, { duration: 100 }); + onLeft.value = false; + } else { + position.value = withTiming(0, { duration: 100 }); + onLeft.value = true; + } + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ translateX: position.value }], + })); + + return ( + // highlight-next-line + + + + ); +} + +const styles = StyleSheet.create({ + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); ``` diff --git a/docs/docs/gestures/pinch-gesture.md b/docs/docs/gestures/pinch-gesture.md new file mode 100644 index 0000000000..9530e4a522 --- /dev/null +++ b/docs/docs/gestures/pinch-gesture.md @@ -0,0 +1,122 @@ +--- +id: pinch-gesture +title: Pinch gesture +sidebar_label: Pinch gesture +sidebar_position: 7 +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +
+ +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseContinousEventConfig from './\_shared/base-continous-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinousEventCallbacks from './\_shared/base-continous-gesture-callbacks.md'; + +A continuous gesture that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. +The gesture [activates](/docs/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. + +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const pinch = Gesture.Pinch(); + + return ( + + + + ); +} +``` + +## Config + + + + +## Callbacks + + + + +## Event data + +### Event attributes specific to `PinchGesture`: + +### `scale` + +The scale factor relative to the points of the two touches in screen coordinates. + +### `velocity` + +Velocity of the pan gesture the current moment. The value is expressed in point units per second. + +### `focalX` + +Position expressed in points along X axis of center anchor point of gesture + +### `focalY` + +Position expressed in points along Y axis of center anchor point of gesture + + + +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, +} from 'react-native-reanimated'; + +export default function App() { + const scale = useSharedValue(1); + const savedScale = useSharedValue(1); + + const pinchGesture = Gesture.Pinch() + .onUpdate((e) => { + scale.value = savedScale.value * e.scale; + }) + .onEnd(() => { + savedScale.value = scale.value; + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ scale: scale.value }], + })); + + return ( + + + + ); +} + +const styles = StyleSheet.create({ + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` diff --git a/docs/docs/gestures/rotation-gesture.md b/docs/docs/gestures/rotation-gesture.md new file mode 100644 index 0000000000..be4ab87ad0 --- /dev/null +++ b/docs/docs/gestures/rotation-gesture.md @@ -0,0 +1,119 @@ +--- +id: rotation-gesture +title: Rotation gesture +sidebar_label: Rotation gesture +sidebar_position: 6 +--- + +import useBaseUrl from '@docusaurus/useBaseUrl'; + +
+ +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseContinousEventConfig from './\_shared/base-continous-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; +import BaseContinousEventCallbacks from './\_shared/base-continous-gesture-callbacks.md'; + +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. + +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const rotation = Gesture.Rotation(); + + return ( + + + + ); +} +``` + +## Config + + + + +## Callbacks + + + + +## Event data + +### Event attributes specific to `RotationGesture`: + +### `rotation` + +Amount rotated, expressed in radians, from the gesture's focal point (anchor). + +### `velocity` + +Instantaneous velocity, expressed in point units per second, of the gesture. + +### `anchorX` + +X coordinate, expressed in points, of the gesture's central focal point (anchor). + +### `anchorY` + +Y coordinate, expressed in points, of the gesture's central focal point (anchor). + + + +## Example + +```jsx +import { StyleSheet } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; +import Animated, { + useSharedValue, + useAnimatedStyle, +} from 'react-native-reanimated'; + +export default function App() { + const rotation = useSharedValue(1); + const savedRotation = useSharedValue(1); + + const rotationGesture = Gesture.Rotation() + .onUpdate((e) => { + rotation.value = savedRotation.value + e.rotation; + }) + .onEnd(() => { + savedRotation.value = rotation.value; + }); + + const animatedStyle = useAnimatedStyle(() => ({ + transform: [{ rotateZ: `${(rotation.value / Math.PI) * 180}deg` }], + })); + + return ( + + + + ); +} + +const styles = StyleSheet.create({ + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); +``` diff --git a/docs/docs/gestures/state-manager.md b/docs/docs/gestures/state-manager.md new file mode 100644 index 0000000000..de1f3404ad --- /dev/null +++ b/docs/docs/gestures/state-manager.md @@ -0,0 +1,27 @@ +--- +id: state-manager +title: Gesture state manager +sidebar_label: Gesture state manager +sidebar_position: 15 +--- + +`GestureStateManager` allows to manually control the state of the gestures. Please note that `react-native-reanimated` is required to use it, since it allows for synchronously executing methods in worklets. + +## Methods + +### `begin()` + +Transition the gesture to the [`BEGAN`](/docs/fundamentals/states-events.md#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. + +### `end()` + +Transition the gesture to the [`END`](/docs/fundamentals/states-events.md#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.md#failed) state. This method will have no effect if the handler has already finished. diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/tap-gesture.md b/docs/docs/gestures/tap-gesture.md similarity index 50% rename from docs/versioned_docs/version-2.1.1/api/gestures/tap-gesture.md rename to docs/docs/gestures/tap-gesture.md index b0eb8216ea..6a6da838b2 100644 --- a/docs/versioned_docs/version-2.1.1/api/gestures/tap-gesture.md +++ b/docs/docs/gestures/tap-gesture.md @@ -2,11 +2,20 @@ id: tap-gesture title: Tap gesture sidebar_label: Tap gesture +sidebar_position: 4 --- -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; +import useBaseUrl from '@docusaurus/useBaseUrl'; + +
+ +
+ +import BaseEventData from './\_shared/base-gesture-event-data.md'; +import BaseEventConfig from './\_shared/base-gesture-config.md'; +import BaseEventCallbacks from './\_shared/base-gesture-callbacks.md'; A discrete gesture that recognizes one or many taps. @@ -15,7 +24,24 @@ 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 gesture to [activate](../../under-the-hood/states-events.md#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the gesture [activates](../../under-the-hood/states-events.md#active), it will [end](../../under-the-hood/states-events.md#end). +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). + +## Reference + +```jsx +import { GestureDetector, Gesture } from 'react-native-gesture-handler'; + +function App() { + // highlight-next-line + const tap = Gesture.Tap(); + + return ( + + + + ); +} +``` ## Config @@ -23,7 +49,7 @@ In order for a gesture to [activate](../../under-the-hood/states-events.md#activ ### `minPointers(value: number)` -Minimum number of pointers (fingers) required to be placed before the gesture [activates](../../under-the-hood/states-events.md#active). Should be a positive integer. The default value is 1. +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(value: number)` @@ -35,19 +61,19 @@ Maximum time, expressed in milliseconds, that can pass before the next tap — i ### `numberOfTaps(value: number)` -Number of tap gestures required to [activate](../../under-the-hood/states-events.md#active) the gesture. The default value is 1. +Number of tap gestures required to [activate](/docs/fundamentals/states-events#active) the gesture. The default value is 1. ### `maxDeltaX(value: number)` -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the X axis during a tap gesture. If the finger travels further than the defined distance along the X axis and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#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 gesture hasn't yet [activated](/docs/fundamentals/states-events#active), it will fail to recognize the gesture. ### `maxDeltaY(value: number)` -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the Y axis during a tap gesture. If the finger travels further than the defined distance along the Y axis and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#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 gesture hasn't yet [activated](/docs/fundamentals/states-events#active), it will fail to recognize the gesture. ### `maxDistance(value: number)` -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a tap gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#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 gesture hasn't yet [activated](/docs/fundamentals/states-events#active), it will fail to recognize the gesture. @@ -61,40 +87,56 @@ Maximum distance, expressed in points, that defines how far the finger is allowe ### `x` -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). +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` -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`](./gesture-detector.md). +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` -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`](./gesture-detector.md) can be transformed as an effect of the gesture. +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` -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`](./gesture-detector.md) can be transformed as an effect of the gesture. +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. ## Example ```jsx -const singleTap = Gesture.Tap() - .maxDurationMs(250) - .onStart(() => { - Alert.alert('Single tap!'); - }); - -const doubleTap = Gesture.Tap() - .maxDurationMs(250) - .onStart(() => { - Alert.alert('Double tap!'); - }); - -return ( - - - -); +import { View, Alert, StyleSheet } from 'react-native'; +import { Gesture, GestureDetector } from 'react-native-gesture-handler'; + +export default function App() { + const singleTap = Gesture.Tap() + .maxDuration(250) + .onStart(() => { + Alert.alert('Single tap!'); + }); + + const doubleTap = Gesture.Tap() + .maxDuration(250) + .numberOfTaps(2) + .onStart(() => { + Alert.alert('Double tap!'); + }); + + return ( + + + + ); +} + +const styles = StyleSheet.create({ + box: { + height: 120, + width: 120, + backgroundColor: '#b58df1', + borderRadius: 20, + marginBottom: 30, + }, +}); ``` diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/touch-events.md b/docs/docs/gestures/touch-events.md similarity index 88% rename from docs/versioned_docs/version-2.1.1/api/gestures/touch-events.md rename to docs/docs/gestures/touch-events.md index 58103d7b25..29374b89f1 100644 --- a/docs/versioned_docs/version-2.1.1/api/gestures/touch-events.md +++ b/docs/docs/gestures/touch-events.md @@ -2,6 +2,7 @@ id: touch-events title: Touch events sidebar_label: Touch events +sidebar_position: 14 --- ### Touch event attributes: @@ -34,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`](./gesture-detector.md). Expressed in point units. +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. ### `y` -Y coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. +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. ### `absoluteX` diff --git a/docs/docs/guides/_category_.json b/docs/docs/guides/_category_.json new file mode 100644 index 0000000000..c9611929bf --- /dev/null +++ b/docs/docs/guides/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Guides", + "position": 5, + "link": { + "type": "generated-index" + } +} diff --git a/docs/docs/guides/testing.md b/docs/docs/guides/testing.md index 980160bdbd..bc8af2a1d7 100644 --- a/docs/docs/guides/testing.md +++ b/docs/docs/guides/testing.md @@ -24,5 +24,105 @@ Example: RNGH provides an API for triggering selected handlers: -- [`fireGestureHandler(gestureOrHandler, eventList)`](../api/test-api#firegesturehandlergestureorhandler-eventlist) -- [`getByGestureTestId(testID)`](../api/test-api#getbygesturetestidtestid) +- [`fireGestureHandler(gestureOrHandler, eventList)`](/docs/guides/testing#firegesturehandlergestureorhandler-eventlist) +- [`getByGestureTestId(testID)`](/docs/guides/testing#getbygesturetestidtestid) + +## fireGestureHandler(gestureOrHandler, eventList) + +Simulates one event stream (i.e. event sequence starting with `BEGIN` state and ending +with one of `END`/`FAIL`/`CANCEL` states), calling appropriate callbacks associated with given gesture handler. + +### Arguments + +#### `gestureOrHandler` + +Represents either: + +1. Gesture handler component found by Jest queries (e.g. `getByTestId`) +2. Gesture found by [`getByGestureTestId()`](/docs/guides/testing#getbygesturetestidtestid) + +#### `eventList` + +Event data passed to appropriate callback. RNGH fills event list if required +data is missing using these rules: + +1. `oldState` is filled using state of the previous event. `BEGIN` events use + `UNDETERMINED` value as previous event. +2. Events after first `ACTIVE` state can omit `state` field. +3. Handler specific data is filled (e.g. `numberOfTouches`, `x` fields) with + defaults. +4. Missing `BEGIN` and `END` events are added with data copied from first and last + passed event, respectively. +5. If first event don't have `state` field, the `ACTIVE` state is assumed. + +Some examples: + +```jsx +const oldStateFilled = [ + { state: State.BEGAN }, + { state: State.ACTIVE }, + { state: State.END }, +]; // three events with specified state are fired. + +const implicitActiveState = [ + { state: State.BEGAN }, + { state: State.ACTIVE }, + { x: 5 }, + { state: State.END }, +]; // 4 events, including two ACTIVE events (second one has overriden additional data). + +const implicitBegin = [ + { x: 1, y: 11 }, + { x: 2, y: 12, state: State.FAILED }, +]; // 3 events, including implicit BEGAN, one ACTIVE, and one FAILED event with additional data. + +const implicitBeginAndEnd = [ + { x: 5, y: 15 }, + { x: 6, y: 16 }, + { x: 7, y: 17 }, +]; // 5 events, including 3 ACTIVE events and implicit BEGAN and END events. BEGAN uses first event's additional data, END uses last event's additional data. + +const allImplicits = []; // 3 events, one BEGIN, one ACTIVE, one END with defaults. +``` + +### Example + +Extracted from RNGH tests, check `Events.test.tsx` for full implementation. + +```tsx +it('sends events with additional data to handlers', () => { + const panHandlers = mockedEventHandlers(); + render(); + fireGestureHandler(getByGestureTestId('pan'), [ + { state: State.BEGAN, translationX: 0 }, + { state: State.ACTIVE, translationX: 10 }, + { translationX: 20 }, + { translationX: 20 }, + { state: State.END, translationX: 30 }, + ]); + + expect(panHandlers.active).toBeCalledTimes(3); + expect(panHandlers.active).toHaveBeenLastCalledWith( + expect.objectContaining({ translationX: 20 }) + ); +}); +``` + +## 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)). + +### Arguments + +#### `testID` + +String identifying gesture. + +### Notes + +`testID` must be unique among components rendered in test. + +### Example + +See above example for `fireGestureHandler`. diff --git a/docs/docs/troubleshooting.md b/docs/docs/guides/troubleshooting.md similarity index 95% rename from docs/docs/troubleshooting.md rename to docs/docs/guides/troubleshooting.md index 41d6eab140..9aa730ccf9 100644 --- a/docs/docs/troubleshooting.md +++ b/docs/docs/guides/troubleshooting.md @@ -1,6 +1,7 @@ --- id: troubleshooting title: Troubleshooting +sidebar_position: 3 --- ## Troubleshooting @@ -11,7 +12,7 @@ Thanks for giving this library a try! We are sorry that you might have encounter 2. When sure your problem hasn't been reported or was reported but the proposed solution doesn't work for you please follow [our issue reporting guidelines](#reporting-issues). 3. You can try seeking help on [Expo Developers Discord](https://chat.expo.dev/) where we often hang out. 4. If you feel like reading the source code I highly recommend it, as this is by far the best resource and gives you the most up to date insights into how the library works and what might be causing the bug. -5. If you managed to find the solution consider [contributing](introduction.md#contributing) a fix or update our documentation to make this information easier to find for the others in the future. +5. If you managed to find the solution consider [contributing](/docs/#contributing) a fix or update our documentation to make this information easier to find for the others in the future. ## Reporting issues diff --git a/docs/docs/guides/upgrading-to-2.md b/docs/docs/guides/upgrading-to-2.md index 36ff261b6e..ff8dfb2f67 100644 --- a/docs/docs/guides/upgrading-to-2.md +++ b/docs/docs/guides/upgrading-to-2.md @@ -5,7 +5,7 @@ title: Upgrading to the new API introduced in Gesture Handler 2 ## Make sure to migrate off the `RNGestureHandlerEnabledRootView` (Android only) -Gesture Handler 1 required you to override `createRootView` to return an instance of `RNGestureHandlerEnabledRootView`. This class has been the cause of many hard to debug and fix crashed and was deprecated in version 2.0, and subsequently removed in version 2.4. If you are still using it, check out [migrating off RNGHEnabledRootView guide](./migrating-off-rnghenabledroot.md). +Gesture Handler 1 required you to override `createRootView` to return an instance of `RNGestureHandlerEnabledRootView`. This class has been the cause of many hard to debug and fix crashed and was deprecated in version 2.0, and subsequently removed in version 2.4. If you are still using it, check out [migrating off RNGHEnabledRootView guide](/docs/guides/migrating-off-rnghenabledroot). ## Upgrading to the new API @@ -24,6 +24,7 @@ return ( ``` As you can see, there are no `onGestureEvent` and `onHandlerStateChange` callbacks, instead the state machine is handled under the hood and relevant callbacks are called for specific transitions or events: + - `onBegin` - called when the gesture transitions to the `BEGAN` state, which in most cases is when the gesture starts processing the touch stream - when the finger first touches the view - `onStart` - called when the activation criteria for the gesture are met and it transitions from `BEGAN` to `ACTIVE` state - `onUpdate` - replaces `onGestureEvent`, called every time the gesture sends a new event while it's in the `ACTIVE` state @@ -95,7 +96,7 @@ return ( ); ``` -With the `GestureDetector` you can use the [Gesture Composition API](../gesture-composition.md) to stack the gestures onto one view: +With the `GestureDetector` you can use the [Gesture Composition API](/docs/fundamentals/gesture-composition) to stack the gestures onto one view: ```jsx const tapGesture = Gesture.Tap(); @@ -109,8 +110,8 @@ return ( ); ``` -Similarily, you can use [`Gesture.Simultaneous`](../gesture-composition.md#simultaneous) to replace stacked gesture handlers that should be able to recognize gestures simultaneously, and [`Gesture.Exclusive`](../gesture-composition.md#exclusive) to replace stacked gesture handlers that require failure of others. +Similarily, you can use [`Gesture.Simultaneous`](/docs/fundamentals/gesture-composition#simultaneous) to replace stacked gesture handlers that should be able to recognize gestures simultaneously, and [`Gesture.Exclusive`](/docs/fundamentals/gesture-composition#exclusive) to replace stacked gesture handlers that require failure of others. ### Replacing `waitFor` and `simultaneousHandlers` -If you want to make relations between the gestures attached to the same view, you should use the [Gesture Composition API](../gesture-composition.md) described above. However, if you want to make a relation between gestures attached to different views, or between gesture and an old gesture handler, you should use `simultaneousWithExternalGesture` instead of `simultaneousHandlers`, and `requireExternalGestureToFail` instead of `waitFor`. In case you need a ref object to pass to an old gesture handler, you can set it to the gesture using `.withRef(refObject)` modifier. \ No newline at end of file +If you want to make relations between the gestures attached to the same view, you should use the [Gesture Composition API](/docs/fundamentals/gesture-composition) described above. However, if you want to make a relation between gestures attached to different views, or between gesture and an old gesture handler, you should use `simultaneousWithExternalGesture` instead of `simultaneousHandlers`, and `requireExternalGestureToFail` instead of `waitFor`. In case you need a ref object to pass to an old gesture handler, you can set it to the gesture using `.withRef(refObject)` modifier. diff --git a/docs/docs/manual-gestures/step2.md b/docs/docs/manual-gestures/step2.md deleted file mode 100644 index 3137d334ef..0000000000 --- a/docs/docs/manual-gestures/step2.md +++ /dev/null @@ -1,35 +0,0 @@ -```jsx -function PointerElement(props: { - pointer: Animated.SharedValue, - active: Animated.SharedValue, -}) { - const animatedStyle = useAnimatedStyle(() => ({ - transform: [ - { translateX: props.pointer.value.x }, - { translateY: props.pointer.value.y }, - { - scale: - (props.pointer.value.visible ? 1 : 0) * - (props.active.value ? 1.3 : 1), - }, - ], - backgroundColor: props.active.value ? 'red' : 'blue', - })); - - return ; -} - -... - -const styles = StyleSheet.create({ - pointer: { - width: 60, - height: 60, - borderRadius: 30, - backgroundColor: 'red', - position: 'absolute', - marginStart: -30, - marginTop: -30, - }, -}); -``` diff --git a/docs/docs/quickstart/quickstart.md b/docs/docs/quickstart/quickstart.md deleted file mode 100644 index c1ba3d7219..0000000000 --- a/docs/docs/quickstart/quickstart.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -id: quickstart -title: Quick start -sidebar_label: Quick start ---- - -import Step, { Divider } from '@site/src/theme/Step'; -import Step1 from './step1.md'; -import Step2 from './step2.md'; -import Step3 from './step3.md'; -import Step4 from './step4.md'; -import Step5 from './step5.md'; - -RNGH2 provides much simpler way to add gestures to your app. All you need to do is wrap the view that you want your gesture to work on with [`GestureDetector`](../api/gestures/gesture-detector), define the gesture and pass it to detector. That's all! - -To demonstrate how you would use the new API, let's make a simple app where you can drag a ball around. You will need to add `react-native-gesture-handler` (for gestures) and `react-native-reanimated` (for animations) modules. - - - - -
First let's define styles we will need to make the app:
- - - - - - -
Then we can start writing our `Ball` component:
- - - - - - -
- We also need to define{' '} - - shared values - {' '} - to keep track of the ball position and create animated styles in order to be - able to position the ball on the screen: -
- - - - - - -
And add it to the ball's styles:
- - - - - - -
- The only thing left is to define the pan gesture and assign it to the - detector: -
- - - - - -Note the `start` shared value. We need it to store the position of the ball at the moment we grab it to be able to correctly position it later, because we only have access to translation relative to the starting point of the gesture. - -Now you can just add `Ball` component to some view in the app and see the results! (Or you can just check the code [here](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/new_api/reanimated/index.tsx) and see it in action in the Example app.) diff --git a/docs/docs/quickstart/step1.md b/docs/docs/quickstart/step1.md deleted file mode 100644 index 1995cd907c..0000000000 --- a/docs/docs/quickstart/step1.md +++ /dev/null @@ -1,11 +0,0 @@ -```jsx -const styles = StyleSheet.create({ - ball: { - width: 100, - height: 100, - borderRadius: 100, - backgroundColor: 'blue', - alignSelf: 'center', - }, -}); -``` diff --git a/docs/docs/quickstart/step2.md b/docs/docs/quickstart/step2.md deleted file mode 100644 index 34c528266b..0000000000 --- a/docs/docs/quickstart/step2.md +++ /dev/null @@ -1,9 +0,0 @@ -```jsx -function Ball() { - return ( - - - - ); -} -``` diff --git a/docs/docs/quickstart/step3.md b/docs/docs/quickstart/step3.md deleted file mode 100644 index ee7184ffc7..0000000000 --- a/docs/docs/quickstart/step3.md +++ /dev/null @@ -1,14 +0,0 @@ -```jsx -const isPressed = useSharedValue(false); -const offset = useSharedValue({ x: 0, y: 0 }); -const animatedStyles = useAnimatedStyle(() => { - return { - transform: [ - { translateX: offset.value.x }, - { translateY: offset.value.y }, - { scale: withSpring(isPressed.value ? 1.2 : 1) }, - ], - backgroundColor: isPressed.value ? 'yellow' : 'blue', - }; -}); -``` diff --git a/docs/docs/quickstart/step4.md b/docs/docs/quickstart/step4.md deleted file mode 100644 index 8e2112a3cd..0000000000 --- a/docs/docs/quickstart/step4.md +++ /dev/null @@ -1,9 +0,0 @@ -```jsx {4} -... -return ( - - - -); -... -``` diff --git a/docs/docs/quickstart/step5.md b/docs/docs/quickstart/step5.md deleted file mode 100644 index c7c2e07265..0000000000 --- a/docs/docs/quickstart/step5.md +++ /dev/null @@ -1,32 +0,0 @@ -```jsx -const start = useSharedValue({ x: 0, y: 0 }); -const gesture = Gesture.Pan() - .onBegin(() => { - isPressed.value = 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, - }; - }) - .onFinalize(() => { - isPressed.value = false; - }); -``` - -```jsx {3} -... -return ( - - - -); -... -``` diff --git a/docs/docs/under-the-hood/_category_.json b/docs/docs/under-the-hood/_category_.json new file mode 100644 index 0000000000..eb9d7de5d7 --- /dev/null +++ b/docs/docs/under-the-hood/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Under the hood", + "position": 6, + "link": { + "type": "generated-index" + } +} diff --git a/docs/docs/under-the-hood/how-does-it-work.md b/docs/docs/under-the-hood/how-does-it-work.md index a4553a478f..4d613d4879 100644 --- a/docs/docs/under-the-hood/how-does-it-work.md +++ b/docs/docs/under-the-hood/how-does-it-work.md @@ -7,7 +7,7 @@ sidebar_label: How does it work? ### Units All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". -These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://facebook.github.io/react-native/docs/flexbox.html)). +These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://reactnative.dev/docs/flexbox.html)). They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. ## iOS diff --git a/docs/versioned_docs/version-2.1.1/gesture-handlers/basics/state.md b/docs/docs/under-the-hood/state.md similarity index 78% rename from docs/versioned_docs/version-2.1.1/gesture-handlers/basics/state.md rename to docs/docs/under-the-hood/state.md index 1f15f94f2f..dddede255f 100644 --- a/docs/versioned_docs/version-2.1.1/gesture-handlers/basics/state.md +++ b/docs/docs/under-the-hood/state.md @@ -4,24 +4,27 @@ title: Handler State sidebar_label: Handler State --- -As described in ["About Gesture Handlers"](./about-handlers.md), gesture handlers can be treated as ["state machines"](https://en.wikipedia.org/wiki/Finite-state_machine). +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). 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: -- [UNDETERMINED](#undetermined) -- [FAILED](#failed) -- [BEGAN](#began) -- [CANCELLED](#cancelled) -- [ACTIVE](#active) -- [END](#end) +- [Accessing state](#accessing-state) +- [State flows](#state-flows) +- [States](#states) + - [UNDETERMINED](#undetermined) + - [FAILED](#failed) + - [BEGAN](#began) + - [CANCELLED](#cancelled) + - [ACTIVE](#active) + - [END](#end) Each state has its own description below. ## Accessing state -We can monitor a handler's state changes by using the [`onHandlerStateChange`](../api/common-gh.md#onhandlerstatechange) callback and the destructured `nativeEvent` argument passed to it. -This can be done by comparing the `nativeEvent`'s [`state`](../api/common-gh.md#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/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). ``` import { State, LongPressGestureHandler } from 'react-native-gesture-handler'; @@ -81,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](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/gesture-handlers/about-handlers#discrete-vs-continuous) to understand how long a handler can be kept in the `ACTIVE` state. ### END diff --git a/docs/docs/under-the-hood/states-events.md b/docs/docs/under-the-hood/states-events.md deleted file mode 100644 index 600f16a5cc..0000000000 --- a/docs/docs/under-the-hood/states-events.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -id: states-events -title: Gesture states & events -sidebar_label: Gesture states & events ---- - -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 (longer arrows represent that there are possibly more touch events received before the state changes): - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`END`](#end) -> [`UNDETERMINED`](#undetermined) - -Another possible flow is when a handler receives touches that cause a recognition failure: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`FAILED`](#failed) -> [`UNDETERMINED`](#undetermined) - -At last, when a handler does properly recognize the gesture but then is interrupted by the touch system the gesture recognition is canceled and the flow looks as follows: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`CANCELLED`](#cancelled) -> [`UNDETERMINED`](#undetermined) - -## 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. - -### `onPointerChange` - -Is called before `onPointerDown`, `onPointerMove`, `onPointerUp` and `onPointerCancelled` with the same event, which may be useful in case you share logic between them. It may carry information about more than one pointer because the events are batched. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 30dba2a054..86c64dca91 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -69,7 +69,8 @@ In swizzled components look for "SWM -" string to see our modifications module.exports = { title: 'React Native Gesture Handler', - tagline: 'Declarative API exposing platform native touch and gesture system to React Native.', + tagline: + 'Declarative API exposing platform native touch and gesture system to React Native.', url: 'https://docs.swmansion.com', baseUrl: '/react-native-gesture-handler/', onBrokenLinks: 'throw', @@ -119,27 +120,21 @@ module.exports = { prism: { theme: prismConfig, }, - announcementBar: { - id: 'appjs_announcement', - content: 'mleko', // content is set in swizzled component but docusaurus requires it to be non-empty - backgroundColor: '#0033CC', - textColor: '#FFFFFF', - }, }, presets: [ [ '@docusaurus/preset-classic', { docs: { - path: 'docs', + breadcrumbs: false, sidebarPath: require.resolve('./sidebars.js'), - editUrl: undefined, // hide edit button + sidebarCollapsible: false, + editUrl: + 'https://github.com/software-mansion/react-native-gesture-handler/edit/main/docs', + lastVersion: 'current', // <- this makes 2.x docs as default versions: { - '2.4.0': { - label: '2.4.0 – 2.5.0', - }, - '2.6.0': { - label: '2.6.0 – 2.13.0', + current: { + label: '2.x', }, }, }, diff --git a/docs/package.json b/docs/package.json index 791b2c839b..286a8c93ab 100644 --- a/docs/package.json +++ b/docs/package.json @@ -14,8 +14,8 @@ "write-heading-ids": "docusaurus write-heading-ids" }, "dependencies": { - "@docusaurus/core": "^2.3.1", - "@docusaurus/preset-classic": "^2.3.1", + "@docusaurus/core": "^2.4.3", + "@docusaurus/preset-classic": "^2.4.3", "@mdx-js/react": "^1.6.21", "classnames": "^2.3.1", "clsx": "^1.1.1", diff --git a/docs/sidebars.js b/docs/sidebars.js index c735b30212..ef1bd11a19 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,81 +1,33 @@ -module.exports = { - docs: [ - { type: 'doc', id: 'introduction' }, - { type: 'doc', id: 'installation' }, - { type: 'doc', id: 'troubleshooting' }, +/** + * Creating a sidebar enables you to: + - create an ordered group of docs + - render a sidebar for each doc of that group + - provide next/previous navigation + + The sidebars can be generated from the filesystem, or explicitly defined here. + + Create as many sidebars as you want. + */ + +// @ts-check + +/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ +const sidebars = { + // By default, Docusaurus generates a sidebar from the docs folder structure + tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }], + + // But you can create a sidebar manually + /* + tutorialSidebar: [ + 'intro', + 'hello', { type: 'category', - label: 'Guides', - items: [ - 'quickstart/quickstart', - 'gesture-composition', - 'manual-gestures/manual-gestures', - 'under-the-hood/states-events', - 'gesture-handlers/basics/about-handlers', - 'gesture-handlers/basics/interactions', - 'guides/testing', - 'guides/migrating-off-rnghenabledroot', - 'guides/upgrading-to-2', - ], - }, - { - type: 'category', - label: 'API reference', - items: [ - { - type: 'category', - label: 'Gestures', - items: [ - 'api/gestures/gesture-detector', - 'api/gestures/gesture', - 'api/gestures/pan-gesture', - 'api/gestures/tap-gesture', - 'api/gestures/long-press-gesture', - 'api/gestures/rotation-gesture', - 'api/gestures/pinch-gesture', - 'api/gestures/fling-gesture', - 'api/gestures/force-touch-gesture', - 'api/gestures/native-gesture', - 'api/gestures/manual-gesture', - 'api/gestures/hover-gesture', - 'api/gestures/composed-gestures', - 'api/gestures/touch-events', - 'api/gestures/state-manager', - ], - }, - { - type: 'category', - label: 'Components', - items: [ - 'api/components/buttons', - 'api/components/swipeable', - 'api/components/touchables', - 'api/components/drawer-layout', - ], - }, - { - type: 'category', - label: 'Gesture Handlers', - items: [ - 'gesture-handlers/api/common-gh', - 'gesture-handlers/api/pan-gh', - 'gesture-handlers/api/tap-gh', - 'gesture-handlers/api/longpress-gh', - 'gesture-handlers/api/rotation-gh', - 'gesture-handlers/api/fling-gh', - 'gesture-handlers/api/pinch-gh', - 'gesture-handlers/api/force-gh', - 'gesture-handlers/api/nativeview-gh', - 'gesture-handlers/api/create-native-wrapper', - ], - }, - { type: 'doc', id: 'api/test-api' }, - ], - }, - { - type: 'category', - label: 'Under the hood', - items: ['under-the-hood/how-does-it-work', 'gesture-handlers/basics/state'], + label: 'Tutorial', + items: ['tutorial-basics/create-a-document'], }, ], + */ }; + +module.exports = sidebars; diff --git a/docs/src/theme/NotFound/index.js b/docs/src/theme/NotFound/index.js new file mode 100644 index 0000000000..23675f838a --- /dev/null +++ b/docs/src/theme/NotFound/index.js @@ -0,0 +1,20 @@ +import React from 'react'; +import NotFound from '@theme-original/NotFound'; +import { Redirect, useLocation } from '@docusaurus/router'; +import { mapLegacyUrl } from './mapLegacyUrl'; + +export default function NotFoundWrapper(props) { + const location = useLocation(); + + const redirect = mapLegacyUrl(location); + + if (redirect) { + return ; + } + + return ( + <> + + + ); +} diff --git a/docs/src/theme/NotFound/mapLegacyUrl.js b/docs/src/theme/NotFound/mapLegacyUrl.js new file mode 100644 index 0000000000..403ad0bb86 --- /dev/null +++ b/docs/src/theme/NotFound/mapLegacyUrl.js @@ -0,0 +1,120 @@ +// not the most elegant way but the most fool-proof for sure +// [from , to] +const siteMap = [ + ['/installation', '/fundamentals/installation'], + ['/quickstart', '/fundamentals/quickstart'], + ['/gesture-composition', '/fundamentals/gesture-composition'], + ['/manual-gestures', '/fundamentals/manual-gestures'], + ['/under-the-hood/states-events', '/fundamentals/states-events'], + ['/api/gestures/gesture-detector', '/gestures/gesture-detector'], + ['/api/gestures/gesture', '/gestures/gesture'], + ['/api/gestures/pan-gesture', '/gestures/pan-gesture'], + ['/api/gestures/tap-gesture', '/gestures/tap-gesture'], + ['/api/gestures/long-press-gesture', '/gestures/long-press-gesture'], + ['/api/gestures/rotation-gesture', '/gestures/rotation-gesture'], + ['/api/gestures/pinch-gesture', '/gestures/pinch-gesture'], + ['/api/gestures/fling-gesture', '/gestures/fling-gesture'], + ['/api/gestures/hover-gesture', '/gestures/hover-gesture'], + ['/api/gestures/force-touch-gesture', '/gestures/force-touch-gesture'], + ['/api/gestures/native-gesture', '/gestures/native-gesture'], + ['/api/gestures/manual-gesture', '/gestures/manual-gesture'], + ['/api/gestures/composed-gestures', '/gestures/composed-gestures'], + ['/api/gestures/touch-events', '/gestures/touch-events'], + ['/api/gestures/state-manager', '/gestures/state-manager'], + ['/api/components/buttons', '/components/buttons'], + ['/api/components/swipeable', '/components/drawer-layout'], + ['/api/components/touchables', '/components/swipeable'], + ['/api/components/drawer-layout', '/components/touchables'], + [ + '/gesture-handlers/basics/about-handlers', + '/gesture-handlers/about-handlers', + ], + ['/under-the-hood/states-events', '/gesture-handlers/states-events'], + ['/gesture-handlers/basics/interactions', '/gesture-handlers/interactions'], + ['/gesture-handlers/api/common-gh', '/gesture-handlers/common-gh'], + ['/gesture-handlers/api/pan-gh', '/gesture-handlers/pan-gh'], + ['/gesture-handlers/api/tap-gh', '/gesture-handlers/tap-gh'], + ['/gesture-handlers/api/longpress-gh', '/gesture-handlers/longpress-gh'], + ['/gesture-handlers/api/rotation-gh', '/gesture-handlers/rotation-gh'], + ['/gesture-handlers/api/fling-gh', '/gesture-handlers/fling-gh'], + ['/gesture-handlers/api/pinch-gh', '/gesture-handlers/pinch-gh'], + ['/gesture-handlers/api/force-gh', '/gesture-handlers/force-gh'], + ['/gesture-handlers/api/nativeview-gh', '/gesture-handlers/nativeview-gh'], + [ + '/gesture-handlers/api/create-native-wrapper', + '/gesture-handlers/create-native-wrapper', + ], + ['/troubleshooting', '/guides/troubleshooting'], + // ['/guides/migrating-off-rnghenabledroot', '/guides/migrating-off-rnghenabledroot'], + // ['/guides/testing', '/guides/testing'], + // ['/guides/upgrading-to-2', '/guides/upgrading-to-2'], + // ['/under-the-hood/how-does-it-work', '/under-the-hood/how-does-it-work'], + ['/gesture-handlers/basics/state', '/under-the-hood/state'], +]; + +const legacyVersions = [ + { + from: '/docs/1.10.3', + to: '/docs/1.x', + }, + { + from: '/docs/2.0.0', + to: '/docs', + }, + { + from: '/docs/2.1.1', + to: '/docs', + }, + { + from: '/docs/2.3.0', + to: '/docs', + }, + { + from: '/docs/2.4.0', + to: '/docs', + }, + { + from: '/docs/next', + to: '/docs', + }, + { + from: '/docs', + to: '/docs', + }, +]; + +function handleLegacyVersions(pathname) { + const redirect = legacyVersions.find(({ from }) => pathname.match(from)); + + const redirectTo = redirect + ? pathname.replace(redirect.from, redirect.to) + : null; + + return redirectTo; +} + +// Example pathname: +// '/react-native-gesture-handler/docs/2.1.1/gesture-composition' +// '/react-native-gesture-handler/docs/2.3.0/gesture-handlers/basics/interactions#simultaneous-recognition' +function handleSiteMap(pathname, hash) { + const element = siteMap.find(([from]) => { + return pathname.match(from); + }); + + const [redirectFromEnding, redirectToEnding] = element ?? []; + + if (redirectFromEnding === undefined) return null; + + const redirectTo = pathname.replace(redirectFromEnding, redirectToEnding); + + return redirectTo + hash; +} + +// Returns null if pathname is not legacy and doesn't need to be redirected +export function mapLegacyUrl(location) { + const resolvedVersionPathname = handleLegacyVersions(location.pathname); + + if (!resolvedVersionPathname) return null; + + return handleSiteMap(resolvedVersionPathname, location.hash); +} diff --git a/docs/static/video/fling.mp4 b/docs/static/video/fling.mp4 new file mode 100644 index 0000000000..a2c8d6d7f9 Binary files /dev/null and b/docs/static/video/fling.mp4 differ diff --git a/docs/static/video/hover.mp4 b/docs/static/video/hover.mp4 new file mode 100644 index 0000000000..50d8743e20 Binary files /dev/null and b/docs/static/video/hover.mp4 differ diff --git a/docs/static/video/longpress.mp4 b/docs/static/video/longpress.mp4 new file mode 100644 index 0000000000..8abdef3942 Binary files /dev/null and b/docs/static/video/longpress.mp4 differ diff --git a/docs/static/video/pan.mp4 b/docs/static/video/pan.mp4 new file mode 100644 index 0000000000..0d8cdfa9d5 Binary files /dev/null and b/docs/static/video/pan.mp4 differ diff --git a/docs/static/video/pinch.mp4 b/docs/static/video/pinch.mp4 new file mode 100644 index 0000000000..a5601fe3e1 Binary files /dev/null and b/docs/static/video/pinch.mp4 differ diff --git a/docs/static/video/rotation.mp4 b/docs/static/video/rotation.mp4 new file mode 100644 index 0000000000..ecd77db80a Binary files /dev/null and b/docs/static/video/rotation.mp4 differ diff --git a/docs/static/video/tap.mp4 b/docs/static/video/tap.mp4 new file mode 100644 index 0000000000..d96deac5ea Binary files /dev/null and b/docs/static/video/tap.mp4 differ diff --git a/docs/versioned_docs/version-1.10.3/api/components/drawer-layout.mdx b/docs/versioned_docs/version-1.10.3/api/components/drawer-layout.mdx deleted file mode 100644 index b3e4373d1e..0000000000 --- a/docs/versioned_docs/version-1.10.3/api/components/drawer-layout.mdx +++ /dev/null @@ -1,147 +0,0 @@ ---- -id: drawer-layout -title: Drawer Layout -sidebar_label: DrawerLayout ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import GifGallery from '@site/components/GifGallery'; - -This is a cross-platform replacement for React Native's [DrawerLayoutAndroid](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) component. It provides a compatible API but allows for the component to be used on both Android and iOS. Please refer to [React Native docs](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) for the detailed usage for standard parameters. - -## Usage: - -`DrawerLayout` component isn't exported by default from the `react-native-gesture-handler` package. To use it, import it in the following way: - -```js -import DrawerLayout from 'react-native-gesture-handler/DrawerLayout'; -``` - -## Properties: - -On top of the standard list of parameters DrawerLayout has an additional set of attributes to customize its behavior. Please refer to the list below: - -### `drawerType` - -possible values are: `front`, `back` or `slide` (default is `front`). It specifies the way the drawer will be displayed. When set to `front` the drawer will slide in and out along with the gesture and will display on top of the content view. When `back` is used the drawer displays behind the content view and can be revealed with gesture of pulling the content view to the side. Finally `slide` option makes the drawer appear like it is attached to the side of the content view; when you pull both content view and drawer will follow the gesture. - -Type `slide`: - - - - - -Type `front`: - - - - - -Type `back`: - - - - - -### `edgeWidth` - -number, allows for defining how far from the edge of the content view the gesture should activate. - -### `hideStatusBar` - -boolean, when set to `true` Drawer component will use [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html) API to hide the OS status bar whenever the drawer is pulled or when its in an "open" state. - -### `statusBarAnimation` - -possible values are: `slide`, `none` or `fade` (defaults to `slide`). Can be used when `hideStatusBar` is set to `true` and will select the animation used for hiding/showing the status bar. See [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html#statusbaranimation) documentation for more details. - -### `overlayColor` - -color (default to `"black"`) of a semi-transparent overlay to be displayed on top of the content view when drawer gets open. A solid color should be used as the opacity is added by the Drawer itself and the opacity of the overlay is animated (from 0% to 70%). - -### `renderNavigationView` - -function. This attribute is present in the standard implementation already and is one of the required params. Gesture handler version of DrawerLayout make it possible for the function passed as `renderNavigationView` to take an Animated value as a parameter that indicates the progress of drawer opening/closing animation (progress value is 0 when closed and 1 when opened). This can be used by the drawer component to animated its children while the drawer is opening or closing. - -### `onDrawerClose` - -function. This function is called when the drawer is closed. - -### `onDrawerOpen` - -function. This function is called when the drawer is opened. - -### `onDrawerSlide` - -function. This function is called as a drawer sliding open from touch events. The progress of the drawer opening/closing is passed back as 0 when closed and 1 when opened. - -### `onDrawerStateChanged` - -function. This function is called when the status of the drawer changes. Possible values that can be passed back are: 'Idle', 'Dragging', and 'Settling'. - -### `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` - -component or function. Children is a component which is rendered by default and is wrapped by drawer. However, it could be also a render function which takes an Animated value as a parameter that indicates the progress of drawer opening/closing animation (progress value is 0 when closed and 1 when opened) is the same way like `renderNavigationView` prop. - -## Methods - -### `openDrawer(options)` - -`openDrawer` can take an optional `options` parameter which is an object, enabling further customization of the open animation. - -`options` has two optional properties: - -`velocity`: number, the initial velocity of the object attached to the spring. Default 0 (object is at rest). -`speed`: number, controls speed of the animation. Default 12. - -### `closeDrawer(options)` - -`closeDrawer` can take an optional `options` parameter which is an object, enabling further customization of the close animation. - -`options` has two optional properties: - -`velocity`: number, the initial velocity of the object attached to the spring. Default 0 (object is at rest). -`speed`: number, controls speed of the animation. Default 12. - -## Example: - -See the [drawer example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/horizontalDrawer/index.tsx) from [GestureHandler Example App](example.md) or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -class Drawerable extends Component { - handleDrawerSlide = (status) => { - // outputs a value between 0 and 1 - console.log(status); - }; - - renderDrawer = () => { - return ( - - I am in the drawer! - - ); - }; - - render() { - return ( - - - - Hello, it's me - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-1.10.3/about-handlers.md b/docs/versioned_docs/version-1.x/about-handlers.md similarity index 100% rename from docs/versioned_docs/version-1.10.3/about-handlers.md rename to docs/versioned_docs/version-1.x/about-handlers.md diff --git a/docs/versioned_docs/version-1.10.3/api/components/buttons.mdx b/docs/versioned_docs/version-1.x/api/components/buttons.mdx similarity index 100% rename from docs/versioned_docs/version-1.10.3/api/components/buttons.mdx rename to docs/versioned_docs/version-1.x/api/components/buttons.mdx diff --git a/docs/versioned_docs/version-2.0.0/api/components/drawer-layout.mdx b/docs/versioned_docs/version-1.x/api/components/drawer-layout.mdx similarity index 90% rename from docs/versioned_docs/version-2.0.0/api/components/drawer-layout.mdx rename to docs/versioned_docs/version-1.x/api/components/drawer-layout.mdx index b3e4373d1e..c1a426222c 100644 --- a/docs/versioned_docs/version-2.0.0/api/components/drawer-layout.mdx +++ b/docs/versioned_docs/version-1.x/api/components/drawer-layout.mdx @@ -7,7 +7,7 @@ sidebar_label: DrawerLayout import useBaseUrl from '@docusaurus/useBaseUrl'; import GifGallery from '@site/components/GifGallery'; -This is a cross-platform replacement for React Native's [DrawerLayoutAndroid](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) component. It provides a compatible API but allows for the component to be used on both Android and iOS. Please refer to [React Native docs](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) for the detailed usage for standard parameters. +This is a cross-platform replacement for React Native's [DrawerLayoutAndroid](http://reactnative.dev/docs/drawerlayoutandroid.html) component. It provides a compatible API but allows for the component to be used on both Android and iOS. Please refer to [React Native docs](http://reactnative.dev/docs/drawerlayoutandroid.html) for the detailed usage for standard parameters. ## Usage: @@ -49,11 +49,11 @@ number, allows for defining how far from the edge of the content view the gestur ### `hideStatusBar` -boolean, when set to `true` Drawer component will use [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html) API to hide the OS status bar whenever the drawer is pulled or when its in an "open" state. +boolean, when set to `true` Drawer component will use [StatusBar](http://reactnative.dev/docs/statusbar.html) API to hide the OS status bar whenever the drawer is pulled or when its in an "open" state. ### `statusBarAnimation` -possible values are: `slide`, `none` or `fade` (defaults to `slide`). Can be used when `hideStatusBar` is set to `true` and will select the animation used for hiding/showing the status bar. See [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html#statusbaranimation) documentation for more details. +possible values are: `slide`, `none` or `fade` (defaults to `slide`). Can be used when `hideStatusBar` is set to `true` and will select the animation used for hiding/showing the status bar. See [StatusBar](http://reactnative.dev/docs/statusbar.html#statusbaranimation) documentation for more details. ### `overlayColor` diff --git a/docs/versioned_docs/version-1.10.3/api/components/swipeable.md b/docs/versioned_docs/version-1.x/api/components/swipeable.md similarity index 100% rename from docs/versioned_docs/version-1.10.3/api/components/swipeable.md rename to docs/versioned_docs/version-1.x/api/components/swipeable.md diff --git a/docs/versioned_docs/version-1.10.3/api/components/touchables.md b/docs/versioned_docs/version-1.x/api/components/touchables.md similarity index 83% rename from docs/versioned_docs/version-1.10.3/api/components/touchables.md rename to docs/versioned_docs/version-1.x/api/components/touchables.md index 6458acbbcd..107b89695c 100644 --- a/docs/versioned_docs/version-1.10.3/api/components/touchables.md +++ b/docs/versioned_docs/version-1.x/api/components/touchables.md @@ -8,10 +8,10 @@ Gesture Handler library provides an implementation of RN's touchable components React Native's touchables API can be found here: -- [Touchable Native Feedback](https://facebook.github.io/react-native/docs/touchablenativefeedback) -- [Touchable Highlight](https://facebook.github.io/react-native/docs/touchablehighlight) -- [Touchable Opacity](https://facebook.github.io/react-native/docs/touchableopacity) -- [Touchable Without Feedback](https://facebook.github.io/react-native/docs/touchablewithoutfeedback) +- [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. diff --git a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/common-gh.md b/docs/versioned_docs/version-1.x/api/gesture-handlers/common-gh.md similarity index 59% rename from docs/versioned_docs/version-1.10.3/api/gesture-handlers/common-gh.md rename to docs/versioned_docs/version-1.x/api/gesture-handlers/common-gh.md index 553bdb1aa3..4c077a212a 100644 --- a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/common-gh.md +++ b/docs/versioned_docs/version-1.x/api/gesture-handlers/common-gh.md @@ -9,7 +9,7 @@ This page covers the common set of properties all gesture handler components exp ### Units All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". -These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://facebook.github.io/react-native/docs/flexbox.html)). +These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://reactnative.dev/docs/flexbox.html)). They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. ## Properties @@ -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`](../../state.md#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`](../../state.md#failed) or [`CANCELLED`](../../state.md#cancelled) (depending on its current state). +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). Default value is `true`. ### `shouldCancelWhenOutside` Accepts a boolean value. -When `true` the handler will [cancel](../../state.md#cancelled) or [fail](../../state.md#failed) recognition (depending on its current state) whenever the finger leaves the area of the connected view. +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. 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](../../state.md#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](../../state.md#active) state. It will also prevent the provided handlers from [cancelling](../../state.md#cancelled) the current handler when they [activate](../../state.md#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/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. ### `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](../../state.md#active) as long as the handlers provided by their refs are in the [`BEGAN`](../../state.md#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/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. ### `hitSlop` -This parameter enables control over what part of the connected view area can be used to [begin](../../state.md#began) recognizing the gesture. +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. 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. @@ -51,23 +51,23 @@ When `width` is set it is only allow to specify one of the sides `right` or `lef 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://facebook.github.io/react-native/docs/view.html#props) property. +**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. ### `onGestureEvent` -Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](../../state.md#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/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. -Instead of a callback [`Animated.event`](https://facebook.github.io/react-native/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. +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](../../state.md) of the given handler changes. +Takes a callback that is going to be triggered when [state](/docs/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](../../state.md) of the handler right before the change. +In addition `onHandlerStateChange` event payload contains `oldState` attribute which represents the [state](/docs/under-the-hood/state) of the handler right before the change. -Instead of a callback [`Animated.event`](https://facebook.github.io/react-native/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. +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**. ## Event data @@ -75,7 +75,7 @@ This section describes the attributes of event object being provided to [`onGest ### `state` -Current [state](../../state.md) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](../../state.md) to learn more about how to use it. +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. ### `numberOfPointers` diff --git a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/create-native-wrapper.md b/docs/versioned_docs/version-1.x/api/gesture-handlers/create-native-wrapper.md similarity index 100% rename from docs/versioned_docs/version-1.10.3/api/gesture-handlers/create-native-wrapper.md rename to docs/versioned_docs/version-1.x/api/gesture-handlers/create-native-wrapper.md diff --git a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/fling-gh.md b/docs/versioned_docs/version-1.x/api/gesture-handlers/fling-gh.md similarity index 100% rename from docs/versioned_docs/version-1.10.3/api/gesture-handlers/fling-gh.md rename to docs/versioned_docs/version-1.x/api/gesture-handlers/fling-gh.md diff --git a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/force-gh.md b/docs/versioned_docs/version-1.x/api/gesture-handlers/force-gh.md similarity index 86% rename from docs/versioned_docs/version-1.10.3/api/gesture-handlers/force-gh.md rename to docs/versioned_docs/version-1.x/api/gesture-handlers/force-gh.md index 638338ae8b..d910ecb35f 100644 --- a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/force-gh.md +++ b/docs/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](../../state.md#active) when pressure of touch if greater or equal than `minForce`. It fails if pressure is greater than `maxForce` +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` 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](../../state.md#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/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](../../state.md#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/under-the-hood/state#failed). Should be a value from range `[0.0, 1.0]`. ### `feedbackOnActivation` diff --git a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/longpress-gh.md b/docs/versioned_docs/version-1.x/api/gesture-handlers/longpress-gh.md similarity index 93% rename from docs/versioned_docs/version-1.10.3/api/gesture-handlers/longpress-gh.md rename to docs/versioned_docs/version-1.x/api/gesture-handlers/longpress-gh.md index 98d218d5f1..69db5218c3 100644 --- a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/longpress-gh.md +++ b/docs/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](../../state.md#end) immediately after the finger is released. +This handler's state will turn into [END](/docs/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/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](../../state.md#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/under-the-hood/state#active), it will fail to recognize the gesture. The default value is 10. ## Event data diff --git a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/nativeview-gh.md b/docs/versioned_docs/version-1.x/api/gesture-handlers/nativeview-gh.md similarity index 100% rename from docs/versioned_docs/version-1.10.3/api/gesture-handlers/nativeview-gh.md rename to docs/versioned_docs/version-1.x/api/gesture-handlers/nativeview-gh.md diff --git a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/pan-gh.md b/docs/versioned_docs/version-1.x/api/gesture-handlers/pan-gh.md similarity index 94% rename from docs/versioned_docs/version-1.10.3/api/gesture-handlers/pan-gh.md rename to docs/versioned_docs/version-1.x/api/gesture-handlers/pan-gh.md index a91314e030..8f3490e3e1 100644 --- a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/pan-gh.md +++ b/docs/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](../../state.md#active) when a finger is placed on the screen and moved some initial distance. +The handler [activates](/docs/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. @@ -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](../../state.md#active) or [fail](../../state.md#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/under-the-hood/state#active) or [fail](/docs/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. @@ -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](../../state.md#active). Expressed in points. +Minimum distance the finger (or multiple finger) need to travel before the handler [activates](/docs/under-the-hood/state#active). Expressed in points. ### `minPointers` -A number of fingers that is required to be placed before handler can [activate](../../state.md#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/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](../../state.md#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/under-the-hood/state#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. ### `activeOffsetX` diff --git a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/pinch-gh.md b/docs/versioned_docs/version-1.x/api/gesture-handlers/pinch-gh.md similarity index 96% rename from docs/versioned_docs/version-1.10.3/api/gesture-handlers/pinch-gh.md rename to docs/versioned_docs/version-1.x/api/gesture-handlers/pinch-gh.md index fa15ec2f73..6e3c60b9dc 100644 --- a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/pinch-gh.md +++ b/docs/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](../../state.md#active) when fingers are placed on the screen and change their position. +The handler [activates](/docs/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. diff --git a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/rotation-gh.md b/docs/versioned_docs/version-1.x/api/gesture-handlers/rotation-gh.md similarity index 100% rename from docs/versioned_docs/version-1.10.3/api/gesture-handlers/rotation-gh.md rename to docs/versioned_docs/version-1.x/api/gesture-handlers/rotation-gh.md diff --git a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/tap-gh.md b/docs/versioned_docs/version-1.x/api/gesture-handlers/tap-gh.md similarity index 80% rename from docs/versioned_docs/version-1.10.3/api/gesture-handlers/tap-gh.md rename to docs/versioned_docs/version-1.x/api/gesture-handlers/tap-gh.md index 5ecc567099..26f648111e 100644 --- a/docs/versioned_docs/version-1.10.3/api/gesture-handlers/tap-gh.md +++ b/docs/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](../../state.md#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](../../state.md#active), it will [END](../../state.md#end). +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). ## 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](../../state.md#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/under-the-hood/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](../../state.md#active) the handler. The default value is 1. +Number of tap gestures required to [activate](/docs/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](../../state.md#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/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](../../state.md#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/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](../../state.md#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/under-the-hood/state#active), it will fail to recognize the gesture. ## Event data diff --git a/docs/versioned_docs/version-1.10.3/contributing.md b/docs/versioned_docs/version-1.x/contributing.md similarity index 100% rename from docs/versioned_docs/version-1.10.3/contributing.md rename to docs/versioned_docs/version-1.x/contributing.md diff --git a/docs/versioned_docs/version-1.10.3/credits.md b/docs/versioned_docs/version-1.x/credits.md similarity index 100% rename from docs/versioned_docs/version-1.10.3/credits.md rename to docs/versioned_docs/version-1.x/credits.md diff --git a/docs/versioned_docs/version-1.10.3/example.md b/docs/versioned_docs/version-1.x/example.md similarity index 93% rename from docs/versioned_docs/version-1.10.3/example.md rename to docs/versioned_docs/version-1.x/example.md index 9527cc83aa..0c5e3b2634 100644 --- a/docs/versioned_docs/version-1.10.3/example.md +++ b/docs/versioned_docs/version-1.x/example.md @@ -21,7 +21,7 @@ You can run example app on [Expo](https://expo.io). Follow instructions under [t ## Running example app locally -Before you begin you should follow [React Native's setup steps](http://facebook.github.io/react-native/docs/getting-started.html) to make sure you have all the tools necessary to build and run React Native apps installed. +Before you begin you should follow [React Native's setup steps](http://reactnative.dev/docs/getting-started.html) to make sure you have all the tools necessary to build and run React Native apps installed. The example app is a regular React Native app, so in case of problems or to learn about available commands you may want to [check react-native cli documentation](https://github.com/react-native-community/cli/blob/master/README.md). In order to run example app you need to clone the repo first: diff --git a/docs/versioned_docs/version-1.10.3/getting-started.md b/docs/versioned_docs/version-1.x/getting-started.md similarity index 98% rename from docs/versioned_docs/version-1.10.3/getting-started.md rename to docs/versioned_docs/version-1.x/getting-started.md index b66c9677c6..854cf26780 100644 --- a/docs/versioned_docs/version-1.10.3/getting-started.md +++ b/docs/versioned_docs/version-1.x/getting-started.md @@ -5,7 +5,7 @@ sidebar_label: Getting Started slug: / --- -Gesture Handler aims to replace React Native's built in touch system called [Gesture Responder System](http://facebook.github.io/react-native/docs/gesture-responder-system). +Gesture Handler aims to replace React Native's built in touch system called [Gesture Responder System](http://reactnative.dev/docs/gesture-responder-system). The motivation for building this library was to address the performance limitations of React Native's Gesture Responder System and to provide more control over the built-in native components that can handle gestures. 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. @@ -40,7 +40,7 @@ To use the version of react-native-gesture-handler that is compatible with your The Expo SDK incorporates the latest version of react-native-gesture-handler available at the time of each SDK release, so managed Expo apps might not always support all our latest features as soon as they are available. -#### Bare [React Native](http://facebook.github.io/react-native/) +#### Bare [React Native](http://reactnative.dev/) Since the library uses native support for handling gestures, it requires an extended installation to the norm. If you are starting a new project, you may want to initialize it with [expo-cli](https://docs.expo.io/versions/latest/workflow/expo-cli/) and use a bare template, they come pre-installed with react-native-gesture-handler. diff --git a/docs/versioned_docs/version-1.10.3/interactions.md b/docs/versioned_docs/version-1.x/interactions.md similarity index 100% rename from docs/versioned_docs/version-1.10.3/interactions.md rename to docs/versioned_docs/version-1.x/interactions.md diff --git a/docs/versioned_docs/version-1.10.3/resources.md b/docs/versioned_docs/version-1.x/resources.md similarity index 100% rename from docs/versioned_docs/version-1.10.3/resources.md rename to docs/versioned_docs/version-1.x/resources.md diff --git a/docs/versioned_docs/version-1.10.3/state.md b/docs/versioned_docs/version-1.x/state.md similarity index 100% rename from docs/versioned_docs/version-1.10.3/state.md rename to docs/versioned_docs/version-1.x/state.md diff --git a/docs/versioned_docs/version-1.10.3/troubleshooting.md b/docs/versioned_docs/version-1.x/troubleshooting.md similarity index 100% rename from docs/versioned_docs/version-1.10.3/troubleshooting.md rename to docs/versioned_docs/version-1.x/troubleshooting.md diff --git a/docs/versioned_docs/version-2.0.0/api/components/buttons.mdx b/docs/versioned_docs/version-2.0.0/api/components/buttons.mdx deleted file mode 100644 index ac8657a5eb..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/components/buttons.mdx +++ /dev/null @@ -1,170 +0,0 @@ ---- -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` -- `RectButton` -- `BorderlessButton` - -On top of that all the buttons are wrapped with `NativeViewGestureHandler` and therefore allow for all the [common gesture handler properties](#common-gesturehandler-properties) and `NativeViewGestureHandler`'s [extra properties](#nativeviewgesturehandler-extra-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). - -### `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`. - -## `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`](#basebutton-component), 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`](#basebutton-component), 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/docs/versioned_docs/version-2.0.0/api/components/swipeable.md b/docs/versioned_docs/version-2.0.0/api/components/swipeable.md deleted file mode 100644 index bf49f033ed..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/components/swipeable.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -id: swipeable -title: Swipeable -sidebar_label: Swipeable ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import GifGallery from '@site/components/GifGallery' - - - - - -This component 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: - -Similarly to the `DrawerLayout`, `Swipeable` component isn't exported by default from the `react-native-gesture-handler` package. To use it, import it in the following way: - -```js -import Swipeable from 'react-native-gesture-handler/Swipeable'; -``` - -## 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. - -### `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 method 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 method 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. - -### `onSwipeableLeftOpen` - -method that is called when left action panel gets open. - -### `onSwipeableRightOpen` - -method that is called when right action panel gets open. - -### `onSwipeableOpen` - -method that is called when action panel gets open (either right or left). - -### `onSwipeableClose` - -method that is called when action panel is closed. - -### `onSwipeableLeftWillOpen` - -method that is called when left action panel starts animating on open. - -### `onSwipeableRightWillOpen` - -method that is called when right action panel starts animating on open. - -### `onSwipeableWillOpen` - -method that is called when action panel starts animating on open (either right or left). - -### `onSwipeableWillClose` - -method that is called when action panel starts animating on close. - -### `renderLeftActions` - -method that is expected to return an action panel that is going to be revealed from the left side when user swipes right. -This map describes the values to use as inputRange for extra interpolation: -AnimatedValue: [startValue, endValue] - -progressAnimatedValue: [0, 1] -dragAnimatedValue: [0, +] - -To support `rtl` flexbox layouts use `flexDirection` styling. - -### `renderRightActions` - -method that is expected to return an action panel that is going to be revealed from the right side when user swipes left. -This map describes the values to use as inputRange for extra interpolation: -AnimatedValue: [startValue, endValue] - -progressAnimatedValue: [0, 1] -dragAnimatedValue: [0, -] - -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`. - -### `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. - -## Methods - -Using reference to `Swipeable` it's possible to trigger some actions on it - -### `close` - -method that closes component. - -### `openLeft` - -method that opens component on left side. - -### `openRight` - -method that opens component on right side. - -### Example: - -See the [swipeable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/showcase/swipeable/index.tsx) from [GestureHandler Example App](example.md) or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -import React, { Component } from 'react'; -import { Animated, StyleSheet, View } from 'react-native'; -import { RectButton } from 'react-native-gesture-handler'; -import Swipeable from 'react-native-gesture-handler/Swipeable'; - -class AppleStyleSwipeableRow extends Component { - renderLeftActions = (progress, dragX) => { - const trans = dragX.interpolate({ - inputRange: [0, 50, 100, 101], - outputRange: [-20, 0, 0, 1], - }); - return ( - - - Archive - - - ); - }; - render() { - return ( - - "hello" - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.0.0/api/components/touchables.md b/docs/versioned_docs/version-2.0.0/api/components/touchables.md deleted file mode 100644 index dff1719b63..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/components/touchables.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -id: touchables -title: Touchables -sidebar_label: Touchables ---- - -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://facebook.github.io/react-native/docs/touchablenativefeedback) -- [Touchable Highlight](https://facebook.github.io/react-native/docs/touchablehighlight) -- [Touchable Opacity](https://facebook.github.io/react-native/docs/touchableopacity) -- [Touchable Without Feedback](https://facebook.github.io/react-native/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. - -### 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/example/src/release_tests/touchables/index.tsx) diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/base-continous-gesture-callbacks.md b/docs/versioned_docs/version-2.0.0/api/gestures/base-continous-gesture-callbacks.md deleted file mode 100644 index 6b9a0e94a3..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/base-continous-gesture-callbacks.md +++ /dev/null @@ -1,5 +0,0 @@ -### Callbacks common to all continous gestures: - -### `onUpdate(callback)` - -Set the callback that is being called every time the gesture receives an update while it's active. diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/base-continous-gesture-config.md b/docs/versioned_docs/version-2.0.0/api/gestures/base-continous-gesture-config.md deleted file mode 100644 index a19473784e..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/base-continous-gesture-config.md +++ /dev/null @@ -1,5 +0,0 @@ -### Properties common to all continous gestures: - -### `manualActivation(value: boolead)` - -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](./state-manager.md). diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/base-gesture-callbacks.md b/docs/versioned_docs/version-2.0.0/api/gestures/base-gesture-callbacks.md deleted file mode 100644 index dff985b307..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/base-gesture-callbacks.md +++ /dev/null @@ -1,33 +0,0 @@ -### Callbacks common to all gestures: - -### `onBegin(callback)` - -Set the callback that is being called when given gesture handler starts receiving touches. At the moment of this callback the handler is not yet in an active state and we don't know yet if it will recognize the gesture at all. - -### `onStart(callback)` - -Set the callback that is being called when the gesture is recognized by the handler and it transitions to the active state. - -### `onEnd(callback)` - -Set the callback that is being called when the gesture that was recognized by the handler finishes. It will be called only if the handler was previously in the active state. - -### `onFinalize(callback)` - -Set the callback that is being called when the handler finalizes handling gesture - the gesture was recognized and has finished or it failed to recognize. - -### `onTouchesDown(callback)` - -Set the `onTouchesDown` callback which is called every time a finger is placed on the screen. - -### `onTouchesMove(callback)` - -Set the `onTouchesMove` callback which is called every time a finger is moved on the screen. - -### `onTouchesUp(callback)` - -Set the `onTouchesUp` callback which is called every time a finger is lifted from the screen. - -### `onTouchesCancelled(callback)` - -Set the `onTouchesCancelled` callback which is called every time a finger stops being tracked, for example when the gesture finishes. diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/base-gesture-config.md b/docs/versioned_docs/version-2.0.0/api/gestures/base-gesture-config.md deleted file mode 100644 index bcc364192b..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/base-gesture-config.md +++ /dev/null @@ -1,44 +0,0 @@ -### 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`](../../under-the-hood/states-events.md#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`](../../under-the-hood/states-events.md#failed) or [`CANCELLED`](../../under-the-hood/states-events.md#cancelled) (depending on its current state). -Default value is `true`. - -### `shouldCancelWhenOutside(value: boolean)` - -When `true` the handler will [cancel](../../under-the-hood/states-events.md#cancelled) or [fail](../../under-the-hood/states-events.md#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`](./long-press-gesture.md) and [`TapGesture`](./tap-gesture.md) which default to `true`. - -### `hitSlop(settings)` - -This parameter enables control over what part of the connected view area can be used to [begin](../../under-the-hood/states-events.md#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://facebook.github.io/react-native/docs/view.html#props) property. - -### `withRef(ref)` - -Sets a ref to the gesture object, allowing for interoperability with the old API. - -### `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](../../gesture-composition). [`GestureDetector`](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. - -**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](../../gesture-composition).[`GestureDetector`](gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/composed-gestures.md b/docs/versioned_docs/version-2.0.0/api/gestures/composed-gestures.md deleted file mode 100644 index 84e2e451bd..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/composed-gestures.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: composed-gestures -title: Composed gestures -sidebar_label: Composed gestures ---- - -Composed gestures (`Race`, `Simultaneous`, `Exclusive`) provide a simple way of building relations between gestures. diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/fling-gesture.md b/docs/versioned_docs/version-2.0.0/api/gestures/fling-gesture.md deleted file mode 100644 index 818cb3868e..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/fling-gesture.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -id: fling-gesture -title: Fling gesture -sidebar_label: Fling gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; - -A discrete gesture that activates when the movement is sufficiently long and fast. -Gesture gets [ACTIVE](../../under-the-hood/states-events.md#active) when movement is sufficiently long and it does not take too much time. -When gesture gets activated it will turn into [END](../../under-the-hood/states-events.md#end) state when finger is released. -The gesture will fail to recognize if the finger is lifted before being activated. - -## Config - -### Properties specific to `FlingGesture`: - -### `direction(value: Directions)` - -Expressed allowed direction of movement. Expected values are exported as constants in the `Directions` object. It's possible to pass one or many directions in one parameter: - -```js -fling.direction(Directions.RIGHT | Directions.LEFT); -``` - -or - -```js -fling.direction(Directions.DOWN); -``` - -### `numberOfPointers(value: number)` - -Determine exact number of points required to handle the fling gesture. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `FlingGesture`: - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. 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. - - - -## Example - -```jsx -const position = useSharedValue(0); - -const flingGesture = Gesture.Fling() - .direction(Directions.RIGHT) - .onStart((e) => { - position.value = withTiming(position.value + 10, { duration: 100 }); - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ translateX: position.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/force-touch-gesture.md b/docs/versioned_docs/version-2.0.0/api/gestures/force-touch-gesture.md deleted file mode 100644 index 8280f944b1..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/force-touch-gesture.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -id: force-touch-gesture -title: Force touch gesture (iOS only) -sidebar_label: Force touch gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-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](../../under-the-hood/states-events.md#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. - -There's no implementation provided on Android and it simply renders children without any wrappers. -Since this behaviour is only provided on some iOS devices, this gesture should not be used for defining any crucial behaviors. Use it only as an additional improvement and make all features to be accessed without this gesture as well. - -## Config - -### Properties specific to `ForceTouchGesture`: - -### `minForce(value: number)` - -A minimal pressure that is required before gesture can [activate](../../under-the-hood/states-events.md#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](../../under-the-hood/states-events.md#failed). Should be a value from range `[0.0, 1.0]`. - -### `feedbackOnActivation(value: boolean)` - -Value defining if haptic feedback has to be performed on activation. - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `ForceTouchGesture`: - -### `force` - -The pressure of a touch. - - diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/gesture-detector-functional1.md b/docs/versioned_docs/version-2.0.0/api/gestures/gesture-detector-functional1.md deleted file mode 100644 index 2397af9dfa..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/gesture-detector-functional1.md +++ /dev/null @@ -1,19 +0,0 @@ -```jsx -export default function Example() { - const tap = Gesture.Tap().onStart(() => { - console.log('tap'); - }); - - return ( - - - - - - ); -} - -function FunctionalComponent(props) { - return {props.children}; -} -``` diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/gesture-detector.md b/docs/versioned_docs/version-2.0.0/api/gestures/gesture-detector.md deleted file mode 100644 index ef8af9b62c..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/gesture-detector.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -id: gesture-detector -title: GestureDetector -sidebar_label: Gesture detector ---- - -import FunctionalComponents from './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.x/). - -:::caution -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. -::: - -## 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 synchrously. - -Starting with Reanimated-2.3.0-beta.4 Gesture Handler will provide a [StateManager](./state-manager.md) in the [touch events](./touch-events.md) that allows for managing the state of the gesture. -::: diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/gesture.md b/docs/versioned_docs/version-2.0.0/api/gestures/gesture.md deleted file mode 100644 index a84a48003a..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/gesture.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -id: gesture -title: Gesture -sidebar_label: Gesture ---- - -`Gesture` is the object that allows you to create and compose gestures. - -### Gesture.Tap() - -Creates a new instance of [`TapGesture`](./tap-gesture.md) with its default config and no callbacks. - -### Gesture.Pan() - -Creates a new instance of [`PanGesture`](./pan-gesture.md) with its default config and no callbacks. - -### Gesture.LongPress() - -Creates a new instance of [`LongPressGesture`](./long-press-gesture.md) with its default config and no callbacks. - -### Gesture.Fling() - -Creates a new instance of [`FlingGesture`](./fling-gesture.md) with its default config and no callbacks. - -### Gesture.Pinch() - -Creates a new instance of [`PinchGesture`](./pinch-gesture.md) with its default config and no callbacks. - -### Gesture.Rotation() - -Creates a new instance of [`RotationGesture`](./rotation-gesture.md) with its default config and no callbacks. - -### Gesture.ForceTouch() - -Creates a new instance of [`ForceTouchGesture`](./force-touch-gesture.md) with its default config and no callbacks. - -### Gesture.Manual() - -Creates a new instance of [`ManualGesture`](./manual-gesture.md) with its default config and no callbacks. - -### Gesture.Native() - -Creates a new instance of [`NativeGesture`](./native-gesture.md) with its default config and no callbacks. - -### Gesture.Race(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. Only one of those can become active and there are no restrictions to the activation of the gesture. The first one to activate will cancel all the others. - -### Gesture.Simultaneous(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. All of them can become active without cancelling the others. - -### Gesture.Exclusive(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. Only one of them can become active, but the first one has a higher priority than the second one, the second one has a higher priority than the third one, and so on. When all gestures are in the `BEGAN` state and the activation criteria for the second one is met, instead of activating it will wait until the first one fails (and only then it will activate) or until the first one activates (and then the second one will get cancelled). It is useful when you want to compose gestures with similar activation criteria (e.g. single and double tap at the same component, without Exclusive the single tap would activate every time user taps thus cancelling the double tap). diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/long-press-gesture.md b/docs/versioned_docs/version-2.0.0/api/gestures/long-press-gesture.md deleted file mode 100644 index e13bdb4ce1..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/long-press-gesture.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -id: long-press-gesture -title: Long press gesture -sidebar_label: Long press gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './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](../../under-the-hood/states-events.md#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](#mindurationms) or if the finger is moved further than the [allowable distance](#maxdist). - -## Config - -### Properties specific to `LongPressGesture`: - -### `minDuration(value: number)` - -Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. - -### `maxDistance(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. The default value is 10. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `LongPressGesture`: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `duration` - -Duration of the long press (time since the start of the gesture), expressed in milliseconds. - - - -## Example - -```jsx -const longPressGesture = Gesture.LongPress().onEnd((e, success) => { - if (success) { - Alert.alert(`Long pressed for ${e.duration} ms!`); - } -}); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/manual-gesture.md b/docs/versioned_docs/version-2.0.0/api/gestures/manual-gesture.md deleted file mode 100644 index a92c6986ef..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/manual-gesture.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -id: manual-gesture -title: Manual gesture -sidebar_label: Manual gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A plain gesture that has no specific activation criteria nor event data set. Its state has to be controlled manually using a [state manager](./state-manager.md). It will not fail when all the pointers are lifted from the screen. - -## Config - - - -## Callbacks - - - - -## Event data - - diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/native-gesture.md b/docs/versioned_docs/version-2.0.0/api/gestures/native-gesture.md deleted file mode 100644 index 6fa7249eed..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/native-gesture.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -id: native-gesture -title: Native gesture -sidebar_label: Native gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A gesture that allows other touch handling components to participate in RNGH's gesture system. When used, the other component should be the direct child of a `GestureDetector`. - -## Config - -### Properties specific to `NativeGesture`: - -### `shouldActivateOnStart(value: boolean)` (**Android only**) - -When `true`, underlying handler will activate unconditionally when in `BEGAN` or `UNDETERMINED` state. - -### `disallowInterruption(value: boolean)` - -When `true`, cancels all other gesture handlers when this `NativeViewGestureHandler` receives an `ACTIVE` state event. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `NativeGesture`: - -### `pointerInside` - -True if gesture was performed inside of containing view, false otherwise. - - diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/pan-gesture.md b/docs/versioned_docs/version-2.0.0/api/gestures/pan-gesture.md deleted file mode 100644 index 28c39a86eb..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/pan-gesture.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -id: pan-gesture -title: Pan gesture -sidebar_label: Pan gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that can recognize a panning (dragging) gesture and track its movement. - -The gesture [activates](../../under-the-hood/states-events.md#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. - -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. - -## 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. - -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 [`avgTouches`](#avgtouches-android-only) flag. - -Note that on both Android and iOS when the additional finger is placed on the screen that translation prop is not affected even though the position of the pointer being tracked might have changed. -Therefore it is safe to rely on translation most of the time as it only reflects the movement that happens regardless of how many fingers are placed on the screen and if that number changes over time. -If you wish to track the "center of mass" virtual pointer and account for its changes when the number of finger changes you can use relative or absolute position provided in the event ([`x`](#x) and [`y`](#y) or [`absoluteX`](#absolutex) and [`absoluteY`](#absolutey)). - -## Config - -### Properties specific to `PanGesture`: - -### `minDistance(value: number)` - -Minimum distance the finger (or multiple finger) need to travel before the gesture [activates](../../under-the-hood/states-events.md#active). Expressed in points. - -### `minPointers(value: number)` - -A number of fingers that is required to be placed before gesture can [activate](../../under-the-hood/states-events.md#active). Should be a higher or equal to 0 integer. - -### `maxPointers(value: number)` - -When the given number of fingers is placed on the screen and gesture hasn't yet [activated](../../under-the-hood/states-events.md#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. - -### `activeOffsetX(value: number | number[])` - -Range along X axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `activeOffsetY(value: number | number[])` - -Range along Y axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `failOffsetY(value: number | number[])` - -When the finger moves outside this range (in points) along Y axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `failOffsetX(value: number | number[])` - -When the finger moves outside this range (in points) along X axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `averageTouches(value: boolean)` (Android only) - -### `enableTrackpadTwoFingerGesture(value: boolean)` (iOS only) - -Enables two-finger gestures on supported devices, for example iPads with trackpads. If not enabled the gesture will require click + drag, with enableTrackpadTwoFingerGesture swiping with two fingers will also trigger the gesture. - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `PanGesture`: - -### `translationX` - -Translation of the pan gesture along X axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `translationY` - -Translation of the pan gesture along Y axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `velocityX` - -Velocity of the pan gesture along the X axis in the current moment. The value is expressed in point units per second. - -### `velocityY` - -Velocity of the pan gesture along the Y axis in the current moment. The value is expressed in point units per second. - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. 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. - - - -## Example - -```jsx -const END_POSITION = 200; -const onLeft = useSharedValue(true); -const position = useSharedValue(0); - -const panGesture = Gesture.Pan() - .onUpdate((e) => { - if (onLeft.value) { - position.value = e.translationX; - } else { - position.value = END_POSITION + e.translationX; - } - }) - .onEnd((e) => { - if (position.value > END_POSITION / 2) { - position.value = withTiming(END_POSITION, { duration: 100 }); - onLeft.value = false; - } else { - position.value = withTiming(0, { duration: 100 }); - onLeft.value = true; - } - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ translateX: position.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/pinch-gesture.md b/docs/versioned_docs/version-2.0.0/api/gestures/pinch-gesture.md deleted file mode 100644 index 5b56e7d043..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/pinch-gesture.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -id: pinch-gesture -title: Pinch gesture -sidebar_label: Pinch gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. -The gesture [activates](../../under-the-hood/states-events.md#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. - -## Config - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `PinchGesture`: - -### `scale` - -The scale factor relative to the points of the two touches in screen coordinates. - -### `velocity` - -Velocity of the pan gesture the current moment. The value is expressed in point units per second. - -### `focalX` - -Position expressed in points along X axis of center anchor point of gesture - -### `focalY` - -Position expressed in points along Y axis of center anchor point of gesture - - - -## Example - -```jsx -const scale = useSharedValue(1); -const savedScale = useSharedValue(1); - -const pinchGesture = Gesture.Pinch() - .onUpdate((e) => { - scale.value = savedScale.value * e.scale; - }) - .onEnd(() => { - savedScale.value = scale.value; - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ scale: scale.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/rotation-gesture.md b/docs/versioned_docs/version-2.0.0/api/gestures/rotation-gesture.md deleted file mode 100644 index 6550e0ea98..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/rotation-gesture.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -id: rotation-gesture -title: Rotation gesture -sidebar_label: Rotation gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that can recognize a rotation gesture and track its movement. - -The gesture [activates](../../under-the-hood/states-events.md#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. - -## Config - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `RotationGesture`: - -### `rotation` - -Amount rotated, expressed in radians, from the gesture's focal point (anchor). - -### `velocity` - -Instantaneous velocity, expressed in point units per second, of the gesture. - -### `anchorX` - -X coordinate, expressed in points, of the gesture's central focal point (anchor). - -### `anchorY` - -Y coordinate, expressed in points, of the gesture's central focal point (anchor). - - - -## Example - -```jsx -const rotation = useSharedValue(1); -const savedRotation = useSharedValue(1); - -const rotationGesture = Gesture.Rotation() - .onUpdate((e) => { - rotation.value = savedRotation.value + e.rotation; - }) - .onEnd(() => { - savedRotation.value = rotation.value; - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ rotateZ: `${(rotation.value / Math.PI) * 180}deg` }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/state-manager.md b/docs/versioned_docs/version-2.0.0/api/gestures/state-manager.md deleted file mode 100644 index cb50e8212b..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/state-manager.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: state-manager -title: Gesture state manager -sidebar_label: Gesture state manager ---- - -`GestureStateManager` allows to manually control the state of the gestures. Please note that `react-native-reanimated` is required to use it, since it allows for synchronously executing methods in worklets. - -## Methods - -### `begin()` - -Transition the gesture to the [`BEGAN`](../../under-the-hood/states-events.md#began) state. This method will have no effect if the gesture has already activated or finished. - -### `activate()` - -Transition the gesture to the [`ACTIVE`](../../under-the-hood/states-events.md#active) state. This method will have no effect if the handler is already active, or has finished. -If the gesture is [`exclusive`](../../gesture-composition) with another one, the activation will be delayed until the gesture with higher priority fails. - -### `end()` - -Transition the gesture to the [`END`](../../under-the-hood/states-events.md#end) state. This method will have no effect if the handler has already finished. - -### `fail()` - -Transition the gesture to the [`FAILED`](../../under-the-hood/states-events.md#failed) state. This method will have no effect if the handler has already finished. diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/tap-gesture.md b/docs/versioned_docs/version-2.0.0/api/gestures/tap-gesture.md deleted file mode 100644 index 51b611b94e..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/tap-gesture.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -id: tap-gesture -title: Tap gesture -sidebar_label: Tap gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; - -A discrete gesture that recognizes one or many taps. - -Tap gestures detect one or more fingers briefly touching the screen. -The fingers involved in these gestures must not move significantly from their initial touch positions. -The required number of taps and allowed distance from initial position may be configured. -For example, you might configure tap gesture recognizers to detect single taps, double taps, or triple taps. - -In order for a gesture to [activate](../../under-the-hood/states-events.md#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the gesture [activates](../../under-the-hood/states-events.md#active), it will [end](../../under-the-hood/states-events.md#end). - -## Config - -### Properties specific to `TapGesture`: - -### `minPointers(value: number)` - -Minimum number of pointers (fingers) required to be placed before the gesture [activates](../../under-the-hood/states-events.md#active). Should be a positive integer. The default value is 1. - -### `maxDuration(value: number)` - -Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch. The default value is 500. - -### `maxDelay(value: number)` - -Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required. The default value is 500. - -### `numberOfTaps(value: number)` - -Number of tap gestures required to [activate](../../under-the-hood/states-events.md#active) the gesture. The default value is 1. - -### `maxDeltaX(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the X axis during a tap gesture. If the finger travels further than the defined distance along the X axis and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - -### `maxDeltaY(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the Y axis during a tap gesture. If the finger travels further than the defined distance along the Y axis and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - -### `maxDistance(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a tap gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `TapGesture`: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - - - -## Example - -```jsx -const singleTap = Gesture.Tap() - .maxDurationMs(250) - .onStart(() => { - Alert.alert('Single tap!'); - }); - -const doubleTap = Gesture.Tap() - .maxDurationMs(250) - .onStart(() => { - Alert.alert('Double tap!'); - }); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.0.0/api/gestures/touch-events.md b/docs/versioned_docs/version-2.0.0/api/gestures/touch-events.md deleted file mode 100644 index c4eb21cc2b..0000000000 --- a/docs/versioned_docs/version-2.0.0/api/gestures/touch-events.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -id: touch-events -title: Touch events -sidebar_label: Touch events ---- - -### Touch event attributes: - -### `eventType` - -Type of the current event - whether the finger was placed on the screen, moved, lifted or cancelled. - -### `changedTouches` - -An array of objects where every object represents a single touch. Contains information only about the touches that were affected by the event i.e. those that were placed down, moved, lifted or cancelled. - -### `allTouches` - -An array of objects where every object represents a single touch. Contains information about all active touches. - -### `numberOfTouches` - -Number representing the count of currently active touches. - -:::caution -Don't rely on the order of items in the `touches` as it may change during the gesture, instead use the `id` attribute to track individual touches across events. -::: - -### PointerData attributes: - -### `id` - -A number representing id of the touch. It may be used to track the touch between events as the id will not change while it is being tracked. - -### `x` - -X coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the touch relative to the root view. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the touch relative to the root view. 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/docs/versioned_docs/version-2.0.0/community.md b/docs/versioned_docs/version-2.0.0/community.md deleted file mode 100644 index 740f408a4d..0000000000 --- a/docs/versioned_docs/version-2.0.0/community.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -id: community -title: Community -sidebar_label: 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
-
- -
-
- -
-
Jakub Gonet
-
- -
-
- -
-
Krzysztof Magiera
- @kzzzf -
- -
- -## 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: - -
- -
- -
- -
-
Shopify
- -
- -
- -
- -
-
Expo
- -
- -
diff --git a/docs/versioned_docs/version-2.0.0/contributing.md b/docs/versioned_docs/version-2.0.0/contributing.md deleted file mode 100644 index c3b9ab2a33..0000000000 --- a/docs/versioned_docs/version-2.0.0/contributing.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -id: contributing -title: Contributing ---- - -If you are interested in the project and want to contribute or support it in other ways don't hesitate to contact [me on Twitter](https://twitter.com/kzzzf)! - -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. diff --git a/docs/versioned_docs/version-2.0.0/example.md b/docs/versioned_docs/version-2.0.0/example.md deleted file mode 100644 index 3586ddd55c..0000000000 --- a/docs/versioned_docs/version-2.0.0/example.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -id: example -title: Running Example App ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import GifGallery from '@site/components/GifGallery' - -Example app code is located under [`example/`](https://github.com/software-mansion/react-native-gesture-handler/tree/main/example) folder in the repo. -It showcases the majority of the Gesture Handler library features. -The app consist of the list of single screen examples presenting the capabilities of the library. -Each example is located under a separate folder under [`example/`](https://github.com/software-mansion/react-native-gesture-handler/tree/main/example). - - - - - -## Running example app locally - -Before you begin you should follow [React Native's setup steps](http://facebook.github.io/react-native/docs/getting-started.html) to make sure you have all the tools necessary to build and run React Native apps installed. -The example app is a regular React Native app, so in case of problems or to learn about available commands you may want to [check react-native cli documentation](https://github.com/react-native-community/cli/blob/master/README.md). - -In order to run example app you need to clone the repo first: - -```bash -git clone git@github.com:software-mansion/react-native-gesture-handler.git -``` - -Then go to the library folder: - -```bash -cd react-native-gesture-handler/ -``` - -Install dependencies of library with the following command: - -```bash -yarn -``` - -Then go to the `example` folder: - -```bash -cd example -``` - -Install dependencies of example with the following command: - -```bash -yarn -``` - -Run development server: - -```bash -yarn start -``` - -Finally run one of the commands below in order to build, install and launch the app on Android: - -```bash -yarn android -``` - -or on iOS: - -```bash -yarn ios -``` - -You will need to have an Android or iOS device or emulator connected and `react-native-cli` package installed globally. diff --git a/docs/versioned_docs/version-2.0.0/gesture-composition.md b/docs/versioned_docs/version-2.0.0/gesture-composition.md deleted file mode 100644 index e55e06fae6..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-composition.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -id: gesture-composition -title: Composing gestures -sidebar_label: Composing gestures ---- - -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 -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 -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 -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 ( - - - -); -``` - -## Composition vs `simultaneousWithExternalGesture` and `requireExternalGestureToFail` - -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. If you want to make a relation between gestures that are attached to separate `GestureDetectors`, we have a separate mechanism for that: `simultaneousWithExternalGesture` and `requireExternalGestureToFail` methods that are available on every base gesture. They work exactly the same way as `simultaneousHandlers` and `waitFor` on gesture handlers, that is they just mark the relation between the gestures without joining them into single object. diff --git a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/common-gh.md b/docs/versioned_docs/version-2.0.0/gesture-handlers/api/common-gh.md deleted file mode 100644 index 471f5250c2..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/common-gh.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -id: common-gh -title: Common handler properties -sidebar_label: Common handler properties ---- - -This page covers the common set of properties all gesture handler components expose. - -### Units - -All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". -These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://facebook.github.io/react-native/docs/flexbox.html)). -They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. - -## Properties - -This section describes properties that can be used with all gesture handler components: - -### `enabled` - -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`](../basics/state.md#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`](../basics/state.md#failed) or [`CANCELLED`](../basics/state.md#cancelled) (depending on its current state). -Default value is `true`. - -### `shouldCancelWhenOutside` - -Accepts a boolean value. -When `true` the handler will [cancel](../basics/state.md#cancelled) or [fail](../basics/state.md#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.md) and [`TapGestureHandler`](./tap-gh.md) 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](../basics/state.md#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](../basics/state.md#active) state. It will also prevent the provided handlers from [cancelling](../basics/state.md#cancelled) the current handler when they [activate](../basics/state.md#active). Read more in the [cross handler interaction](../basics/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](../basics/state.md#active) as long as the handlers provided by their refs are in the [`BEGAN`](../basics/state.md#began) state. Read more in the [cross handler interaction](../basics/interactions.md#awaiting-other-handlers) section. - -### `hitSlop` - -This parameter enables control over what part of the connected view area can be used to [begin](../basics/state.md#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://facebook.github.io/react-native/docs/view.html#props) property. - -### `onGestureEvent` - -Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](../basics/state.md#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.md#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://facebook.github.io/react-native/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](../basics/state.md) 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](../basics/state.md) of the handler right before the change. - -Instead of a callback [`Animated.event`](https://facebook.github.io/react-native/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. - -## Event data - -This section describes the attributes of event object being provided to [`onGestureEvent`](#ongestureevent) and [`onHandlerStateChange`](#onhandlerstatechange) callbacks: - -### `state` - -Current [state](../basics/state.md) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](../basics/state.md) to learn more about how to use it. - -### `numberOfPointers` - -Represents the number of pointers (fingers) currently placed on the screen. diff --git a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/create-native-wrapper.md b/docs/versioned_docs/version-2.0.0/gesture-handlers/api/create-native-wrapper.md deleted file mode 100644 index 519f7c583c..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/create-native-wrapper.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -id: create-native-wrapper -title: createNativeWrapper -sidebar_label: createNativeWrapper() ---- - -Creates provided component with NativeViewGestureHandler, allowing it to be part of RNGH's -gesture system. - -## Arguments - -### Component - -The component we want to wrap. - -### config - -Config is an object with properties that can be used on [`NativeViewGestureHandler`](./nativeview-gh.md) - -## Returns - -Wrapped component. diff --git a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/fling-gh.md b/docs/versioned_docs/version-2.0.0/gesture-handlers/api/fling-gh.md deleted file mode 100644 index 36a385ecbc..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/fling-gh.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -id: fling-gh -title: FlingGestureHandler -sidebar_label: Fling ---- - -A discrete gesture handler that activates when the movement is sufficiently long and fast. -Handler gets [ACTIVE](../basics/state#active) when movement is sufficiently long and it does not take too much time. -When handler gets activated it will turn into [END](../basics/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](./common-gh.md#properties). Below is a list of properties specific to `FlingGestureHandler` component: - -### `direction` - -Expressed allowed direction of movement. It's possible to pass one or many directions in one parameter: - -```js -direction={Directions.RIGHT | Directions.LEFT} -``` - -or - -```js -direction={Directions.DOWN} -``` - -### `numberOfPointers` - -Determine exact number of points required to handle the fling gesture. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `FlingGestureHandler`: - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. 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. - -## Example - -See the [fling example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/release_tests/fling/index.tsx) from [GestureHandler Example App](../../example.md). - -```js -const LongPressButton = () => ( - { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert("I'm flinged!"); - } - }}> - - -); -``` diff --git a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/force-gh.md b/docs/versioned_docs/version-2.0.0/gesture-handlers/api/force-gh.md deleted file mode 100644 index ad2102e603..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/force-gh.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -id: force-gh -title: ForceTouchGestureHandler (iOS only) -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](../basics/state.md#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. - -The handler is implemented using custom [UIGestureRecognizer](https://developer.apple.com/documentation/uikit/uigesturerecognizer) on iOS. There's no implementation provided on Android and it simply render children without any wrappers. -Since this behaviour is only provided on some iOS devices, this handler should not be used for defining any crucial behaviors. Use it only as an additional improvement and make all features to be accessed without this handler as well. - -# Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to `ForceTouchGestureHandler` component: - -### `minForce` - -A minimal pressure that is required before handler can [activate](../basics/state.md#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](../basics/state.md#failed). Should be a value from range `[0.0, 1.0]`. - -### `feedbackOnActivation` - -Boolean value defining if haptic feedback has to be performed on activation. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `ForceTouchGestureHandler`: - -### `force` - -The pressure of a touch. - -## Static method - -### `forceTouchAvailable` - -You may check if it's possible to use `ForceTouchGestureHandler` with `ForceTouchGestureHandler.forceTouchAvailable` - -## Example - -See the [force touch handler example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/forcetouch/index.tsx) from [GestureHandler Example App](../../example). - -```js - - - -``` diff --git a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/longpress-gh.md b/docs/versioned_docs/version-2.0.0/gesture-handlers/api/longpress-gh.md deleted file mode 100644 index 3f0a716261..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/longpress-gh.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -id: longpress-gh -title: LongPressGestureHandler -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](../basics/state.md#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.java) on Android. - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to the `LongPressGestureHandler` component: - -### `minDurationMs` - -Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. - -### `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](../basics/state.md#active), it will fail to recognize the gesture. The default value is 10. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to the `LongPressGestureHandler` component: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `duration` - -Duration of the long press (time since the start of the event), expressed in milliseconds. - -## Example - -See the [multitap example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from [GestureHandler Example App](example.md). - -```js -const LongPressButton = () => ( - { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert("I'm being pressed for so long"); - } - }} - minDurationMs={800}> - - -); -``` diff --git a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/nativeview-gh.md b/docs/versioned_docs/version-2.0.0/gesture-handlers/api/nativeview-gh.md deleted file mode 100644 index d857f57ed7..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/nativeview-gh.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -id: nativeview-gh -title: NativeViewGestureHandler -sidebar_label: NativeView ---- - -A gesture handler that allows other touch handling components to participate in -RNGH's gesture system. - -Used by [`createNativeWrapper()`](./create-native-wrapper.md). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to `NativeViewGestureHandler` component: - -### `shouldActivateOnStart` (**Android only**) - -When `true`, underlying handler will activate unconditionally when in `BEGAN` or `UNDETERMINED` state. - -### `disallowInterruption` - -When `true`, cancels all other gesture handlers when this `NativeViewGestureHandler` receives an `ACTIVE` state event. diff --git a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/pan-gh.md b/docs/versioned_docs/version-2.0.0/gesture-handlers/api/pan-gh.md deleted file mode 100644 index beabb460fe..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/pan-gh.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -id: pan-gh -title: PanGestureHandler -sidebar_label: Pan ---- - -A continuous gesture handler that can recognize a panning (dragging) gesture and track its movement. - -The handler [activates](../basics/state.md#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. - -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. - -The handler is implemented using [UIPanGestureRecognizer](https://developer.apple.com/documentation/uikit/uipangesturerecognizer) on iOS and [PanGestureHandler](https://github.com/software-mansion/react-native-gesture-handler/blob/main/android/lib/src/main/java/com/swmansion/gesturehandler/PanGestureHandler.java) on Android. - -## 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](../basics/state.md#active) or [fail](../basics/state.md#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. -Another example would be setting both [`maxDeltaX`](#maxdeltaX) and [`maxDeltaY`](#maxdeltay) to 20 and [`minDist`](#mindist) to 23. -In such a case, if we move a finger along the X-axis by 20 points and along the Y-axis by 0 points, the handler will fail even though the finger is still within the bounds of translation along Y-axis. - -## 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. - -The default behavior for native components like scroll view, pager views or drawers is different and hence gesture handler 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 [`avgTouches`](#avgtouches-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)). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#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](../basics/state.md#active). Expressed in points. - -### `minPointers` - -A number of fingers that is required to be placed before handler can [activate](../basics/state.md#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](../basics/state.md#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. - -### `activeOffsetX` - -Range along X axis (in points) where fingers travels without activation of handler. Moving outside of this range implies activation of handler. 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` - -Range along Y axis (in points) where fingers travels without activation of handler. Moving outside of this range implies activation of handler. 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` - -When the finger moves outside this range (in points) along Y axis and handler 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` - -When the finger moves outside this range (in points) along X axis and handler 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. - -### `maxDeltaX` - -> 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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#active) for the movement in one particular direction use [`minOffsetY`](#minoffsety) instead. - -### `avgTouches` (Android only) - -### `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. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `PanGestureHandler`: - -### `translationX` - -Translation of the pan gesture along X axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `translationY` - -Translation of the pan gesture along Y axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `velocityX` - -Velocity of the pan gesture along the X axis in the current moment. The value is expressed in point units per second. - -### `velocityY` - -Velocity of the pan gesture along the Y axis in the current moment. The value is expressed in point units per second. - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. 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. - -## Example - -See the [draggable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/draggable/index.tsx) from [GestureHandler Example App](../../example). - -```js -const circleRadius = 30; -class Circle extends Component { - _touchX = new Animated.Value(windowWidth / 2 - circleRadius); - _onPanGestureEvent = Animated.event([{ nativeEvent: { x: this._touchX } }], { - useNativeDriver: true, - }); - render() { - return ( - - - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/pinch-gh.md b/docs/versioned_docs/version-2.0.0/gesture-handlers/api/pinch-gh.md deleted file mode 100644 index 094c700516..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/pinch-gh.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -id: pinch-gh -title: PinchGestureHandler -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](../basics/state.md#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. - -The handler is implemented using [UIPinchGestureRecognizer](https://developer.apple.com/documentation/uikit/uipinchgesturerecognizer) on iOS and from scratch on Android. - -## Properties - -Properties provided to `PinchGestureHandler` do not extend [common set of properties from base handler class](./common-gh.md#properties). - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `PinchGestureHandler`: - -### `scale` - -The scale factor relative to the points of the two touches in screen coordinates. - -### `velocity` - -Velocity of the pan gesture the current moment. The value is expressed in point units per second. - -### `focalX` - -Position expressed in points along X axis of center anchor point of gesture - -### `focalY` - -Position expressed in points along Y axis of center anchor point of gesture - -## Example - -See the [scale and rotation example](hhttps://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from [GestureHandler Example App](../../example). - -```js -export class PinchableBox extends React.Component { - _baseScale = new Animated.Value(1); - _pinchScale = new Animated.Value(1); - _scale = Animated.multiply(this._baseScale, this._pinchScale); - _lastScale = 1; - _onPinchGestureEvent = Animated.event( - [{ nativeEvent: { scale: this._pinchScale } }], - { useNativeDriver: USE_NATIVE_DRIVER } - ); - - _onPinchHandlerStateChange = (event) => { - if (event.nativeEvent.oldState === State.ACTIVE) { - this._lastScale *= event.nativeEvent.scale; - this._baseScale.setValue(this._lastScale); - this._pinchScale.setValue(1); - } - }; - - render() { - return ( - - - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/rotation-gh.md b/docs/versioned_docs/version-2.0.0/gesture-handlers/api/rotation-gh.md deleted file mode 100644 index 3e80dda287..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/rotation-gh.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -id: rotation-gh -title: RotationGestureHandler -sidebar_label: Rotation ---- - -A continuous gesture handler that can recognize a rotation gesture and track its movement. - -The handler [activates](../basics/state.md#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. - -The handler is implemented using [UIRotationGestureRecognizer](https://developer.apple.com/documentation/uikit/uirotationgesturerecognizer) on iOS and from scratch on Android. - -## Properties - -Properties provided to `RotationGestureHandler` do not extend [common set of properties from base handler class](./common-gh.md#properties). - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `RotationGestureHandler`: - -### `rotation` - -Amount rotated, expressed in radians, from the gesture's focal point (anchor). - -### `velocity` - -Instantaneous velocity, expressed in point units per second, of the gesture. - -### `anchorX` - -X coordinate, expressed in points, of the gesture's central focal point (anchor). - -### `anchorY` - -Y coordinate, expressed in points, of the gesture's central focal point (anchor). - -## Example - -See the [scale and rotation example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from [GestureHandler Example App](../../example). - -```js -class RotableBox extends React.Component { - _rotate = new Animated.Value(0); - _rotateStr = this._rotate.interpolate({ - inputRange: [-100, 100], - outputRange: ['-100rad', '100rad'], - }); - _lastRotate = 0; - _onRotateGestureEvent = Animated.event( - [{ nativeEvent: { rotation: this._rotate } }], - { useNativeDriver: USE_NATIVE_DRIVER } - ); - _onRotateHandlerStateChange = (event) => { - if (event.nativeEvent.oldState === State.ACTIVE) { - this._lastRotate += event.nativeEvent.rotation; - this._rotate.setOffset(this._lastRotate); - this._rotate.setValue(0); - } - }; - render() { - return ( - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/tap-gh.md b/docs/versioned_docs/version-2.0.0/gesture-handlers/api/tap-gh.md deleted file mode 100644 index dfd9d06715..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-handlers/api/tap-gh.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -id: tap-gh -title: TapGestureHandler -sidebar_label: Tap ---- - -A discrete gesture handler 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 handler to [activate](../basics/state.md#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](../basics/state.md#active), it will [END](../basics/state.md#end). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#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](../basics/state.md#active). Should be a positive integer. The default value is 1. - -### `maxDurationMs` - -Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch. The default value is 500. - -### `maxDelayMs` - -Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required. The default value is 500. - -### `numberOfTaps` - -Number of tap gestures required to [activate](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#active), it will fail to recognize the gesture. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to the `TapGestureHandler` component: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the root view. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -## Example - -See the [multitap example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from [GestureHandler Example App](../../example.md). - -```js -export class PressBox extends Component { - doubleTapRef = React.createRef(); - render() { - return ( - - - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.0.0/gesture-handlers/basics/about-handlers.md b/docs/versioned_docs/version-2.0.0/gesture-handlers/basics/about-handlers.md deleted file mode 100644 index 4c2062a24f..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-handlers/basics/about-handlers.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -id: about-handlers -title: About Gesture Handlers -sidebar_label: About Gesture Handlers ---- - -Gesture handlers are the core building blocks of this library. -We use this term to describe elements of the native touch system that the library allows us to instantiate and control from Javascript using [React's Component](https://reactjs.org/docs/react-component.html) interface. - -Each handler type is capable of recognizing one type of gesture (pan, pinch, etc.) and provides gesture-specific information via events (translation, scale, 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](./state.md). -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](./state.md#active), it cancels all the other gestures (read more about how to influence this process in ["Cross handler interactions"](./interactions.md) 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. - -### Available gesture handlers - -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`](../api/pan-gh.md) -- [`TapGestureHandler`](../api/tap-gh.md) -- [`LongPressGestureHandler`](../api/longpress-gh.md) -- [`RotationGestureHandler`](../api/rotation-gh.md) -- [`FlingGestureHandler`](../api/fling-gh.md) -- [`PinchGestureHandler`](../api/pinch-gh.md) -- [`ForceTouchGestureHandler`](../api/force-gh.md) - -### Discrete vs continuous - -We distinguish between two types of gestures: discrete and continuous. - -Continuous gesture handlers can be [active](./state.md#active) for a long period of time and will generate a stream of [gesture events](../api/common-gh.md#ongestureevent) until the gesture is [over](./state.md#ended). -An example of a continuous handler is [`PanGestureHandler`](../api/pan-gh.md) that once [activated](./state.md#active), will start providing updates about [translation](../api/pan-gh.md#translationx) and other properties. - -On the other hand, discrete gesture handlers once [activated](./state.md#active) will not stay in the active state but will [end](./state.md#ended) immediately. -[`LongPressGestureHandler`](../api/longpress-gh.md) 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`](../api/pan-gh.md)). - -Keep in mind that `onGestureEvent` is only generated in continuous gesture handlers and shouldn't be used in the `TapGestureHandler` and other discrete handlers. - -### Nesting handlers - -Handler components can be nested. In any case it is recommended that the innermost handler renders a native view component. There are some limitations that apply when [using `useNativeDriver` flag](#events-with-usenativedriver). An example of nested handlers: - -```js -class Multitap extends Component { - render() { - return ( - - - - - - - - ); - } -} -``` - -### Using native components - -Gesture handler library exposes a set of components normally available in React Native that are wrapped in [`NativeViewGestureHandler`](../api/nativeview-gh.md). -Here is a list of exposed components: - -- `ScrollView` -- `FlatList` -- `Switch` -- `TextInput` -- `DrawerLayoutAndroid` (**Android only**) - -If you want to use other handlers or [buttons](../../api/components/buttons.mdx) nested in a `ScrollView`, use the [`waitFor`](../api/common-gh.md#waitfor) property to define interaction between a handler and `ScrollView` - -### Events with `useNativeDriver` - -Because handlers do not instantiate native views but instead hook up to their child views, directly nesting two gesture handlers using `Animated.event` is not currently supported. -To workaround this limitation we recommend placing an `` component in between the handlers. - -Instead of doing: - -```js -const PanAndRotate = () => ( - - - - - -); -``` - -Place an `` in between the handlers: - -```js -const PanAndRotate = () => ( - - - - - - - -); -``` - -Another consequence of handlers depending on their native child components is that when using a `useNativeDriver` flag with an `Animated.event`, the child component must be wrapped by an `Animated.API` e.g. `` instead of just a ``: - -```js -class Draggable extends Component { - render() { - return ( - - {/* <-- NEEDS TO BE Animated.View */} - - ); - } -}; -``` diff --git a/docs/versioned_docs/version-2.0.0/gesture-handlers/basics/interactions.md b/docs/versioned_docs/version-2.0.0/gesture-handlers/basics/interactions.md deleted file mode 100644 index 762d0e96f9..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-handlers/basics/interactions.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -id: interactions -title: Cross handler interactions -sidebar_label: Cross handler interactions ---- - -Gesture handlers can "communicate" with each other to support complex gestures and control how they _[activate](./state.md#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. -Gesture handler relies on ref objects created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html) and introduced in [React 16.3](https://reactjs.org/blog/2018/03/29/react-v-16-3.html#createref-api). - -## Simultaneous recognition - -By default, only one gesture handler is allowed to be in the [`ACTIVE`](./state.md#active) state. -So when a gesture handler recognizes a gesture it [cancels](./state.md#cancelled) all other handlers in the [`BEGAN`](./state.md#began) state and prevents any new handlers from receiving a stream of touch events as long as it remains [`ACTIVE`](./state.md#active). - -This behavior can be altered using the [`simultaneousHandlers`](../api/common-gh.md#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`](./state.md#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`](../api/pinch-gh.md), [`RotationGestureHandler`](../api/rotation-gh.md) and [`PanGestureHandler`](../api/pan-gh.md) that would have to simultaneously recognize gestures. - -### Example - -See the ["Scale, rotate & tilt" example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from the [GestureHandler Example App](../../example.md) or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -class PinchableBox extends React.Component { - // ...take a look on full implementation in an Example app - render() { - const imagePinch = React.createRef(); - const imageRotation = React.createRef(); - return ( - - - - - - - - - - ); - } -} -``` - -## Awaiting other handlers - -### Use cases - -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](./state.md#cancelled) the double tap handler. - -### Example - -See the ["Multitap" example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from [GestureHandler Example App](../../example.md) or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -const doubleTap = React.createRef(); -const PressBox = () => ( - - nativeEvent.state === State.ACTIVE && Alert.alert('Single tap!') - } - waitFor={doubleTap}> - - nativeEvent.state === State.ACTIVE && Alert.alert("You're so fast") - } - numberOfTaps={2}> - - - -); -``` diff --git a/docs/versioned_docs/version-2.0.0/gesture-handlers/basics/state.md b/docs/versioned_docs/version-2.0.0/gesture-handlers/basics/state.md deleted file mode 100644 index 1f15f94f2f..0000000000 --- a/docs/versioned_docs/version-2.0.0/gesture-handlers/basics/state.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: state -title: Handler State -sidebar_label: Handler State ---- - -As described in ["About Gesture Handlers"](./about-handlers.md), 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: - -- [UNDETERMINED](#undetermined) -- [FAILED](#failed) -- [BEGAN](#began) -- [CANCELLED](#cancelled) -- [ACTIVE](#active) -- [END](#end) - -Each state has its own description below. - -## Accessing state - -We can monitor a handler's state changes by using the [`onHandlerStateChange`](../api/common-gh.md#onhandlerstatechange) callback and the destructured `nativeEvent` argument passed to it. -This can be done by comparing the `nativeEvent`'s [`state`](../api/common-gh.md#state) attribute to one of the constants exported under the `State` object (see example below). - -``` -import { State, LongPressGestureHandler } from 'react-native-gesture-handler'; - -class Demo extends Component { - _handleStateChange = ({ nativeEvent }) => { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert('Longpress'); - } - }; - render() { - return ( - - Longpress me - - ); - } -} -``` - -## State flows - -The most typical flow of state is when a gesture handler picks up on an initial touch event then recognizes it then acknowledges its ending then resets itself back to the initial state. - -The flow looks as follows (longer arrows represent that there are possibly more touch events received before the state changes): - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`END`](#end) -> [`UNDETERMINED`](#undetermined) - -Another possible flow is when a handler receives touches that cause a recognition failure: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`FAILED`](#failed) -> [`UNDETERMINED`](#undetermined) - -At last, when a handler does properly recognize the gesture but then is interrupted by the touch system. In that case, the gesture recognition is canceled and the flow looks as follows: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`CANCELLED`](#cancelled) -> [`UNDETERMINED`](#undetermined) - -## States - -The section below describes all possible handler states: - -### UNDETERMINED - -This is the initial state of each handler and it goes into this state after it's done recognizing a gesture. - -### FAILED - -A handler 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 handler won't become active but will fail instead. Afterwards, it's state will be reset to `UNDETERMINED`. - -### BEGAN - -Handler 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 - -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](about-handlers#discrete-vs-continuous) to understand how long a handler can be kept in the `ACTIVE` state. - -### END - -The gesture recognizer has received touches signalling the end of a gesture. Its state will become `END` until it is reset to `UNDETERMINED`. diff --git a/docs/versioned_docs/version-2.0.0/introduction.md b/docs/versioned_docs/version-2.0.0/introduction.md deleted file mode 100644 index 14545fc100..0000000000 --- a/docs/versioned_docs/version-2.0.0/introduction.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -id: introduction -title: Introduction -sidebar_label: Introduction -slug: / ---- - -Gesture Handler aims to replace React Native's built in touch system called [Gesture Responder System](http://facebook.github.io/react-native/docs/gesture-responder-system). - -The motivation for building this library was to address the performance limitations of React Native's Gesture Responder System and to provide more control over the built-in native components that can handle gestures. -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. - -In a nutshell, the library provides: - -- A way to use a platform's native touch handling system for recognizing pinch, rotation and pan (besides a few other gestures). -- The ability to define relations between gesture handlers, e.g. when you have a pan handler in `ScrollView` you can make that `ScrollView` wait until it knows pan won't recognize. -- Mechanisms to use touchables 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. - -:::info -It is recommended to use Reanimated 2 for animations when using React Native Gesture Handler as its more advanced features rely heavily on the worklets provided by Reanimated. -::: - -## Installation - -### Requirements - -| version | `react-native` version | -| --------- | ---------------------- | -| 2.0.0+ | 0.63.0+ | -| 1.4.0+ | 0.60.0+ | -| 1.1.0+ | 0.57.2+ | -| <1.1.0 | 0.50.0+ | - -It may be possible to use newer versions of react-native-gesture-handler on React Native with version <= 0.59 by reverse Jetifying. -Read more on that here https://github.com/mikehardy/jetifier#to-reverse-jetify--convert-node_modules-dependencies-to-support-libraries - -Note that if you wish to use [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html) support for [interactions](./gesture-handlers/basics/interactions.md) you need to use v16.3 of [React](https://reactjs.org/) - -In order to fully utilize the [touch events](./api/gestures/touch-events.md) you also need to use `react-native-reanimated` 2.3.0-beta.4 or newer. - -### Expo - -#### Managed [Expo](https://expo.io) - -To use the version of react-native-gesture-handler that is compatible with your managed Expo project, run `expo install react-native-gesture-handler`. - -The Expo SDK incorporates the latest version of react-native-gesture-handler available at the time of each SDK release, so managed Expo apps might not always support all our latest features as soon as they are available. - -#### Bare [React Native](http://facebook.github.io/react-native/) - -Since the library uses native support for handling gestures, it requires an extended installation to the norm. If you are starting a new project, you may want to initialize it with [expo-cli](https://docs.expo.io/versions/latest/workflow/expo-cli/) and use a bare template, they come pre-installed with react-native-gesture-handler. - -### JS - -First, install the library using `yarn`: - -```bash -yarn add react-native-gesture-handler -``` - -or with `npm` if you prefer: - -```bash -npm install --save react-native-gesture-handler -``` - -After installation, wrap your entry point with `` or -`gestureHandlerRootHOC`. - -For example: - -```js -export default function App() { - return {/* content */}; -} -``` - -:::info -If you use props such as `shouldCancelWhenOutside`, `simultaneousHandlers`, `waitFor` etc. with gesture handlers, the handlers need to be mounted under a single `GestureHandlerRootView`. So it's important to keep the `GestureHandlerRootView` as close to the actual root view as possible. - -Note that `GestureHandlerRootView` acts like a normal `View`. So if you want it to fill the screen, you will need to pass `{ flex: 1 }` like you'll need to do with a normal `View`. By default, it'll take the size of the content nested inside. -::: - -:::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. -::: - -#### Linking - -> **Important**: You only need to do this step if you're using React Native 0.59 or lower. Since v0.60, linking happens automatically. - -```bash -react-native link react-native-gesture-handler -``` - -### Android - -#### Usage with modals on Android - -On Android RNGH does not work by default because modals are not located under React Native Root view in native hierarchy. -To fix that, components need to be wrapped with `gestureHandlerRootHOC` (it's no-op on iOS and web). - -For example: - -```js -const ExampleWithHoc = gestureHandlerRootHOC(() => ( - - - - ); -); - -export default function Example() { - return ( - - - - ); -} -``` - -#### Kotlin - -Since version `2.0.0` RNGH has been rewritten with Kotlin. The default version of the Kotlin plugin used in this library is `1.5.20`. - -If you need to use a different Kotlin version, set the `kotlinVersion` ext property in `android/build.gradle` file and RNGH will use that version: - -``` -buildscript { - ext { - ... - kotlinVersion = "1.5.20" - } -} -``` - -The minimal version of the Kotlin plugin supported by RNGH is `1.4.10`. - -### iOS - -There is no additional configuration required on iOS except what follows in the next steps. - -If you're in a CocoaPods project (the default setup since React Native 0.60), -make sure to install pods before you run your app: - -```bash -cd ios && pod install -``` - -For React Native 0.61 or greater, add the library as the first import in your index.js file: - -```js -import 'react-native-gesture-handler'; -``` - -### Testing - -In order to load mocks provided by the library add following to your jest config in `package.json`: - -```json -"setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"] -``` - -Example: - -```json -"jest": { - "preset": "react-native", - "setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"] -} -``` diff --git a/docs/versioned_docs/version-2.0.0/manual-gestures/manual-gestures.md b/docs/versioned_docs/version-2.0.0/manual-gestures/manual-gestures.md deleted file mode 100644 index eae7fffd2d..0000000000 --- a/docs/versioned_docs/version-2.0.0/manual-gestures/manual-gestures.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -id: manual-gestures -title: Manual gestures -sidebar_label: Manual gestures ---- - -import Step, { Divider } from '@site/src/theme/Step'; -import Step1 from './step1.md'; -import Step2 from './step2.md'; -import Step3 from './step3.md'; -import Step4 from './step4.md'; -import Step5 from './step5.md'; -import Step6 from './step6.md'; -import Step7 from './step7.md'; - -RNGH2 finally brings one of the most requested features: manual gestures and touch events. To demonstrate how to make a manual gesture we will make a simple one that tracks all pointers on the screen. - - - - - First, we need a way to store information about the pointer: whether it should be visible and its position. - - - - - - - We also need a component to mark where a pointer is. In order to accomplish that we will make a component that accepts two shared values: one holding information about the pointer using the interface we just created, the other holding a bool indicating whether the gesture has activated. - In this example when the gesture is not active, the ball representing it will be blue and when it is active the ball will be red and slightly bigger. - - - - - - - Now we have to make a component that will handle the gesture and draw all the pointer indicators. We will store data about pointers in an array of size 12 as that is the maximum number of touches that RNGH will track, and render them inside an Animated.View. - - - - - - - We have our components set up and we can finally get to making the gesture! We will start with onTouchesDown where we need to set position of the pointers and make them visible. We can get this information from the touches property of the event. In this case we will also check how many pointers are on the screen and activate the gesture if there are at least two. - - - - - - - Next, we will handle pointer movement. In onTouchesMove we will simply update the position of moved pointers. - - - - - - - We also need to handle lifting fingers from the screen, which corresponds to onTouchesUp. Here we will just hide the pointers that were lifted and end the gesture if there are no more pointers on the screen. - Note that we are not handling onTouchesCancelled as in this very basic case we don't expect it to happen, however you should clear data about cancelled pointers (most of the time all active ones) when it is called. - - - - - - - Now that our pointers are being tracked correctly and we have the state management, we can handle activation and ending of the gesture. In our case, we will simply set the active shared value either to true or false. - - - - - -And that's all! As you can see using manual gestures is really easy but as you can imagine, manual gestures are a powerful tool that makes it possible to accomplish things that were previously impossible with RNGH. - -## Modifying existing gestures - -While manual gestures open great possibilities we are aware that reimplementing pinch or rotation from scratch just because you need to activate in specific circumstances or require position of the fingers, would be a waste of time as those gestures are already there. Because of that you can use touch events with every gesture so that you can extract more informations about gesture than is sent to you in events. We also added a `manualActivation` modifier on all continous gestures, which prevents the gesture it is applied to from activating by itself thus giving you full control of its behavior. - -This functionality makes another highly requested feature possible: drag after long press. Simply set `manualActivation` to `true` on a `PanGesture` and use `StateManager` to fail the gesture if the user attempts to drag the component sooner than the duration of the long press. diff --git a/docs/versioned_docs/version-2.0.0/manual-gestures/step1.md b/docs/versioned_docs/version-2.0.0/manual-gestures/step1.md deleted file mode 100644 index 4c6331c1c8..0000000000 --- a/docs/versioned_docs/version-2.0.0/manual-gestures/step1.md +++ /dev/null @@ -1,7 +0,0 @@ -```jsx -interface Pointer { - visible: boolean; - x: number; - y: number; -} -``` diff --git a/docs/versioned_docs/version-2.0.0/manual-gestures/step2.md b/docs/versioned_docs/version-2.0.0/manual-gestures/step2.md deleted file mode 100644 index 3137d334ef..0000000000 --- a/docs/versioned_docs/version-2.0.0/manual-gestures/step2.md +++ /dev/null @@ -1,35 +0,0 @@ -```jsx -function PointerElement(props: { - pointer: Animated.SharedValue, - active: Animated.SharedValue, -}) { - const animatedStyle = useAnimatedStyle(() => ({ - transform: [ - { translateX: props.pointer.value.x }, - { translateY: props.pointer.value.y }, - { - scale: - (props.pointer.value.visible ? 1 : 0) * - (props.active.value ? 1.3 : 1), - }, - ], - backgroundColor: props.active.value ? 'red' : 'blue', - })); - - return ; -} - -... - -const styles = StyleSheet.create({ - pointer: { - width: 60, - height: 60, - borderRadius: 30, - backgroundColor: 'red', - position: 'absolute', - marginStart: -30, - marginTop: -30, - }, -}); -``` diff --git a/docs/versioned_docs/version-2.0.0/manual-gestures/step3.md b/docs/versioned_docs/version-2.0.0/manual-gestures/step3.md deleted file mode 100644 index c9b32e5c2a..0000000000 --- a/docs/versioned_docs/version-2.0.0/manual-gestures/step3.md +++ /dev/null @@ -1,29 +0,0 @@ -```jsx -export default function Example() { - const trackedPointers: Animated.SharedValue[] = []; - const active = useSharedValue(false); - - for (let i = 0; i < 12; i++) { - trackedPointers[i] = - useSharedValue < - Pointer > - { - visible: false, - x: 0, - y: 0, - }; - } - - const gesture = Gesture.Manual(); - - return ( - - - {trackedPointers.map((pointer, index) => ( - - ))} - - - ); -} -``` diff --git a/docs/versioned_docs/version-2.0.0/manual-gestures/step4.md b/docs/versioned_docs/version-2.0.0/manual-gestures/step4.md deleted file mode 100644 index 36ec2c34bd..0000000000 --- a/docs/versioned_docs/version-2.0.0/manual-gestures/step4.md +++ /dev/null @@ -1,15 +0,0 @@ -```jsx {2-15} -const gesture = Gesture.Manual().onTouchesDown((e, manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: true, - x: touch.x, - y: touch.y, - }; - } - - if (e.numberOfTouches >= 2) { - manager.activate(); - } -}); -``` diff --git a/docs/versioned_docs/version-2.0.0/manual-gestures/step5.md b/docs/versioned_docs/version-2.0.0/manual-gestures/step5.md deleted file mode 100644 index d2f9377cc8..0000000000 --- a/docs/versioned_docs/version-2.0.0/manual-gestures/step5.md +++ /dev/null @@ -1,13 +0,0 @@ -```jsx {3-12} -const gesture = Gesture.Manual() - ... - .onTouchesMove((e, _manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: true, - x: touch.x, - y: touch.y, - }; - } - }) -``` diff --git a/docs/versioned_docs/version-2.0.0/manual-gestures/step6.md b/docs/versioned_docs/version-2.0.0/manual-gestures/step6.md deleted file mode 100644 index 323f9516cb..0000000000 --- a/docs/versioned_docs/version-2.0.0/manual-gestures/step6.md +++ /dev/null @@ -1,17 +0,0 @@ -```jsx {3-16} -const gesture = Gesture.Manual() - ... - .onTouchesUp((e, manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: false, - x: touch.x, - y: touch.y, - }; - } - - if (e.numberOfTouches === 0) { - manager.end(); - } - }) -``` diff --git a/docs/versioned_docs/version-2.0.0/manual-gestures/step7.md b/docs/versioned_docs/version-2.0.0/manual-gestures/step7.md deleted file mode 100644 index 913e766ae8..0000000000 --- a/docs/versioned_docs/version-2.0.0/manual-gestures/step7.md +++ /dev/null @@ -1,10 +0,0 @@ -```jsx {3-10} -const gesture = Gesture.Manual() - ... - .onStart(() => { - active.value = true; - }) - .onEnd(() => { - active.value = false; - }); -``` diff --git a/docs/versioned_docs/version-2.0.0/quickstart/quickstart.md b/docs/versioned_docs/version-2.0.0/quickstart/quickstart.md deleted file mode 100644 index c1ba3d7219..0000000000 --- a/docs/versioned_docs/version-2.0.0/quickstart/quickstart.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -id: quickstart -title: Quick start -sidebar_label: Quick start ---- - -import Step, { Divider } from '@site/src/theme/Step'; -import Step1 from './step1.md'; -import Step2 from './step2.md'; -import Step3 from './step3.md'; -import Step4 from './step4.md'; -import Step5 from './step5.md'; - -RNGH2 provides much simpler way to add gestures to your app. All you need to do is wrap the view that you want your gesture to work on with [`GestureDetector`](../api/gestures/gesture-detector), define the gesture and pass it to detector. That's all! - -To demonstrate how you would use the new API, let's make a simple app where you can drag a ball around. You will need to add `react-native-gesture-handler` (for gestures) and `react-native-reanimated` (for animations) modules. - - - - -
First let's define styles we will need to make the app:
- - - - - - -
Then we can start writing our `Ball` component:
- - - - - - -
- We also need to define{' '} - - shared values - {' '} - to keep track of the ball position and create animated styles in order to be - able to position the ball on the screen: -
- - - - - - -
And add it to the ball's styles:
- - - - - - -
- The only thing left is to define the pan gesture and assign it to the - detector: -
- - - - - -Note the `start` shared value. We need it to store the position of the ball at the moment we grab it to be able to correctly position it later, because we only have access to translation relative to the starting point of the gesture. - -Now you can just add `Ball` component to some view in the app and see the results! (Or you can just check the code [here](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/new_api/reanimated/index.tsx) and see it in action in the Example app.) diff --git a/docs/versioned_docs/version-2.0.0/quickstart/step1.md b/docs/versioned_docs/version-2.0.0/quickstart/step1.md deleted file mode 100644 index 1995cd907c..0000000000 --- a/docs/versioned_docs/version-2.0.0/quickstart/step1.md +++ /dev/null @@ -1,11 +0,0 @@ -```jsx -const styles = StyleSheet.create({ - ball: { - width: 100, - height: 100, - borderRadius: 100, - backgroundColor: 'blue', - alignSelf: 'center', - }, -}); -``` diff --git a/docs/versioned_docs/version-2.0.0/quickstart/step3.md b/docs/versioned_docs/version-2.0.0/quickstart/step3.md deleted file mode 100644 index ee7184ffc7..0000000000 --- a/docs/versioned_docs/version-2.0.0/quickstart/step3.md +++ /dev/null @@ -1,14 +0,0 @@ -```jsx -const isPressed = useSharedValue(false); -const offset = useSharedValue({ x: 0, y: 0 }); -const animatedStyles = useAnimatedStyle(() => { - return { - transform: [ - { translateX: offset.value.x }, - { translateY: offset.value.y }, - { scale: withSpring(isPressed.value ? 1.2 : 1) }, - ], - backgroundColor: isPressed.value ? 'yellow' : 'blue', - }; -}); -``` diff --git a/docs/versioned_docs/version-2.0.0/quickstart/step5.md b/docs/versioned_docs/version-2.0.0/quickstart/step5.md deleted file mode 100644 index c7c2e07265..0000000000 --- a/docs/versioned_docs/version-2.0.0/quickstart/step5.md +++ /dev/null @@ -1,32 +0,0 @@ -```jsx -const start = useSharedValue({ x: 0, y: 0 }); -const gesture = Gesture.Pan() - .onBegin(() => { - isPressed.value = 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, - }; - }) - .onFinalize(() => { - isPressed.value = false; - }); -``` - -```jsx {3} -... -return ( - - - -); -... -``` diff --git a/docs/versioned_docs/version-2.0.0/resources.md b/docs/versioned_docs/version-2.0.0/resources.md deleted file mode 100644 index eff7378934..0000000000 --- a/docs/versioned_docs/version-2.0.0/resources.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -id: resources -title: Learning Resources ---- - -## Apps - -[Gesture Handler Example App](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example) – official gesture handler "showcase" app. - -[Gesture Handler Example on Expo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo) – the official app you can install and play with using [Expo](https://expo.io). - -## 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 Vetne](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. diff --git a/docs/versioned_docs/version-2.0.0/troubleshooting.md b/docs/versioned_docs/version-2.0.0/troubleshooting.md deleted file mode 100644 index 2bc94e0f90..0000000000 --- a/docs/versioned_docs/version-2.0.0/troubleshooting.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -id: troubleshooting -title: Troubleshooting ---- - -## Troubleshooting - -Thanks for giving this library a try! We are sorry that you might have encountered issues though. Here is how you can seek help: - -1. Search over the [issues on Github](https://github.com/software-mansion/react-native-gesture-handler/issues). There is a chance someone had this problem in the past and it has been resolved! - -2. When sure your problem hasn't been reported or was reported but the proposed solution doesn't work for you please follow [our issue reporting guidelines](#reporting-issues). - -3. You can try seeking help on [Expo Developers Slack channel](https://slack.expo.io/) where we often hang out. - -4. If you feel like reading the source code I highly recommend it, as this is by far the best resource and gives you the most up to date insights into how the library works and what might be causing the bug. - -5. If you managed to find the solution consider [contributing](contributing.md) a fix or update our documentation to make this information easier to find for the others in the future. - -## Reporting issues - -This library is maintained by a very small team. -Please be mindful of that when reporting issue and when it happens that we can't get back to you as soon as you might expect. -We would love to fix all the problems as soon as possible, but often our time is constraint with other issues/features or projects. -To make it easier for us to understand your issue and to be able to approach it sooner you can help by: - -- Making sure the issue description is complete. Please include all the details about your environment (library version, RN version, device OS etc). -- It is the best to provide an example app that reproduces the issue you are having. Put it up on [gist](https://gist.github.com/), [snack](https://snack.expo.io) or create a repo on Github – it doesn't matter as long as we can easily pull it in, run and see the issue. -- Explain how you run your repro app and what steps to take to reproduce the issue. -- Isolate your issue from other dependencies you might be using and make the repro app as minimal as possible. -- If you have spent some time figuring out the root cause of the problem you can leave a note about your findings so far. -- **Do not comment on closed issues**. It is very unlikely that we are going to notice your comment in such a case. If the issue has been closed, but the proposed solution doesn't work for you, please open a new one providing all the information necessary and linking to the solution you have tried. - -## It's not a bug, it's a feature - -- Changing `enabled` prop during a gesture has no effect, only when a gesture starts (that is a finger touches the screen) the `enabled` prop is taken into consideration to decide whether to extract (or not) the gesture and provide it with stream of events to analyze. -- `Native` gesture may not conform to the standard state flow due to platform specific workarounds to incorporate native views into RNGH. -- Keep in mind that `Touchables` from RNGH are rendering two additional views that may need to be styled separately to achieve desired effect (`style` and `containerStyle` props). -- In order for the gesture composition to work, all composed gestures must be attached to the same `GestureHandlerRootView`. diff --git a/docs/versioned_docs/version-2.0.0/under-the-hood/how-does-it-work.md b/docs/versioned_docs/version-2.0.0/under-the-hood/how-does-it-work.md deleted file mode 100644 index aebed78316..0000000000 --- a/docs/versioned_docs/version-2.0.0/under-the-hood/how-does-it-work.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -id: how-does-it-work -title: How does it work? -sidebar_label: How does it work? ---- - -### Units - -All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". -These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://facebook.github.io/react-native/docs/flexbox.html)). -They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. - -## iOS - -All gestures are implemented using [UIGestureRecognizers](https://developer.apple.com/documentation/uikit/uigesturerecognizer?language=objc), some of them have been slightly modified to allow for more customization and to conform to the state flow of RNGH. When you assign a gesture configuration to the `GestureDetector`, it creates all the required recognizers and assigns them to the child view of the detector. From this point most of the heavy lifting is handled by the [UIKit](https://developer.apple.com/documentation/uikit?language=objc) (with our help to correctly implement interactions between gestures). - -## Android - -Unfortunately, Android doesn't provide an easy way of handling gestures hence most of them were implemented from scratch, including a system for managing how the gestures should interact with each other. Here's a quick overview of how it works: -When you wrap a component with `GestureHandlerRootView` it allows for the RNGH to intercept all touch events on that component and process them, deciding whether they should be handled by one of the gesture handlers or passed to the underlying view. Gesture handlers are created when you assign a gesture configuration to the `GestureDetector`, it initializes all of the necessary handlers natively. Every `GestureHandlerRootView` also has a specific handler to decide whether to pass the touch events or to consume them. It can never activate, only begin, end or be cancelled. When this handler is in the `UNDETERMINED` state it means that there is no touch in progress, however when the touch starts it transitions to the `BEGAN` state. As long as it stays in that state, no touch event is consumed, but as soon as it gets cancelled (meaning that some handler has activated) all incoming touch events get consumed, preventing underlying view from receiving them. - -When a pointer touches the screen the view tree is traversed in order to extract all handlers attached to the views below the finger (including the one attached to the `GestureHandlerRootView`) and all extracted handlers transition to the `BEGAN` state, signalling that the gesture may heve began. The touch events continue to be delivered to all extracted handlers until one of them recognizes the gesture and tries to activate. At this point the orchestrator checks whether this gesture should wait for any other of the extracted gestures to fail. If it does, it's put to the waiting list, if it doesn't, it gets activated and all other gestures (that are not simultaneous with it) get cancelled. When a gesture handlers transitions to a finished state (the gesture recognized by it stops, it fails or gets cancelled) the orchestrator check the waiting handlers. Every one of them that waited for the gesture that just failed tries to activate again (and again the orchestrator checks if it should wait for any of the extracted gestures...). diff --git a/docs/versioned_docs/version-2.0.0/under-the-hood/states-events.md b/docs/versioned_docs/version-2.0.0/under-the-hood/states-events.md deleted file mode 100644 index 600f16a5cc..0000000000 --- a/docs/versioned_docs/version-2.0.0/under-the-hood/states-events.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -id: states-events -title: Gesture states & events -sidebar_label: Gesture states & events ---- - -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 (longer arrows represent that there are possibly more touch events received before the state changes): - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`END`](#end) -> [`UNDETERMINED`](#undetermined) - -Another possible flow is when a handler receives touches that cause a recognition failure: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`FAILED`](#failed) -> [`UNDETERMINED`](#undetermined) - -At last, when a handler does properly recognize the gesture but then is interrupted by the touch system the gesture recognition is canceled and the flow looks as follows: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`CANCELLED`](#cancelled) -> [`UNDETERMINED`](#undetermined) - -## 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. - -### `onPointerChange` - -Is called before `onPointerDown`, `onPointerMove`, `onPointerUp` and `onPointerCancelled` with the same event, which may be useful in case you share logic between them. It may carry information about more than one pointer because the events are batched. diff --git a/docs/versioned_docs/version-2.0.0/whats-new.md b/docs/versioned_docs/version-2.0.0/whats-new.md deleted file mode 100644 index ffafefa857..0000000000 --- a/docs/versioned_docs/version-2.0.0/whats-new.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -id: whats-new -title: What's new in 2.0 -sidebar_label: What's new in 2.0 ---- - -RNGH2 introduces a new way of creating gestures. Instead of creating a gesture handler component for every gesture you want to create, you just need to create a `GestureDetector` component and assign to it all the gestures you want it to recognize. It is also designed to work seamlessly with `Reanimated 2` and it will automatically detect if it is installed, and start using it if it is. -You can create gestures using the `Gesture` object and methods it provides, and configure them in the builder-like pattern. If you want to specify behavior between the gestures instead of using `waitFor` and `simultaneousGestures` you can use the new system of [gesture composition](./gesture-composition). -Along the new API, version 2.0 brings one of the most requested features: [touch events and manual gestures](manual-gestures). Thanks to great work done by the Reanimated team, we were able to provide synchronous communication between gestures and their native implementation using worklets. This allows to manage gesture state from the JS without risking race-conditions. - -### Interoperability with gesture handlers - -The new API with gestures is somewhat compatible with the old gesture handlers. Unfortunately you cannot use the new gesture composing with gesture handlers, however you can still mark relations using refs. If you want to make a gesture handler wait for (or simultaneous with) a gesture, simply use withRef method on the gesture to set the ref object and pass it to the appropriate property on the gesture handler. - -Similarly, if you want to make a gesture simultaneous with (or wait for failure of) a gesture handler, set the ref prop of the gesture handler and pass the same ref to the simultaneousWithExternalGesture or requireExternalGestureToFail method on the gesture object. - -This should allow you to migrate your codebase from the gesture handlers to gestures smoothly and at your own pace. Just keep in mind that the gesture handlers cannot have the GestureDetector as their direct child, as it's a functional component. diff --git a/docs/versioned_docs/version-2.1.1/api/components/buttons.mdx b/docs/versioned_docs/version-2.1.1/api/components/buttons.mdx deleted file mode 100644 index ac8657a5eb..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/components/buttons.mdx +++ /dev/null @@ -1,170 +0,0 @@ ---- -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` -- `RectButton` -- `BorderlessButton` - -On top of that all the buttons are wrapped with `NativeViewGestureHandler` and therefore allow for all the [common gesture handler properties](#common-gesturehandler-properties) and `NativeViewGestureHandler`'s [extra properties](#nativeviewgesturehandler-extra-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). - -### `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`. - -## `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`](#basebutton-component), 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`](#basebutton-component), 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/docs/versioned_docs/version-2.1.1/api/components/drawer-layout.mdx b/docs/versioned_docs/version-2.1.1/api/components/drawer-layout.mdx deleted file mode 100644 index b3e4373d1e..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/components/drawer-layout.mdx +++ /dev/null @@ -1,147 +0,0 @@ ---- -id: drawer-layout -title: Drawer Layout -sidebar_label: DrawerLayout ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import GifGallery from '@site/components/GifGallery'; - -This is a cross-platform replacement for React Native's [DrawerLayoutAndroid](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) component. It provides a compatible API but allows for the component to be used on both Android and iOS. Please refer to [React Native docs](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) for the detailed usage for standard parameters. - -## Usage: - -`DrawerLayout` component isn't exported by default from the `react-native-gesture-handler` package. To use it, import it in the following way: - -```js -import DrawerLayout from 'react-native-gesture-handler/DrawerLayout'; -``` - -## Properties: - -On top of the standard list of parameters DrawerLayout has an additional set of attributes to customize its behavior. Please refer to the list below: - -### `drawerType` - -possible values are: `front`, `back` or `slide` (default is `front`). It specifies the way the drawer will be displayed. When set to `front` the drawer will slide in and out along with the gesture and will display on top of the content view. When `back` is used the drawer displays behind the content view and can be revealed with gesture of pulling the content view to the side. Finally `slide` option makes the drawer appear like it is attached to the side of the content view; when you pull both content view and drawer will follow the gesture. - -Type `slide`: - - - - - -Type `front`: - - - - - -Type `back`: - - - - - -### `edgeWidth` - -number, allows for defining how far from the edge of the content view the gesture should activate. - -### `hideStatusBar` - -boolean, when set to `true` Drawer component will use [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html) API to hide the OS status bar whenever the drawer is pulled or when its in an "open" state. - -### `statusBarAnimation` - -possible values are: `slide`, `none` or `fade` (defaults to `slide`). Can be used when `hideStatusBar` is set to `true` and will select the animation used for hiding/showing the status bar. See [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html#statusbaranimation) documentation for more details. - -### `overlayColor` - -color (default to `"black"`) of a semi-transparent overlay to be displayed on top of the content view when drawer gets open. A solid color should be used as the opacity is added by the Drawer itself and the opacity of the overlay is animated (from 0% to 70%). - -### `renderNavigationView` - -function. This attribute is present in the standard implementation already and is one of the required params. Gesture handler version of DrawerLayout make it possible for the function passed as `renderNavigationView` to take an Animated value as a parameter that indicates the progress of drawer opening/closing animation (progress value is 0 when closed and 1 when opened). This can be used by the drawer component to animated its children while the drawer is opening or closing. - -### `onDrawerClose` - -function. This function is called when the drawer is closed. - -### `onDrawerOpen` - -function. This function is called when the drawer is opened. - -### `onDrawerSlide` - -function. This function is called as a drawer sliding open from touch events. The progress of the drawer opening/closing is passed back as 0 when closed and 1 when opened. - -### `onDrawerStateChanged` - -function. This function is called when the status of the drawer changes. Possible values that can be passed back are: 'Idle', 'Dragging', and 'Settling'. - -### `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` - -component or function. Children is a component which is rendered by default and is wrapped by drawer. However, it could be also a render function which takes an Animated value as a parameter that indicates the progress of drawer opening/closing animation (progress value is 0 when closed and 1 when opened) is the same way like `renderNavigationView` prop. - -## Methods - -### `openDrawer(options)` - -`openDrawer` can take an optional `options` parameter which is an object, enabling further customization of the open animation. - -`options` has two optional properties: - -`velocity`: number, the initial velocity of the object attached to the spring. Default 0 (object is at rest). -`speed`: number, controls speed of the animation. Default 12. - -### `closeDrawer(options)` - -`closeDrawer` can take an optional `options` parameter which is an object, enabling further customization of the close animation. - -`options` has two optional properties: - -`velocity`: number, the initial velocity of the object attached to the spring. Default 0 (object is at rest). -`speed`: number, controls speed of the animation. Default 12. - -## Example: - -See the [drawer example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/horizontalDrawer/index.tsx) from [GestureHandler Example App](example.md) or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -class Drawerable extends Component { - handleDrawerSlide = (status) => { - // outputs a value between 0 and 1 - console.log(status); - }; - - renderDrawer = () => { - return ( - - I am in the drawer! - - ); - }; - - render() { - return ( - - - - Hello, it's me - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.1.1/api/components/swipeable.md b/docs/versioned_docs/version-2.1.1/api/components/swipeable.md deleted file mode 100644 index bf49f033ed..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/components/swipeable.md +++ /dev/null @@ -1,170 +0,0 @@ ---- -id: swipeable -title: Swipeable -sidebar_label: Swipeable ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import GifGallery from '@site/components/GifGallery' - - - - - -This component 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: - -Similarly to the `DrawerLayout`, `Swipeable` component isn't exported by default from the `react-native-gesture-handler` package. To use it, import it in the following way: - -```js -import Swipeable from 'react-native-gesture-handler/Swipeable'; -``` - -## 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. - -### `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 method 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 method 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. - -### `onSwipeableLeftOpen` - -method that is called when left action panel gets open. - -### `onSwipeableRightOpen` - -method that is called when right action panel gets open. - -### `onSwipeableOpen` - -method that is called when action panel gets open (either right or left). - -### `onSwipeableClose` - -method that is called when action panel is closed. - -### `onSwipeableLeftWillOpen` - -method that is called when left action panel starts animating on open. - -### `onSwipeableRightWillOpen` - -method that is called when right action panel starts animating on open. - -### `onSwipeableWillOpen` - -method that is called when action panel starts animating on open (either right or left). - -### `onSwipeableWillClose` - -method that is called when action panel starts animating on close. - -### `renderLeftActions` - -method that is expected to return an action panel that is going to be revealed from the left side when user swipes right. -This map describes the values to use as inputRange for extra interpolation: -AnimatedValue: [startValue, endValue] - -progressAnimatedValue: [0, 1] -dragAnimatedValue: [0, +] - -To support `rtl` flexbox layouts use `flexDirection` styling. - -### `renderRightActions` - -method that is expected to return an action panel that is going to be revealed from the right side when user swipes left. -This map describes the values to use as inputRange for extra interpolation: -AnimatedValue: [startValue, endValue] - -progressAnimatedValue: [0, 1] -dragAnimatedValue: [0, -] - -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`. - -### `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. - -## Methods - -Using reference to `Swipeable` it's possible to trigger some actions on it - -### `close` - -method that closes component. - -### `openLeft` - -method that opens component on left side. - -### `openRight` - -method that opens component on right side. - -### Example: - -See the [swipeable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/showcase/swipeable/index.tsx) from [GestureHandler Example App](example.md) or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -import React, { Component } from 'react'; -import { Animated, StyleSheet, View } from 'react-native'; -import { RectButton } from 'react-native-gesture-handler'; -import Swipeable from 'react-native-gesture-handler/Swipeable'; - -class AppleStyleSwipeableRow extends Component { - renderLeftActions = (progress, dragX) => { - const trans = dragX.interpolate({ - inputRange: [0, 50, 100, 101], - outputRange: [-20, 0, 0, 1], - }); - return ( - - - Archive - - - ); - }; - render() { - return ( - - "hello" - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.1.1/api/components/touchables.md b/docs/versioned_docs/version-2.1.1/api/components/touchables.md deleted file mode 100644 index dff1719b63..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/components/touchables.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -id: touchables -title: Touchables -sidebar_label: Touchables ---- - -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://facebook.github.io/react-native/docs/touchablenativefeedback) -- [Touchable Highlight](https://facebook.github.io/react-native/docs/touchablehighlight) -- [Touchable Opacity](https://facebook.github.io/react-native/docs/touchableopacity) -- [Touchable Without Feedback](https://facebook.github.io/react-native/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. - -### 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/example/src/release_tests/touchables/index.tsx) diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/base-continous-gesture-config.md b/docs/versioned_docs/version-2.1.1/api/gestures/base-continous-gesture-config.md deleted file mode 100644 index a19473784e..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/base-continous-gesture-config.md +++ /dev/null @@ -1,5 +0,0 @@ -### Properties common to all continous gestures: - -### `manualActivation(value: boolead)` - -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](./state-manager.md). diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/base-gesture-callbacks.md b/docs/versioned_docs/version-2.1.1/api/gestures/base-gesture-callbacks.md deleted file mode 100644 index dff985b307..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/base-gesture-callbacks.md +++ /dev/null @@ -1,33 +0,0 @@ -### Callbacks common to all gestures: - -### `onBegin(callback)` - -Set the callback that is being called when given gesture handler starts receiving touches. At the moment of this callback the handler is not yet in an active state and we don't know yet if it will recognize the gesture at all. - -### `onStart(callback)` - -Set the callback that is being called when the gesture is recognized by the handler and it transitions to the active state. - -### `onEnd(callback)` - -Set the callback that is being called when the gesture that was recognized by the handler finishes. It will be called only if the handler was previously in the active state. - -### `onFinalize(callback)` - -Set the callback that is being called when the handler finalizes handling gesture - the gesture was recognized and has finished or it failed to recognize. - -### `onTouchesDown(callback)` - -Set the `onTouchesDown` callback which is called every time a finger is placed on the screen. - -### `onTouchesMove(callback)` - -Set the `onTouchesMove` callback which is called every time a finger is moved on the screen. - -### `onTouchesUp(callback)` - -Set the `onTouchesUp` callback which is called every time a finger is lifted from the screen. - -### `onTouchesCancelled(callback)` - -Set the `onTouchesCancelled` callback which is called every time a finger stops being tracked, for example when the gesture finishes. diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/base-gesture-config.md b/docs/versioned_docs/version-2.1.1/api/gestures/base-gesture-config.md deleted file mode 100644 index bcc364192b..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/base-gesture-config.md +++ /dev/null @@ -1,44 +0,0 @@ -### 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`](../../under-the-hood/states-events.md#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`](../../under-the-hood/states-events.md#failed) or [`CANCELLED`](../../under-the-hood/states-events.md#cancelled) (depending on its current state). -Default value is `true`. - -### `shouldCancelWhenOutside(value: boolean)` - -When `true` the handler will [cancel](../../under-the-hood/states-events.md#cancelled) or [fail](../../under-the-hood/states-events.md#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`](./long-press-gesture.md) and [`TapGesture`](./tap-gesture.md) which default to `true`. - -### `hitSlop(settings)` - -This parameter enables control over what part of the connected view area can be used to [begin](../../under-the-hood/states-events.md#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://facebook.github.io/react-native/docs/view.html#props) property. - -### `withRef(ref)` - -Sets a ref to the gesture object, allowing for interoperability with the old API. - -### `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](../../gesture-composition). [`GestureDetector`](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. - -**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](../../gesture-composition).[`GestureDetector`](gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/base-gesture-event-data.md b/docs/versioned_docs/version-2.1.1/api/gestures/base-gesture-event-data.md deleted file mode 100644 index 4d9056b1e5..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/base-gesture-event-data.md +++ /dev/null @@ -1,9 +0,0 @@ -### Event attributes common to all gestures: - -### `state` - -Current [state](.../../under-the-hood/states-events.md) 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. diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/composed-gestures.md b/docs/versioned_docs/version-2.1.1/api/gestures/composed-gestures.md deleted file mode 100644 index 84e2e451bd..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/composed-gestures.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: composed-gestures -title: Composed gestures -sidebar_label: Composed gestures ---- - -Composed gestures (`Race`, `Simultaneous`, `Exclusive`) provide a simple way of building relations between gestures. diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/fling-gesture.md b/docs/versioned_docs/version-2.1.1/api/gestures/fling-gesture.md deleted file mode 100644 index 09c2846276..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/fling-gesture.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -id: fling-gesture -title: Fling gesture -sidebar_label: Fling gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; - -A discrete gesture that activates when the movement is sufficiently long and fast. -Gesture gets [ACTIVE](../../under-the-hood/states-events.md#active) when movement is sufficiently long and it does not take too much time. -When gesture gets activated it will turn into [END](../../under-the-hood/states-events.md#end) state when finger is released. -The gesture will fail to recognize if the finger is lifted before being activated. - -## Config - -### Properties specific to `FlingGesture`: - -### `direction(value: Directions)` - -Expressed allowed direction of movement. Expected values are exported as constants in the `Directions` object. It's possible to pass one or many directions in one parameter: - -```js -fling.direction(Directions.RIGHT | Directions.LEFT); -``` - -or - -```js -fling.direction(Directions.DOWN); -``` - -### `numberOfPointers(value: number)` - -Determine exact number of points required to handle the fling gesture. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `FlingGesture`: - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - - - -## Example - -```jsx -const position = useSharedValue(0); - -const flingGesture = Gesture.Fling() - .direction(Directions.RIGHT) - .onStart((e) => { - position.value = withTiming(position.value + 10, { duration: 100 }); - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ translateX: position.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/gesture-detector-functional1.md b/docs/versioned_docs/version-2.1.1/api/gestures/gesture-detector-functional1.md deleted file mode 100644 index 2397af9dfa..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/gesture-detector-functional1.md +++ /dev/null @@ -1,19 +0,0 @@ -```jsx -export default function Example() { - const tap = Gesture.Tap().onStart(() => { - console.log('tap'); - }); - - return ( - - - - - - ); -} - -function FunctionalComponent(props) { - return {props.children}; -} -``` diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/gesture-detector.md b/docs/versioned_docs/version-2.1.1/api/gestures/gesture-detector.md deleted file mode 100644 index ef8af9b62c..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/gesture-detector.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -id: gesture-detector -title: GestureDetector -sidebar_label: Gesture detector ---- - -import FunctionalComponents from './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.x/). - -:::caution -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. -::: - -## 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 synchrously. - -Starting with Reanimated-2.3.0-beta.4 Gesture Handler will provide a [StateManager](./state-manager.md) in the [touch events](./touch-events.md) that allows for managing the state of the gesture. -::: diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/gesture.md b/docs/versioned_docs/version-2.1.1/api/gestures/gesture.md deleted file mode 100644 index a84a48003a..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/gesture.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -id: gesture -title: Gesture -sidebar_label: Gesture ---- - -`Gesture` is the object that allows you to create and compose gestures. - -### Gesture.Tap() - -Creates a new instance of [`TapGesture`](./tap-gesture.md) with its default config and no callbacks. - -### Gesture.Pan() - -Creates a new instance of [`PanGesture`](./pan-gesture.md) with its default config and no callbacks. - -### Gesture.LongPress() - -Creates a new instance of [`LongPressGesture`](./long-press-gesture.md) with its default config and no callbacks. - -### Gesture.Fling() - -Creates a new instance of [`FlingGesture`](./fling-gesture.md) with its default config and no callbacks. - -### Gesture.Pinch() - -Creates a new instance of [`PinchGesture`](./pinch-gesture.md) with its default config and no callbacks. - -### Gesture.Rotation() - -Creates a new instance of [`RotationGesture`](./rotation-gesture.md) with its default config and no callbacks. - -### Gesture.ForceTouch() - -Creates a new instance of [`ForceTouchGesture`](./force-touch-gesture.md) with its default config and no callbacks. - -### Gesture.Manual() - -Creates a new instance of [`ManualGesture`](./manual-gesture.md) with its default config and no callbacks. - -### Gesture.Native() - -Creates a new instance of [`NativeGesture`](./native-gesture.md) with its default config and no callbacks. - -### Gesture.Race(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. Only one of those can become active and there are no restrictions to the activation of the gesture. The first one to activate will cancel all the others. - -### Gesture.Simultaneous(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. All of them can become active without cancelling the others. - -### Gesture.Exclusive(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. Only one of them can become active, but the first one has a higher priority than the second one, the second one has a higher priority than the third one, and so on. When all gestures are in the `BEGAN` state and the activation criteria for the second one is met, instead of activating it will wait until the first one fails (and only then it will activate) or until the first one activates (and then the second one will get cancelled). It is useful when you want to compose gestures with similar activation criteria (e.g. single and double tap at the same component, without Exclusive the single tap would activate every time user taps thus cancelling the double tap). diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/long-press-gesture.md b/docs/versioned_docs/version-2.1.1/api/gestures/long-press-gesture.md deleted file mode 100644 index 9f174d58e7..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/long-press-gesture.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -id: long-press-gesture -title: Long press gesture -sidebar_label: Long press gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './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](../../under-the-hood/states-events.md#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](#mindurationms) or if the finger is moved further than the [allowable distance](#maxdist). - -## Config - -### Properties specific to `LongPressGesture`: - -### `minDuration(value: number)` - -Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. - -### `maxDistance(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. The default value is 10. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `LongPressGesture`: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `duration` - -Duration of the long press (time since the start of the gesture), expressed in milliseconds. - - - -## Example - -```jsx -const longPressGesture = Gesture.LongPress().onEnd((e, success) => { - if (success) { - Alert.alert(`Long pressed for ${e.duration} ms!`); - } -}); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/manual-gesture.md b/docs/versioned_docs/version-2.1.1/api/gestures/manual-gesture.md deleted file mode 100644 index a92c6986ef..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/manual-gesture.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -id: manual-gesture -title: Manual gesture -sidebar_label: Manual gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A plain gesture that has no specific activation criteria nor event data set. Its state has to be controlled manually using a [state manager](./state-manager.md). It will not fail when all the pointers are lifted from the screen. - -## Config - - - -## Callbacks - - - - -## Event data - - diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/pan-gesture.md b/docs/versioned_docs/version-2.1.1/api/gestures/pan-gesture.md deleted file mode 100644 index c8be974e7f..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/pan-gesture.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -id: pan-gesture -title: Pan gesture -sidebar_label: Pan gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that can recognize a panning (dragging) gesture and track its movement. - -The gesture [activates](../../under-the-hood/states-events.md#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. - -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. - -## 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. - -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 [`avgTouches`](#avgtouches-android-only) flag. - -Note that on both Android and iOS when the additional finger is placed on the screen that translation prop is not affected even though the position of the pointer being tracked might have changed. -Therefore it is safe to rely on translation most of the time as it only reflects the movement that happens regardless of how many fingers are placed on the screen and if that number changes over time. -If you wish to track the "center of mass" virtual pointer and account for its changes when the number of finger changes you can use relative or absolute position provided in the event ([`x`](#x) and [`y`](#y) or [`absoluteX`](#absolutex) and [`absoluteY`](#absolutey)). - -## Config - -### Properties specific to `PanGesture`: - -### `minDistance(value: number)` - -Minimum distance the finger (or multiple finger) need to travel before the gesture [activates](../../under-the-hood/states-events.md#active). Expressed in points. - -### `minPointers(value: number)` - -A number of fingers that is required to be placed before gesture can [activate](../../under-the-hood/states-events.md#active). Should be a higher or equal to 0 integer. - -### `maxPointers(value: number)` - -When the given number of fingers is placed on the screen and gesture hasn't yet [activated](../../under-the-hood/states-events.md#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. - -### `activeOffsetX(value: number | number[])` - -Range along X axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `activeOffsetY(value: number | number[])` - -Range along Y axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `failOffsetY(value: number | number[])` - -When the finger moves outside this range (in points) along Y axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `failOffsetX(value: number | number[])` - -When the finger moves outside this range (in points) along X axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `averageTouches(value: boolean)` (Android only) - -### `enableTrackpadTwoFingerGesture(value: boolean)` (iOS only) - -Enables two-finger gestures on supported devices, for example iPads with trackpads. If not enabled the gesture will require click + drag, with enableTrackpadTwoFingerGesture swiping with two fingers will also trigger the gesture. - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `PanGesture`: - -### `translationX` - -Translation of the pan gesture along X axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `translationY` - -Translation of the pan gesture along Y axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `velocityX` - -Velocity of the pan gesture along the X axis in the current moment. The value is expressed in point units per second. - -### `velocityY` - -Velocity of the pan gesture along the Y axis in the current moment. The value is expressed in point units per second. - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - - - -## Example - -```jsx -const END_POSITION = 200; -const onLeft = useSharedValue(true); -const position = useSharedValue(0); - -const panGesture = Gesture.Pan() - .onUpdate((e) => { - if (onLeft.value) { - position.value = e.translationX; - } else { - position.value = END_POSITION + e.translationX; - } - }) - .onEnd((e) => { - if (position.value > END_POSITION / 2) { - position.value = withTiming(END_POSITION, { duration: 100 }); - onLeft.value = false; - } else { - position.value = withTiming(0, { duration: 100 }); - onLeft.value = true; - } - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ translateX: position.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/pinch-gesture.md b/docs/versioned_docs/version-2.1.1/api/gestures/pinch-gesture.md deleted file mode 100644 index 5b56e7d043..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/pinch-gesture.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -id: pinch-gesture -title: Pinch gesture -sidebar_label: Pinch gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. -The gesture [activates](../../under-the-hood/states-events.md#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. - -## Config - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `PinchGesture`: - -### `scale` - -The scale factor relative to the points of the two touches in screen coordinates. - -### `velocity` - -Velocity of the pan gesture the current moment. The value is expressed in point units per second. - -### `focalX` - -Position expressed in points along X axis of center anchor point of gesture - -### `focalY` - -Position expressed in points along Y axis of center anchor point of gesture - - - -## Example - -```jsx -const scale = useSharedValue(1); -const savedScale = useSharedValue(1); - -const pinchGesture = Gesture.Pinch() - .onUpdate((e) => { - scale.value = savedScale.value * e.scale; - }) - .onEnd(() => { - savedScale.value = scale.value; - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ scale: scale.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/rotation-gesture.md b/docs/versioned_docs/version-2.1.1/api/gestures/rotation-gesture.md deleted file mode 100644 index 6550e0ea98..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/rotation-gesture.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -id: rotation-gesture -title: Rotation gesture -sidebar_label: Rotation gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that can recognize a rotation gesture and track its movement. - -The gesture [activates](../../under-the-hood/states-events.md#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. - -## Config - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `RotationGesture`: - -### `rotation` - -Amount rotated, expressed in radians, from the gesture's focal point (anchor). - -### `velocity` - -Instantaneous velocity, expressed in point units per second, of the gesture. - -### `anchorX` - -X coordinate, expressed in points, of the gesture's central focal point (anchor). - -### `anchorY` - -Y coordinate, expressed in points, of the gesture's central focal point (anchor). - - - -## Example - -```jsx -const rotation = useSharedValue(1); -const savedRotation = useSharedValue(1); - -const rotationGesture = Gesture.Rotation() - .onUpdate((e) => { - rotation.value = savedRotation.value + e.rotation; - }) - .onEnd(() => { - savedRotation.value = rotation.value; - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ rotateZ: `${(rotation.value / Math.PI) * 180}deg` }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.1.1/api/gestures/state-manager.md b/docs/versioned_docs/version-2.1.1/api/gestures/state-manager.md deleted file mode 100644 index cb50e8212b..0000000000 --- a/docs/versioned_docs/version-2.1.1/api/gestures/state-manager.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: state-manager -title: Gesture state manager -sidebar_label: Gesture state manager ---- - -`GestureStateManager` allows to manually control the state of the gestures. Please note that `react-native-reanimated` is required to use it, since it allows for synchronously executing methods in worklets. - -## Methods - -### `begin()` - -Transition the gesture to the [`BEGAN`](../../under-the-hood/states-events.md#began) state. This method will have no effect if the gesture has already activated or finished. - -### `activate()` - -Transition the gesture to the [`ACTIVE`](../../under-the-hood/states-events.md#active) state. This method will have no effect if the handler is already active, or has finished. -If the gesture is [`exclusive`](../../gesture-composition) with another one, the activation will be delayed until the gesture with higher priority fails. - -### `end()` - -Transition the gesture to the [`END`](../../under-the-hood/states-events.md#end) state. This method will have no effect if the handler has already finished. - -### `fail()` - -Transition the gesture to the [`FAILED`](../../under-the-hood/states-events.md#failed) state. This method will have no effect if the handler has already finished. diff --git a/docs/versioned_docs/version-2.1.1/community.md b/docs/versioned_docs/version-2.1.1/community.md deleted file mode 100644 index 740f408a4d..0000000000 --- a/docs/versioned_docs/version-2.1.1/community.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -id: community -title: Community -sidebar_label: 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
-
- -
-
- -
-
Jakub Gonet
-
- -
-
- -
-
Krzysztof Magiera
- @kzzzf -
- -
- -## 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: - -
- -
- -
- -
-
Shopify
- -
- -
- -
- -
-
Expo
- -
- -
diff --git a/docs/versioned_docs/version-2.1.1/contributing.md b/docs/versioned_docs/version-2.1.1/contributing.md deleted file mode 100644 index c3b9ab2a33..0000000000 --- a/docs/versioned_docs/version-2.1.1/contributing.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -id: contributing -title: Contributing ---- - -If you are interested in the project and want to contribute or support it in other ways don't hesitate to contact [me on Twitter](https://twitter.com/kzzzf)! - -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. diff --git a/docs/versioned_docs/version-2.1.1/example.md b/docs/versioned_docs/version-2.1.1/example.md deleted file mode 100644 index 3586ddd55c..0000000000 --- a/docs/versioned_docs/version-2.1.1/example.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -id: example -title: Running Example App ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import GifGallery from '@site/components/GifGallery' - -Example app code is located under [`example/`](https://github.com/software-mansion/react-native-gesture-handler/tree/main/example) folder in the repo. -It showcases the majority of the Gesture Handler library features. -The app consist of the list of single screen examples presenting the capabilities of the library. -Each example is located under a separate folder under [`example/`](https://github.com/software-mansion/react-native-gesture-handler/tree/main/example). - - - - - -## Running example app locally - -Before you begin you should follow [React Native's setup steps](http://facebook.github.io/react-native/docs/getting-started.html) to make sure you have all the tools necessary to build and run React Native apps installed. -The example app is a regular React Native app, so in case of problems or to learn about available commands you may want to [check react-native cli documentation](https://github.com/react-native-community/cli/blob/master/README.md). - -In order to run example app you need to clone the repo first: - -```bash -git clone git@github.com:software-mansion/react-native-gesture-handler.git -``` - -Then go to the library folder: - -```bash -cd react-native-gesture-handler/ -``` - -Install dependencies of library with the following command: - -```bash -yarn -``` - -Then go to the `example` folder: - -```bash -cd example -``` - -Install dependencies of example with the following command: - -```bash -yarn -``` - -Run development server: - -```bash -yarn start -``` - -Finally run one of the commands below in order to build, install and launch the app on Android: - -```bash -yarn android -``` - -or on iOS: - -```bash -yarn ios -``` - -You will need to have an Android or iOS device or emulator connected and `react-native-cli` package installed globally. diff --git a/docs/versioned_docs/version-2.1.1/gesture-composition.md b/docs/versioned_docs/version-2.1.1/gesture-composition.md deleted file mode 100644 index e55e06fae6..0000000000 --- a/docs/versioned_docs/version-2.1.1/gesture-composition.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -id: gesture-composition -title: Composing gestures -sidebar_label: Composing gestures ---- - -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 -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 -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 -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 ( - - - -); -``` - -## Composition vs `simultaneousWithExternalGesture` and `requireExternalGestureToFail` - -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. If you want to make a relation between gestures that are attached to separate `GestureDetectors`, we have a separate mechanism for that: `simultaneousWithExternalGesture` and `requireExternalGestureToFail` methods that are available on every base gesture. They work exactly the same way as `simultaneousHandlers` and `waitFor` on gesture handlers, that is they just mark the relation between the gestures without joining them into single object. diff --git a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/common-gh.md b/docs/versioned_docs/version-2.1.1/gesture-handlers/api/common-gh.md deleted file mode 100644 index 471f5250c2..0000000000 --- a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/common-gh.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -id: common-gh -title: Common handler properties -sidebar_label: Common handler properties ---- - -This page covers the common set of properties all gesture handler components expose. - -### Units - -All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". -These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://facebook.github.io/react-native/docs/flexbox.html)). -They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. - -## Properties - -This section describes properties that can be used with all gesture handler components: - -### `enabled` - -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`](../basics/state.md#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`](../basics/state.md#failed) or [`CANCELLED`](../basics/state.md#cancelled) (depending on its current state). -Default value is `true`. - -### `shouldCancelWhenOutside` - -Accepts a boolean value. -When `true` the handler will [cancel](../basics/state.md#cancelled) or [fail](../basics/state.md#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.md) and [`TapGestureHandler`](./tap-gh.md) 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](../basics/state.md#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](../basics/state.md#active) state. It will also prevent the provided handlers from [cancelling](../basics/state.md#cancelled) the current handler when they [activate](../basics/state.md#active). Read more in the [cross handler interaction](../basics/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](../basics/state.md#active) as long as the handlers provided by their refs are in the [`BEGAN`](../basics/state.md#began) state. Read more in the [cross handler interaction](../basics/interactions.md#awaiting-other-handlers) section. - -### `hitSlop` - -This parameter enables control over what part of the connected view area can be used to [begin](../basics/state.md#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://facebook.github.io/react-native/docs/view.html#props) property. - -### `onGestureEvent` - -Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](../basics/state.md#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.md#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://facebook.github.io/react-native/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](../basics/state.md) 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](../basics/state.md) of the handler right before the change. - -Instead of a callback [`Animated.event`](https://facebook.github.io/react-native/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. - -## Event data - -This section describes the attributes of event object being provided to [`onGestureEvent`](#ongestureevent) and [`onHandlerStateChange`](#onhandlerstatechange) callbacks: - -### `state` - -Current [state](../basics/state.md) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](../basics/state.md) to learn more about how to use it. - -### `numberOfPointers` - -Represents the number of pointers (fingers) currently placed on the screen. diff --git a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/create-native-wrapper.md b/docs/versioned_docs/version-2.1.1/gesture-handlers/api/create-native-wrapper.md deleted file mode 100644 index 519f7c583c..0000000000 --- a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/create-native-wrapper.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -id: create-native-wrapper -title: createNativeWrapper -sidebar_label: createNativeWrapper() ---- - -Creates provided component with NativeViewGestureHandler, allowing it to be part of RNGH's -gesture system. - -## Arguments - -### Component - -The component we want to wrap. - -### config - -Config is an object with properties that can be used on [`NativeViewGestureHandler`](./nativeview-gh.md) - -## Returns - -Wrapped component. diff --git a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/fling-gh.md b/docs/versioned_docs/version-2.1.1/gesture-handlers/api/fling-gh.md deleted file mode 100644 index dca6ed4546..0000000000 --- a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/fling-gh.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -id: fling-gh -title: FlingGestureHandler -sidebar_label: Fling ---- - -A discrete gesture handler that activates when the movement is sufficiently long and fast. -Handler gets [ACTIVE](../basics/state#active) when movement is sufficiently long and it does not take too much time. -When handler gets activated it will turn into [END](../basics/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](./common-gh.md#properties). Below is a list of properties specific to `FlingGestureHandler` component: - -### `direction` - -Expressed allowed direction of movement. It's possible to pass one or many directions in one parameter: - -```js -direction={Directions.RIGHT | Directions.LEFT} -``` - -or - -```js -direction={Directions.DOWN} -``` - -### `numberOfPointers` - -Determine exact number of points required to handle the fling gesture. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `FlingGestureHandler`: - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - -## Example - -See the [fling example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/release_tests/fling/index.tsx) from [GestureHandler Example App](../../example.md). - -```js -const LongPressButton = () => ( - { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert("I'm flinged!"); - } - }}> - - -); -``` diff --git a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/force-gh.md b/docs/versioned_docs/version-2.1.1/gesture-handlers/api/force-gh.md deleted file mode 100644 index ad2102e603..0000000000 --- a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/force-gh.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -id: force-gh -title: ForceTouchGestureHandler (iOS only) -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](../basics/state.md#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. - -The handler is implemented using custom [UIGestureRecognizer](https://developer.apple.com/documentation/uikit/uigesturerecognizer) on iOS. There's no implementation provided on Android and it simply render children without any wrappers. -Since this behaviour is only provided on some iOS devices, this handler should not be used for defining any crucial behaviors. Use it only as an additional improvement and make all features to be accessed without this handler as well. - -# Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to `ForceTouchGestureHandler` component: - -### `minForce` - -A minimal pressure that is required before handler can [activate](../basics/state.md#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](../basics/state.md#failed). Should be a value from range `[0.0, 1.0]`. - -### `feedbackOnActivation` - -Boolean value defining if haptic feedback has to be performed on activation. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `ForceTouchGestureHandler`: - -### `force` - -The pressure of a touch. - -## Static method - -### `forceTouchAvailable` - -You may check if it's possible to use `ForceTouchGestureHandler` with `ForceTouchGestureHandler.forceTouchAvailable` - -## Example - -See the [force touch handler example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/forcetouch/index.tsx) from [GestureHandler Example App](../../example). - -```js - - - -``` diff --git a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/longpress-gh.md b/docs/versioned_docs/version-2.1.1/gesture-handlers/api/longpress-gh.md deleted file mode 100644 index 38aa8c8fca..0000000000 --- a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/longpress-gh.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -id: longpress-gh -title: LongPressGestureHandler -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](../basics/state.md#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.java) on Android. - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to the `LongPressGestureHandler` component: - -### `minDurationMs` - -Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. - -### `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](../basics/state.md#active), it will fail to recognize the gesture. The default value is 10. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to the `LongPressGestureHandler` component: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `duration` - -Duration of the long press (time since the start of the event), expressed in milliseconds. - -## Example - -See the [multitap example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from [GestureHandler Example App](example.md). - -```js -const LongPressButton = () => ( - { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert("I'm being pressed for so long"); - } - }} - minDurationMs={800}> - - -); -``` diff --git a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/nativeview-gh.md b/docs/versioned_docs/version-2.1.1/gesture-handlers/api/nativeview-gh.md deleted file mode 100644 index d857f57ed7..0000000000 --- a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/nativeview-gh.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -id: nativeview-gh -title: NativeViewGestureHandler -sidebar_label: NativeView ---- - -A gesture handler that allows other touch handling components to participate in -RNGH's gesture system. - -Used by [`createNativeWrapper()`](./create-native-wrapper.md). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to `NativeViewGestureHandler` component: - -### `shouldActivateOnStart` (**Android only**) - -When `true`, underlying handler will activate unconditionally when in `BEGAN` or `UNDETERMINED` state. - -### `disallowInterruption` - -When `true`, cancels all other gesture handlers when this `NativeViewGestureHandler` receives an `ACTIVE` state event. diff --git a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/pan-gh.md b/docs/versioned_docs/version-2.1.1/gesture-handlers/api/pan-gh.md deleted file mode 100644 index 06a1ff5383..0000000000 --- a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/pan-gh.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -id: pan-gh -title: PanGestureHandler -sidebar_label: Pan ---- - -A continuous gesture handler that can recognize a panning (dragging) gesture and track its movement. - -The handler [activates](../basics/state.md#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. - -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. - -The handler is implemented using [UIPanGestureRecognizer](https://developer.apple.com/documentation/uikit/uipangesturerecognizer) on iOS and [PanGestureHandler](https://github.com/software-mansion/react-native-gesture-handler/blob/main/android/lib/src/main/java/com/swmansion/gesturehandler/PanGestureHandler.java) on Android. - -## 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](../basics/state.md#active) or [fail](../basics/state.md#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. -Another example would be setting both [`maxDeltaX`](#maxdeltaX) and [`maxDeltaY`](#maxdeltay) to 20 and [`minDist`](#mindist) to 23. -In such a case, if we move a finger along the X-axis by 20 points and along the Y-axis by 0 points, the handler will fail even though the finger is still within the bounds of translation along Y-axis. - -## 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. - -The default behavior for native components like scroll view, pager views or drawers is different and hence gesture handler 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 [`avgTouches`](#avgtouches-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)). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#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](../basics/state.md#active). Expressed in points. - -### `minPointers` - -A number of fingers that is required to be placed before handler can [activate](../basics/state.md#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](../basics/state.md#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. - -### `activeOffsetX` - -Range along X axis (in points) where fingers travels without activation of handler. Moving outside of this range implies activation of handler. 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` - -Range along Y axis (in points) where fingers travels without activation of handler. Moving outside of this range implies activation of handler. 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` - -When the finger moves outside this range (in points) along Y axis and handler 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` - -When the finger moves outside this range (in points) along X axis and handler 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. - -### `maxDeltaX` - -> 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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#active) for the movement in one particular direction use [`minOffsetY`](#minoffsety) instead. - -### `avgTouches` (Android only) - -### `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. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `PanGestureHandler`: - -### `translationX` - -Translation of the pan gesture along X axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `translationY` - -Translation of the pan gesture along Y axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `velocityX` - -Velocity of the pan gesture along the X axis in the current moment. The value is expressed in point units per second. - -### `velocityY` - -Velocity of the pan gesture along the Y axis in the current moment. The value is expressed in point units per second. - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - -## Example - -See the [draggable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/draggable/index.tsx) from [GestureHandler Example App](../../example). - -```js -const circleRadius = 30; -class Circle extends Component { - _touchX = new Animated.Value(windowWidth / 2 - circleRadius); - _onPanGestureEvent = Animated.event([{ nativeEvent: { x: this._touchX } }], { - useNativeDriver: true, - }); - render() { - return ( - - - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/pinch-gh.md b/docs/versioned_docs/version-2.1.1/gesture-handlers/api/pinch-gh.md deleted file mode 100644 index 094c700516..0000000000 --- a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/pinch-gh.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -id: pinch-gh -title: PinchGestureHandler -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](../basics/state.md#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. - -The handler is implemented using [UIPinchGestureRecognizer](https://developer.apple.com/documentation/uikit/uipinchgesturerecognizer) on iOS and from scratch on Android. - -## Properties - -Properties provided to `PinchGestureHandler` do not extend [common set of properties from base handler class](./common-gh.md#properties). - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `PinchGestureHandler`: - -### `scale` - -The scale factor relative to the points of the two touches in screen coordinates. - -### `velocity` - -Velocity of the pan gesture the current moment. The value is expressed in point units per second. - -### `focalX` - -Position expressed in points along X axis of center anchor point of gesture - -### `focalY` - -Position expressed in points along Y axis of center anchor point of gesture - -## Example - -See the [scale and rotation example](hhttps://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from [GestureHandler Example App](../../example). - -```js -export class PinchableBox extends React.Component { - _baseScale = new Animated.Value(1); - _pinchScale = new Animated.Value(1); - _scale = Animated.multiply(this._baseScale, this._pinchScale); - _lastScale = 1; - _onPinchGestureEvent = Animated.event( - [{ nativeEvent: { scale: this._pinchScale } }], - { useNativeDriver: USE_NATIVE_DRIVER } - ); - - _onPinchHandlerStateChange = (event) => { - if (event.nativeEvent.oldState === State.ACTIVE) { - this._lastScale *= event.nativeEvent.scale; - this._baseScale.setValue(this._lastScale); - this._pinchScale.setValue(1); - } - }; - - render() { - return ( - - - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/rotation-gh.md b/docs/versioned_docs/version-2.1.1/gesture-handlers/api/rotation-gh.md deleted file mode 100644 index 3e80dda287..0000000000 --- a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/rotation-gh.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -id: rotation-gh -title: RotationGestureHandler -sidebar_label: Rotation ---- - -A continuous gesture handler that can recognize a rotation gesture and track its movement. - -The handler [activates](../basics/state.md#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. - -The handler is implemented using [UIRotationGestureRecognizer](https://developer.apple.com/documentation/uikit/uirotationgesturerecognizer) on iOS and from scratch on Android. - -## Properties - -Properties provided to `RotationGestureHandler` do not extend [common set of properties from base handler class](./common-gh.md#properties). - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `RotationGestureHandler`: - -### `rotation` - -Amount rotated, expressed in radians, from the gesture's focal point (anchor). - -### `velocity` - -Instantaneous velocity, expressed in point units per second, of the gesture. - -### `anchorX` - -X coordinate, expressed in points, of the gesture's central focal point (anchor). - -### `anchorY` - -Y coordinate, expressed in points, of the gesture's central focal point (anchor). - -## Example - -See the [scale and rotation example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from [GestureHandler Example App](../../example). - -```js -class RotableBox extends React.Component { - _rotate = new Animated.Value(0); - _rotateStr = this._rotate.interpolate({ - inputRange: [-100, 100], - outputRange: ['-100rad', '100rad'], - }); - _lastRotate = 0; - _onRotateGestureEvent = Animated.event( - [{ nativeEvent: { rotation: this._rotate } }], - { useNativeDriver: USE_NATIVE_DRIVER } - ); - _onRotateHandlerStateChange = (event) => { - if (event.nativeEvent.oldState === State.ACTIVE) { - this._lastRotate += event.nativeEvent.rotation; - this._rotate.setOffset(this._lastRotate); - this._rotate.setValue(0); - } - }; - render() { - return ( - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/tap-gh.md b/docs/versioned_docs/version-2.1.1/gesture-handlers/api/tap-gh.md deleted file mode 100644 index bc27d1a03c..0000000000 --- a/docs/versioned_docs/version-2.1.1/gesture-handlers/api/tap-gh.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -id: tap-gh -title: TapGestureHandler -sidebar_label: Tap ---- - -A discrete gesture handler 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 handler to [activate](../basics/state.md#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](../basics/state.md#active), it will [END](../basics/state.md#end). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#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](../basics/state.md#active). Should be a positive integer. The default value is 1. - -### `maxDurationMs` - -Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch. The default value is 500. - -### `maxDelayMs` - -Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required. The default value is 500. - -### `numberOfTaps` - -Number of tap gestures required to [activate](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#active), it will fail to recognize the gesture. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to the `TapGestureHandler` component: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -## Example - -See the [multitap example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from [GestureHandler Example App](../../example.md). - -```js -export class PressBox extends Component { - doubleTapRef = React.createRef(); - render() { - return ( - - - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.1.1/gesture-handlers/basics/about-handlers.md b/docs/versioned_docs/version-2.1.1/gesture-handlers/basics/about-handlers.md deleted file mode 100644 index 4c2062a24f..0000000000 --- a/docs/versioned_docs/version-2.1.1/gesture-handlers/basics/about-handlers.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -id: about-handlers -title: About Gesture Handlers -sidebar_label: About Gesture Handlers ---- - -Gesture handlers are the core building blocks of this library. -We use this term to describe elements of the native touch system that the library allows us to instantiate and control from Javascript using [React's Component](https://reactjs.org/docs/react-component.html) interface. - -Each handler type is capable of recognizing one type of gesture (pan, pinch, etc.) and provides gesture-specific information via events (translation, scale, 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](./state.md). -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](./state.md#active), it cancels all the other gestures (read more about how to influence this process in ["Cross handler interactions"](./interactions.md) 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. - -### Available gesture handlers - -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`](../api/pan-gh.md) -- [`TapGestureHandler`](../api/tap-gh.md) -- [`LongPressGestureHandler`](../api/longpress-gh.md) -- [`RotationGestureHandler`](../api/rotation-gh.md) -- [`FlingGestureHandler`](../api/fling-gh.md) -- [`PinchGestureHandler`](../api/pinch-gh.md) -- [`ForceTouchGestureHandler`](../api/force-gh.md) - -### Discrete vs continuous - -We distinguish between two types of gestures: discrete and continuous. - -Continuous gesture handlers can be [active](./state.md#active) for a long period of time and will generate a stream of [gesture events](../api/common-gh.md#ongestureevent) until the gesture is [over](./state.md#ended). -An example of a continuous handler is [`PanGestureHandler`](../api/pan-gh.md) that once [activated](./state.md#active), will start providing updates about [translation](../api/pan-gh.md#translationx) and other properties. - -On the other hand, discrete gesture handlers once [activated](./state.md#active) will not stay in the active state but will [end](./state.md#ended) immediately. -[`LongPressGestureHandler`](../api/longpress-gh.md) 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`](../api/pan-gh.md)). - -Keep in mind that `onGestureEvent` is only generated in continuous gesture handlers and shouldn't be used in the `TapGestureHandler` and other discrete handlers. - -### Nesting handlers - -Handler components can be nested. In any case it is recommended that the innermost handler renders a native view component. There are some limitations that apply when [using `useNativeDriver` flag](#events-with-usenativedriver). An example of nested handlers: - -```js -class Multitap extends Component { - render() { - return ( - - - - - - - - ); - } -} -``` - -### Using native components - -Gesture handler library exposes a set of components normally available in React Native that are wrapped in [`NativeViewGestureHandler`](../api/nativeview-gh.md). -Here is a list of exposed components: - -- `ScrollView` -- `FlatList` -- `Switch` -- `TextInput` -- `DrawerLayoutAndroid` (**Android only**) - -If you want to use other handlers or [buttons](../../api/components/buttons.mdx) nested in a `ScrollView`, use the [`waitFor`](../api/common-gh.md#waitfor) property to define interaction between a handler and `ScrollView` - -### Events with `useNativeDriver` - -Because handlers do not instantiate native views but instead hook up to their child views, directly nesting two gesture handlers using `Animated.event` is not currently supported. -To workaround this limitation we recommend placing an `` component in between the handlers. - -Instead of doing: - -```js -const PanAndRotate = () => ( - - - - - -); -``` - -Place an `` in between the handlers: - -```js -const PanAndRotate = () => ( - - - - - - - -); -``` - -Another consequence of handlers depending on their native child components is that when using a `useNativeDriver` flag with an `Animated.event`, the child component must be wrapped by an `Animated.API` e.g. `` instead of just a ``: - -```js -class Draggable extends Component { - render() { - return ( - - {/* <-- NEEDS TO BE Animated.View */} - - ); - } -}; -``` diff --git a/docs/versioned_docs/version-2.1.1/gesture-handlers/basics/interactions.md b/docs/versioned_docs/version-2.1.1/gesture-handlers/basics/interactions.md deleted file mode 100644 index 762d0e96f9..0000000000 --- a/docs/versioned_docs/version-2.1.1/gesture-handlers/basics/interactions.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -id: interactions -title: Cross handler interactions -sidebar_label: Cross handler interactions ---- - -Gesture handlers can "communicate" with each other to support complex gestures and control how they _[activate](./state.md#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. -Gesture handler relies on ref objects created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html) and introduced in [React 16.3](https://reactjs.org/blog/2018/03/29/react-v-16-3.html#createref-api). - -## Simultaneous recognition - -By default, only one gesture handler is allowed to be in the [`ACTIVE`](./state.md#active) state. -So when a gesture handler recognizes a gesture it [cancels](./state.md#cancelled) all other handlers in the [`BEGAN`](./state.md#began) state and prevents any new handlers from receiving a stream of touch events as long as it remains [`ACTIVE`](./state.md#active). - -This behavior can be altered using the [`simultaneousHandlers`](../api/common-gh.md#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`](./state.md#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`](../api/pinch-gh.md), [`RotationGestureHandler`](../api/rotation-gh.md) and [`PanGestureHandler`](../api/pan-gh.md) that would have to simultaneously recognize gestures. - -### Example - -See the ["Scale, rotate & tilt" example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from the [GestureHandler Example App](../../example.md) or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -class PinchableBox extends React.Component { - // ...take a look on full implementation in an Example app - render() { - const imagePinch = React.createRef(); - const imageRotation = React.createRef(); - return ( - - - - - - - - - - ); - } -} -``` - -## Awaiting other handlers - -### Use cases - -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](./state.md#cancelled) the double tap handler. - -### Example - -See the ["Multitap" example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from [GestureHandler Example App](../../example.md) or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -const doubleTap = React.createRef(); -const PressBox = () => ( - - nativeEvent.state === State.ACTIVE && Alert.alert('Single tap!') - } - waitFor={doubleTap}> - - nativeEvent.state === State.ACTIVE && Alert.alert("You're so fast") - } - numberOfTaps={2}> - - - -); -``` diff --git a/docs/versioned_docs/version-2.1.1/introduction.md b/docs/versioned_docs/version-2.1.1/introduction.md deleted file mode 100644 index 14545fc100..0000000000 --- a/docs/versioned_docs/version-2.1.1/introduction.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -id: introduction -title: Introduction -sidebar_label: Introduction -slug: / ---- - -Gesture Handler aims to replace React Native's built in touch system called [Gesture Responder System](http://facebook.github.io/react-native/docs/gesture-responder-system). - -The motivation for building this library was to address the performance limitations of React Native's Gesture Responder System and to provide more control over the built-in native components that can handle gestures. -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. - -In a nutshell, the library provides: - -- A way to use a platform's native touch handling system for recognizing pinch, rotation and pan (besides a few other gestures). -- The ability to define relations between gesture handlers, e.g. when you have a pan handler in `ScrollView` you can make that `ScrollView` wait until it knows pan won't recognize. -- Mechanisms to use touchables 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. - -:::info -It is recommended to use Reanimated 2 for animations when using React Native Gesture Handler as its more advanced features rely heavily on the worklets provided by Reanimated. -::: - -## Installation - -### Requirements - -| version | `react-native` version | -| --------- | ---------------------- | -| 2.0.0+ | 0.63.0+ | -| 1.4.0+ | 0.60.0+ | -| 1.1.0+ | 0.57.2+ | -| <1.1.0 | 0.50.0+ | - -It may be possible to use newer versions of react-native-gesture-handler on React Native with version <= 0.59 by reverse Jetifying. -Read more on that here https://github.com/mikehardy/jetifier#to-reverse-jetify--convert-node_modules-dependencies-to-support-libraries - -Note that if you wish to use [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html) support for [interactions](./gesture-handlers/basics/interactions.md) you need to use v16.3 of [React](https://reactjs.org/) - -In order to fully utilize the [touch events](./api/gestures/touch-events.md) you also need to use `react-native-reanimated` 2.3.0-beta.4 or newer. - -### Expo - -#### Managed [Expo](https://expo.io) - -To use the version of react-native-gesture-handler that is compatible with your managed Expo project, run `expo install react-native-gesture-handler`. - -The Expo SDK incorporates the latest version of react-native-gesture-handler available at the time of each SDK release, so managed Expo apps might not always support all our latest features as soon as they are available. - -#### Bare [React Native](http://facebook.github.io/react-native/) - -Since the library uses native support for handling gestures, it requires an extended installation to the norm. If you are starting a new project, you may want to initialize it with [expo-cli](https://docs.expo.io/versions/latest/workflow/expo-cli/) and use a bare template, they come pre-installed with react-native-gesture-handler. - -### JS - -First, install the library using `yarn`: - -```bash -yarn add react-native-gesture-handler -``` - -or with `npm` if you prefer: - -```bash -npm install --save react-native-gesture-handler -``` - -After installation, wrap your entry point with `` or -`gestureHandlerRootHOC`. - -For example: - -```js -export default function App() { - return {/* content */}; -} -``` - -:::info -If you use props such as `shouldCancelWhenOutside`, `simultaneousHandlers`, `waitFor` etc. with gesture handlers, the handlers need to be mounted under a single `GestureHandlerRootView`. So it's important to keep the `GestureHandlerRootView` as close to the actual root view as possible. - -Note that `GestureHandlerRootView` acts like a normal `View`. So if you want it to fill the screen, you will need to pass `{ flex: 1 }` like you'll need to do with a normal `View`. By default, it'll take the size of the content nested inside. -::: - -:::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. -::: - -#### Linking - -> **Important**: You only need to do this step if you're using React Native 0.59 or lower. Since v0.60, linking happens automatically. - -```bash -react-native link react-native-gesture-handler -``` - -### Android - -#### Usage with modals on Android - -On Android RNGH does not work by default because modals are not located under React Native Root view in native hierarchy. -To fix that, components need to be wrapped with `gestureHandlerRootHOC` (it's no-op on iOS and web). - -For example: - -```js -const ExampleWithHoc = gestureHandlerRootHOC(() => ( - - - - ); -); - -export default function Example() { - return ( - - - - ); -} -``` - -#### Kotlin - -Since version `2.0.0` RNGH has been rewritten with Kotlin. The default version of the Kotlin plugin used in this library is `1.5.20`. - -If you need to use a different Kotlin version, set the `kotlinVersion` ext property in `android/build.gradle` file and RNGH will use that version: - -``` -buildscript { - ext { - ... - kotlinVersion = "1.5.20" - } -} -``` - -The minimal version of the Kotlin plugin supported by RNGH is `1.4.10`. - -### iOS - -There is no additional configuration required on iOS except what follows in the next steps. - -If you're in a CocoaPods project (the default setup since React Native 0.60), -make sure to install pods before you run your app: - -```bash -cd ios && pod install -``` - -For React Native 0.61 or greater, add the library as the first import in your index.js file: - -```js -import 'react-native-gesture-handler'; -``` - -### Testing - -In order to load mocks provided by the library add following to your jest config in `package.json`: - -```json -"setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"] -``` - -Example: - -```json -"jest": { - "preset": "react-native", - "setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"] -} -``` diff --git a/docs/versioned_docs/version-2.1.1/manual-gestures/manual-gestures.md b/docs/versioned_docs/version-2.1.1/manual-gestures/manual-gestures.md deleted file mode 100644 index eae7fffd2d..0000000000 --- a/docs/versioned_docs/version-2.1.1/manual-gestures/manual-gestures.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -id: manual-gestures -title: Manual gestures -sidebar_label: Manual gestures ---- - -import Step, { Divider } from '@site/src/theme/Step'; -import Step1 from './step1.md'; -import Step2 from './step2.md'; -import Step3 from './step3.md'; -import Step4 from './step4.md'; -import Step5 from './step5.md'; -import Step6 from './step6.md'; -import Step7 from './step7.md'; - -RNGH2 finally brings one of the most requested features: manual gestures and touch events. To demonstrate how to make a manual gesture we will make a simple one that tracks all pointers on the screen. - - - - - First, we need a way to store information about the pointer: whether it should be visible and its position. - - - - - - - We also need a component to mark where a pointer is. In order to accomplish that we will make a component that accepts two shared values: one holding information about the pointer using the interface we just created, the other holding a bool indicating whether the gesture has activated. - In this example when the gesture is not active, the ball representing it will be blue and when it is active the ball will be red and slightly bigger. - - - - - - - Now we have to make a component that will handle the gesture and draw all the pointer indicators. We will store data about pointers in an array of size 12 as that is the maximum number of touches that RNGH will track, and render them inside an Animated.View. - - - - - - - We have our components set up and we can finally get to making the gesture! We will start with onTouchesDown where we need to set position of the pointers and make them visible. We can get this information from the touches property of the event. In this case we will also check how many pointers are on the screen and activate the gesture if there are at least two. - - - - - - - Next, we will handle pointer movement. In onTouchesMove we will simply update the position of moved pointers. - - - - - - - We also need to handle lifting fingers from the screen, which corresponds to onTouchesUp. Here we will just hide the pointers that were lifted and end the gesture if there are no more pointers on the screen. - Note that we are not handling onTouchesCancelled as in this very basic case we don't expect it to happen, however you should clear data about cancelled pointers (most of the time all active ones) when it is called. - - - - - - - Now that our pointers are being tracked correctly and we have the state management, we can handle activation and ending of the gesture. In our case, we will simply set the active shared value either to true or false. - - - - - -And that's all! As you can see using manual gestures is really easy but as you can imagine, manual gestures are a powerful tool that makes it possible to accomplish things that were previously impossible with RNGH. - -## Modifying existing gestures - -While manual gestures open great possibilities we are aware that reimplementing pinch or rotation from scratch just because you need to activate in specific circumstances or require position of the fingers, would be a waste of time as those gestures are already there. Because of that you can use touch events with every gesture so that you can extract more informations about gesture than is sent to you in events. We also added a `manualActivation` modifier on all continous gestures, which prevents the gesture it is applied to from activating by itself thus giving you full control of its behavior. - -This functionality makes another highly requested feature possible: drag after long press. Simply set `manualActivation` to `true` on a `PanGesture` and use `StateManager` to fail the gesture if the user attempts to drag the component sooner than the duration of the long press. diff --git a/docs/versioned_docs/version-2.1.1/manual-gestures/step1.md b/docs/versioned_docs/version-2.1.1/manual-gestures/step1.md deleted file mode 100644 index 4c6331c1c8..0000000000 --- a/docs/versioned_docs/version-2.1.1/manual-gestures/step1.md +++ /dev/null @@ -1,7 +0,0 @@ -```jsx -interface Pointer { - visible: boolean; - x: number; - y: number; -} -``` diff --git a/docs/versioned_docs/version-2.1.1/manual-gestures/step3.md b/docs/versioned_docs/version-2.1.1/manual-gestures/step3.md deleted file mode 100644 index c9b32e5c2a..0000000000 --- a/docs/versioned_docs/version-2.1.1/manual-gestures/step3.md +++ /dev/null @@ -1,29 +0,0 @@ -```jsx -export default function Example() { - const trackedPointers: Animated.SharedValue[] = []; - const active = useSharedValue(false); - - for (let i = 0; i < 12; i++) { - trackedPointers[i] = - useSharedValue < - Pointer > - { - visible: false, - x: 0, - y: 0, - }; - } - - const gesture = Gesture.Manual(); - - return ( - - - {trackedPointers.map((pointer, index) => ( - - ))} - - - ); -} -``` diff --git a/docs/versioned_docs/version-2.1.1/manual-gestures/step4.md b/docs/versioned_docs/version-2.1.1/manual-gestures/step4.md deleted file mode 100644 index 36ec2c34bd..0000000000 --- a/docs/versioned_docs/version-2.1.1/manual-gestures/step4.md +++ /dev/null @@ -1,15 +0,0 @@ -```jsx {2-15} -const gesture = Gesture.Manual().onTouchesDown((e, manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: true, - x: touch.x, - y: touch.y, - }; - } - - if (e.numberOfTouches >= 2) { - manager.activate(); - } -}); -``` diff --git a/docs/versioned_docs/version-2.1.1/manual-gestures/step5.md b/docs/versioned_docs/version-2.1.1/manual-gestures/step5.md deleted file mode 100644 index d2f9377cc8..0000000000 --- a/docs/versioned_docs/version-2.1.1/manual-gestures/step5.md +++ /dev/null @@ -1,13 +0,0 @@ -```jsx {3-12} -const gesture = Gesture.Manual() - ... - .onTouchesMove((e, _manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: true, - x: touch.x, - y: touch.y, - }; - } - }) -``` diff --git a/docs/versioned_docs/version-2.1.1/manual-gestures/step6.md b/docs/versioned_docs/version-2.1.1/manual-gestures/step6.md deleted file mode 100644 index 323f9516cb..0000000000 --- a/docs/versioned_docs/version-2.1.1/manual-gestures/step6.md +++ /dev/null @@ -1,17 +0,0 @@ -```jsx {3-16} -const gesture = Gesture.Manual() - ... - .onTouchesUp((e, manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: false, - x: touch.x, - y: touch.y, - }; - } - - if (e.numberOfTouches === 0) { - manager.end(); - } - }) -``` diff --git a/docs/versioned_docs/version-2.1.1/manual-gestures/step7.md b/docs/versioned_docs/version-2.1.1/manual-gestures/step7.md deleted file mode 100644 index 913e766ae8..0000000000 --- a/docs/versioned_docs/version-2.1.1/manual-gestures/step7.md +++ /dev/null @@ -1,10 +0,0 @@ -```jsx {3-10} -const gesture = Gesture.Manual() - ... - .onStart(() => { - active.value = true; - }) - .onEnd(() => { - active.value = false; - }); -``` diff --git a/docs/versioned_docs/version-2.1.1/quickstart/step2.md b/docs/versioned_docs/version-2.1.1/quickstart/step2.md deleted file mode 100644 index 34c528266b..0000000000 --- a/docs/versioned_docs/version-2.1.1/quickstart/step2.md +++ /dev/null @@ -1,9 +0,0 @@ -```jsx -function Ball() { - return ( - - - - ); -} -``` diff --git a/docs/versioned_docs/version-2.1.1/quickstart/step3.md b/docs/versioned_docs/version-2.1.1/quickstart/step3.md deleted file mode 100644 index ee7184ffc7..0000000000 --- a/docs/versioned_docs/version-2.1.1/quickstart/step3.md +++ /dev/null @@ -1,14 +0,0 @@ -```jsx -const isPressed = useSharedValue(false); -const offset = useSharedValue({ x: 0, y: 0 }); -const animatedStyles = useAnimatedStyle(() => { - return { - transform: [ - { translateX: offset.value.x }, - { translateY: offset.value.y }, - { scale: withSpring(isPressed.value ? 1.2 : 1) }, - ], - backgroundColor: isPressed.value ? 'yellow' : 'blue', - }; -}); -``` diff --git a/docs/versioned_docs/version-2.1.1/quickstart/step4.md b/docs/versioned_docs/version-2.1.1/quickstart/step4.md deleted file mode 100644 index 8e2112a3cd..0000000000 --- a/docs/versioned_docs/version-2.1.1/quickstart/step4.md +++ /dev/null @@ -1,9 +0,0 @@ -```jsx {4} -... -return ( - - - -); -... -``` diff --git a/docs/versioned_docs/version-2.1.1/quickstart/step5.md b/docs/versioned_docs/version-2.1.1/quickstart/step5.md deleted file mode 100644 index c7c2e07265..0000000000 --- a/docs/versioned_docs/version-2.1.1/quickstart/step5.md +++ /dev/null @@ -1,32 +0,0 @@ -```jsx -const start = useSharedValue({ x: 0, y: 0 }); -const gesture = Gesture.Pan() - .onBegin(() => { - isPressed.value = 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, - }; - }) - .onFinalize(() => { - isPressed.value = false; - }); -``` - -```jsx {3} -... -return ( - - - -); -... -``` diff --git a/docs/versioned_docs/version-2.1.1/resources.md b/docs/versioned_docs/version-2.1.1/resources.md deleted file mode 100644 index eff7378934..0000000000 --- a/docs/versioned_docs/version-2.1.1/resources.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -id: resources -title: Learning Resources ---- - -## Apps - -[Gesture Handler Example App](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example) – official gesture handler "showcase" app. - -[Gesture Handler Example on Expo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo) – the official app you can install and play with using [Expo](https://expo.io). - -## 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 Vetne](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. diff --git a/docs/versioned_docs/version-2.1.1/troubleshooting.md b/docs/versioned_docs/version-2.1.1/troubleshooting.md deleted file mode 100644 index 2bc94e0f90..0000000000 --- a/docs/versioned_docs/version-2.1.1/troubleshooting.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -id: troubleshooting -title: Troubleshooting ---- - -## Troubleshooting - -Thanks for giving this library a try! We are sorry that you might have encountered issues though. Here is how you can seek help: - -1. Search over the [issues on Github](https://github.com/software-mansion/react-native-gesture-handler/issues). There is a chance someone had this problem in the past and it has been resolved! - -2. When sure your problem hasn't been reported or was reported but the proposed solution doesn't work for you please follow [our issue reporting guidelines](#reporting-issues). - -3. You can try seeking help on [Expo Developers Slack channel](https://slack.expo.io/) where we often hang out. - -4. If you feel like reading the source code I highly recommend it, as this is by far the best resource and gives you the most up to date insights into how the library works and what might be causing the bug. - -5. If you managed to find the solution consider [contributing](contributing.md) a fix or update our documentation to make this information easier to find for the others in the future. - -## Reporting issues - -This library is maintained by a very small team. -Please be mindful of that when reporting issue and when it happens that we can't get back to you as soon as you might expect. -We would love to fix all the problems as soon as possible, but often our time is constraint with other issues/features or projects. -To make it easier for us to understand your issue and to be able to approach it sooner you can help by: - -- Making sure the issue description is complete. Please include all the details about your environment (library version, RN version, device OS etc). -- It is the best to provide an example app that reproduces the issue you are having. Put it up on [gist](https://gist.github.com/), [snack](https://snack.expo.io) or create a repo on Github – it doesn't matter as long as we can easily pull it in, run and see the issue. -- Explain how you run your repro app and what steps to take to reproduce the issue. -- Isolate your issue from other dependencies you might be using and make the repro app as minimal as possible. -- If you have spent some time figuring out the root cause of the problem you can leave a note about your findings so far. -- **Do not comment on closed issues**. It is very unlikely that we are going to notice your comment in such a case. If the issue has been closed, but the proposed solution doesn't work for you, please open a new one providing all the information necessary and linking to the solution you have tried. - -## It's not a bug, it's a feature - -- Changing `enabled` prop during a gesture has no effect, only when a gesture starts (that is a finger touches the screen) the `enabled` prop is taken into consideration to decide whether to extract (or not) the gesture and provide it with stream of events to analyze. -- `Native` gesture may not conform to the standard state flow due to platform specific workarounds to incorporate native views into RNGH. -- Keep in mind that `Touchables` from RNGH are rendering two additional views that may need to be styled separately to achieve desired effect (`style` and `containerStyle` props). -- In order for the gesture composition to work, all composed gestures must be attached to the same `GestureHandlerRootView`. diff --git a/docs/versioned_docs/version-2.1.1/under-the-hood/how-does-it-work.md b/docs/versioned_docs/version-2.1.1/under-the-hood/how-does-it-work.md deleted file mode 100644 index aebed78316..0000000000 --- a/docs/versioned_docs/version-2.1.1/under-the-hood/how-does-it-work.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -id: how-does-it-work -title: How does it work? -sidebar_label: How does it work? ---- - -### Units - -All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". -These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://facebook.github.io/react-native/docs/flexbox.html)). -They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. - -## iOS - -All gestures are implemented using [UIGestureRecognizers](https://developer.apple.com/documentation/uikit/uigesturerecognizer?language=objc), some of them have been slightly modified to allow for more customization and to conform to the state flow of RNGH. When you assign a gesture configuration to the `GestureDetector`, it creates all the required recognizers and assigns them to the child view of the detector. From this point most of the heavy lifting is handled by the [UIKit](https://developer.apple.com/documentation/uikit?language=objc) (with our help to correctly implement interactions between gestures). - -## Android - -Unfortunately, Android doesn't provide an easy way of handling gestures hence most of them were implemented from scratch, including a system for managing how the gestures should interact with each other. Here's a quick overview of how it works: -When you wrap a component with `GestureHandlerRootView` it allows for the RNGH to intercept all touch events on that component and process them, deciding whether they should be handled by one of the gesture handlers or passed to the underlying view. Gesture handlers are created when you assign a gesture configuration to the `GestureDetector`, it initializes all of the necessary handlers natively. Every `GestureHandlerRootView` also has a specific handler to decide whether to pass the touch events or to consume them. It can never activate, only begin, end or be cancelled. When this handler is in the `UNDETERMINED` state it means that there is no touch in progress, however when the touch starts it transitions to the `BEGAN` state. As long as it stays in that state, no touch event is consumed, but as soon as it gets cancelled (meaning that some handler has activated) all incoming touch events get consumed, preventing underlying view from receiving them. - -When a pointer touches the screen the view tree is traversed in order to extract all handlers attached to the views below the finger (including the one attached to the `GestureHandlerRootView`) and all extracted handlers transition to the `BEGAN` state, signalling that the gesture may heve began. The touch events continue to be delivered to all extracted handlers until one of them recognizes the gesture and tries to activate. At this point the orchestrator checks whether this gesture should wait for any other of the extracted gestures to fail. If it does, it's put to the waiting list, if it doesn't, it gets activated and all other gestures (that are not simultaneous with it) get cancelled. When a gesture handlers transitions to a finished state (the gesture recognized by it stops, it fails or gets cancelled) the orchestrator check the waiting handlers. Every one of them that waited for the gesture that just failed tries to activate again (and again the orchestrator checks if it should wait for any of the extracted gestures...). diff --git a/docs/versioned_docs/version-2.1.1/whats-new.md b/docs/versioned_docs/version-2.1.1/whats-new.md deleted file mode 100644 index ffafefa857..0000000000 --- a/docs/versioned_docs/version-2.1.1/whats-new.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -id: whats-new -title: What's new in 2.0 -sidebar_label: What's new in 2.0 ---- - -RNGH2 introduces a new way of creating gestures. Instead of creating a gesture handler component for every gesture you want to create, you just need to create a `GestureDetector` component and assign to it all the gestures you want it to recognize. It is also designed to work seamlessly with `Reanimated 2` and it will automatically detect if it is installed, and start using it if it is. -You can create gestures using the `Gesture` object and methods it provides, and configure them in the builder-like pattern. If you want to specify behavior between the gestures instead of using `waitFor` and `simultaneousGestures` you can use the new system of [gesture composition](./gesture-composition). -Along the new API, version 2.0 brings one of the most requested features: [touch events and manual gestures](manual-gestures). Thanks to great work done by the Reanimated team, we were able to provide synchronous communication between gestures and their native implementation using worklets. This allows to manage gesture state from the JS without risking race-conditions. - -### Interoperability with gesture handlers - -The new API with gestures is somewhat compatible with the old gesture handlers. Unfortunately you cannot use the new gesture composing with gesture handlers, however you can still mark relations using refs. If you want to make a gesture handler wait for (or simultaneous with) a gesture, simply use withRef method on the gesture to set the ref object and pass it to the appropriate property on the gesture handler. - -Similarly, if you want to make a gesture simultaneous with (or wait for failure of) a gesture handler, set the ref prop of the gesture handler and pass the same ref to the simultaneousWithExternalGesture or requireExternalGestureToFail method on the gesture object. - -This should allow you to migrate your codebase from the gesture handlers to gestures smoothly and at your own pace. Just keep in mind that the gesture handlers cannot have the GestureDetector as their direct child, as it's a functional component. diff --git a/docs/versioned_docs/version-2.3.0/api/components/buttons.mdx b/docs/versioned_docs/version-2.3.0/api/components/buttons.mdx deleted file mode 100644 index ac8657a5eb..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/components/buttons.mdx +++ /dev/null @@ -1,170 +0,0 @@ ---- -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` -- `RectButton` -- `BorderlessButton` - -On top of that all the buttons are wrapped with `NativeViewGestureHandler` and therefore allow for all the [common gesture handler properties](#common-gesturehandler-properties) and `NativeViewGestureHandler`'s [extra properties](#nativeviewgesturehandler-extra-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). - -### `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`. - -## `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`](#basebutton-component), 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`](#basebutton-component), 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/docs/versioned_docs/version-2.3.0/api/components/swipeable.md b/docs/versioned_docs/version-2.3.0/api/components/swipeable.md deleted file mode 100644 index 18fb7dfe78..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/components/swipeable.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -id: swipeable -title: Swipeable -sidebar_label: Swipeable ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import GifGallery from '@site/components/GifGallery' - - - - - -This component 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: - -Similarly to the `DrawerLayout`, `Swipeable` component isn't exported by default from the `react-native-gesture-handler` package. To use it, import it in the following way: - -```js -import Swipeable from 'react-native-gesture-handler/Swipeable'; -``` - -## 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. - -### `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 method 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 method 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. - -### `onSwipeableLeftOpen` - -:::caution -This callback is deprecated and will be removed in the next version. Please use `onSwipeableOpen(direction)` -::: - -method that is called when left action panel gets open. - -### `onSwipeableRightOpen` - -:::caution -This callback is deprecated and will be removed in the next version. Please use `onSwipeableOpen(direction)` -::: - -method that is called when right action panel gets open. - -### `onSwipeableOpen` - -method that is called when action panel gets open (either right or left). Takes swipe direction as -an argument. - -### `onSwipeableClose` - -method that is called when action panel is closed. Takes swipe direction as -an argument. - -### `onSwipeableLeftWillOpen` - -:::caution -This callback is deprecated and will be removed in the next version. Please use `onSwipeableWillOpen(direction)` -::: - -method that is called when left action panel starts animating on open. - -### `onSwipeableRightWillOpen` - -:::caution -This callback is deprecated and will be removed in the next version. Please use `onSwipeableWillOpen(direction)` -::: - -method that is called when right action panel starts animating on open. - -### `onSwipeableWillOpen` - -method that is called when action panel starts animating on open (either right or left). Takes swipe direction as -an argument. - -### `onSwipeableWillClose` - -method that is called when action panel starts animating on close. Takes swipe direction as -an argument. - -### `renderLeftActions` - -method that is expected to return an action panel that is going to be revealed from the left side when user swipes right. -This map describes the values to use as inputRange for extra interpolation: -AnimatedValue: [startValue, endValue] - -progressAnimatedValue: [0, 1] -dragAnimatedValue: [0, +] - -To support `rtl` flexbox layouts use `flexDirection` styling. - -### `renderRightActions` - -method that is expected to return an action panel that is going to be revealed from the right side when user swipes left. -This map describes the values to use as inputRange for extra interpolation: -AnimatedValue: [startValue, endValue] - -progressAnimatedValue: [0, 1] -dragAnimatedValue: [0, -] - -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`. - -### `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. - -## Methods - -Using reference to `Swipeable` it's possible to trigger some actions on it - -### `close` - -method that closes component. - -### `openLeft` - -method that opens component on left side. - -### `openRight` - -method that opens component on right side. - -### Example: - -See the [swipeable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/showcase/swipeable/index.tsx) from GestureHandler Example App or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -import React, { Component } from 'react'; -import { Animated, StyleSheet, View } from 'react-native'; -import { RectButton } from 'react-native-gesture-handler'; -import Swipeable from 'react-native-gesture-handler/Swipeable'; - -class AppleStyleSwipeableRow extends Component { - renderLeftActions = (progress, dragX) => { - const trans = dragX.interpolate({ - inputRange: [0, 50, 100, 101], - outputRange: [-20, 0, 0, 1], - }); - return ( - - - Archive - - - ); - }; - render() { - return ( - - "hello" - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.3.0/api/components/touchables.md b/docs/versioned_docs/version-2.3.0/api/components/touchables.md deleted file mode 100644 index dff1719b63..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/components/touchables.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -id: touchables -title: Touchables -sidebar_label: Touchables ---- - -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://facebook.github.io/react-native/docs/touchablenativefeedback) -- [Touchable Highlight](https://facebook.github.io/react-native/docs/touchablehighlight) -- [Touchable Opacity](https://facebook.github.io/react-native/docs/touchableopacity) -- [Touchable Without Feedback](https://facebook.github.io/react-native/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. - -### 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/example/src/release_tests/touchables/index.tsx) diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/base-continous-gesture-callbacks.md b/docs/versioned_docs/version-2.3.0/api/gestures/base-continous-gesture-callbacks.md deleted file mode 100644 index 5504b2db8d..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/base-continous-gesture-callbacks.md +++ /dev/null @@ -1,9 +0,0 @@ -### Callbacks common to all continous gestures: - -### `onUpdate(callback)` - -Set the callback that is being called every time the gesture receives an update while it's active. - -### `onChange(callback)` - -Set the callback that is being called every time the gesture receives an update while it's active. This callback will receive information about change in value in relation to the last received event. diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/base-continous-gesture-config.md b/docs/versioned_docs/version-2.3.0/api/gestures/base-continous-gesture-config.md deleted file mode 100644 index a19473784e..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/base-continous-gesture-config.md +++ /dev/null @@ -1,5 +0,0 @@ -### Properties common to all continous gestures: - -### `manualActivation(value: boolead)` - -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](./state-manager.md). diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/base-gesture-callbacks.md b/docs/versioned_docs/version-2.3.0/api/gestures/base-gesture-callbacks.md deleted file mode 100644 index dff985b307..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/base-gesture-callbacks.md +++ /dev/null @@ -1,33 +0,0 @@ -### Callbacks common to all gestures: - -### `onBegin(callback)` - -Set the callback that is being called when given gesture handler starts receiving touches. At the moment of this callback the handler is not yet in an active state and we don't know yet if it will recognize the gesture at all. - -### `onStart(callback)` - -Set the callback that is being called when the gesture is recognized by the handler and it transitions to the active state. - -### `onEnd(callback)` - -Set the callback that is being called when the gesture that was recognized by the handler finishes. It will be called only if the handler was previously in the active state. - -### `onFinalize(callback)` - -Set the callback that is being called when the handler finalizes handling gesture - the gesture was recognized and has finished or it failed to recognize. - -### `onTouchesDown(callback)` - -Set the `onTouchesDown` callback which is called every time a finger is placed on the screen. - -### `onTouchesMove(callback)` - -Set the `onTouchesMove` callback which is called every time a finger is moved on the screen. - -### `onTouchesUp(callback)` - -Set the `onTouchesUp` callback which is called every time a finger is lifted from the screen. - -### `onTouchesCancelled(callback)` - -Set the `onTouchesCancelled` callback which is called every time a finger stops being tracked, for example when the gesture finishes. diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/base-gesture-config.md b/docs/versioned_docs/version-2.3.0/api/gestures/base-gesture-config.md deleted file mode 100644 index 7b0c6370a9..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/base-gesture-config.md +++ /dev/null @@ -1,54 +0,0 @@ -### 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`](../../under-the-hood/states-events.md#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`](../../under-the-hood/states-events.md#failed) or [`CANCELLED`](../../under-the-hood/states-events.md#cancelled) (depending on its current state). -Default value is `true`. - -### `shouldCancelWhenOutside(value: boolean)` - -When `true` the handler will [cancel](../../under-the-hood/states-events.md#cancelled) or [fail](../../under-the-hood/states-events.md#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`](./long-press-gesture.md) and [`TapGesture`](./tap-gesture.md) which default to `true`. - -### `hitSlop(settings)` - -This parameter enables control over what part of the connected view area can be used to [begin](../../under-the-hood/states-events.md#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://facebook.github.io/react-native/docs/view.html#props) 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. - -### `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](../../gesture-composition). [`GestureDetector`](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. - -**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](../../gesture-composition).[`GestureDetector`](gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/base-gesture-event-data.md b/docs/versioned_docs/version-2.3.0/api/gestures/base-gesture-event-data.md deleted file mode 100644 index 4d9056b1e5..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/base-gesture-event-data.md +++ /dev/null @@ -1,9 +0,0 @@ -### Event attributes common to all gestures: - -### `state` - -Current [state](.../../under-the-hood/states-events.md) 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. diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/composed-gestures.md b/docs/versioned_docs/version-2.3.0/api/gestures/composed-gestures.md deleted file mode 100644 index 84e2e451bd..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/composed-gestures.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: composed-gestures -title: Composed gestures -sidebar_label: Composed gestures ---- - -Composed gestures (`Race`, `Simultaneous`, `Exclusive`) provide a simple way of building relations between gestures. diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/force-touch-gesture.md b/docs/versioned_docs/version-2.3.0/api/gestures/force-touch-gesture.md deleted file mode 100644 index 8280f944b1..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/force-touch-gesture.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -id: force-touch-gesture -title: Force touch gesture (iOS only) -sidebar_label: Force touch gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-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](../../under-the-hood/states-events.md#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. - -There's no implementation provided on Android and it simply renders children without any wrappers. -Since this behaviour is only provided on some iOS devices, this gesture should not be used for defining any crucial behaviors. Use it only as an additional improvement and make all features to be accessed without this gesture as well. - -## Config - -### Properties specific to `ForceTouchGesture`: - -### `minForce(value: number)` - -A minimal pressure that is required before gesture can [activate](../../under-the-hood/states-events.md#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](../../under-the-hood/states-events.md#failed). Should be a value from range `[0.0, 1.0]`. - -### `feedbackOnActivation(value: boolean)` - -Value defining if haptic feedback has to be performed on activation. - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `ForceTouchGesture`: - -### `force` - -The pressure of a touch. - - diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/gesture-detector-functional1.md b/docs/versioned_docs/version-2.3.0/api/gestures/gesture-detector-functional1.md deleted file mode 100644 index 2397af9dfa..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/gesture-detector-functional1.md +++ /dev/null @@ -1,19 +0,0 @@ -```jsx -export default function Example() { - const tap = Gesture.Tap().onStart(() => { - console.log('tap'); - }); - - return ( - - - - - - ); -} - -function FunctionalComponent(props) { - return {props.children}; -} -``` diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/gesture-detector.md b/docs/versioned_docs/version-2.3.0/api/gestures/gesture-detector.md deleted file mode 100644 index ef8af9b62c..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/gesture-detector.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -id: gesture-detector -title: GestureDetector -sidebar_label: Gesture detector ---- - -import FunctionalComponents from './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.x/). - -:::caution -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. -::: - -## 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 synchrously. - -Starting with Reanimated-2.3.0-beta.4 Gesture Handler will provide a [StateManager](./state-manager.md) in the [touch events](./touch-events.md) that allows for managing the state of the gesture. -::: diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/gesture.md b/docs/versioned_docs/version-2.3.0/api/gestures/gesture.md deleted file mode 100644 index a84a48003a..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/gesture.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -id: gesture -title: Gesture -sidebar_label: Gesture ---- - -`Gesture` is the object that allows you to create and compose gestures. - -### Gesture.Tap() - -Creates a new instance of [`TapGesture`](./tap-gesture.md) with its default config and no callbacks. - -### Gesture.Pan() - -Creates a new instance of [`PanGesture`](./pan-gesture.md) with its default config and no callbacks. - -### Gesture.LongPress() - -Creates a new instance of [`LongPressGesture`](./long-press-gesture.md) with its default config and no callbacks. - -### Gesture.Fling() - -Creates a new instance of [`FlingGesture`](./fling-gesture.md) with its default config and no callbacks. - -### Gesture.Pinch() - -Creates a new instance of [`PinchGesture`](./pinch-gesture.md) with its default config and no callbacks. - -### Gesture.Rotation() - -Creates a new instance of [`RotationGesture`](./rotation-gesture.md) with its default config and no callbacks. - -### Gesture.ForceTouch() - -Creates a new instance of [`ForceTouchGesture`](./force-touch-gesture.md) with its default config and no callbacks. - -### Gesture.Manual() - -Creates a new instance of [`ManualGesture`](./manual-gesture.md) with its default config and no callbacks. - -### Gesture.Native() - -Creates a new instance of [`NativeGesture`](./native-gesture.md) with its default config and no callbacks. - -### Gesture.Race(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. Only one of those can become active and there are no restrictions to the activation of the gesture. The first one to activate will cancel all the others. - -### Gesture.Simultaneous(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. All of them can become active without cancelling the others. - -### Gesture.Exclusive(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. Only one of them can become active, but the first one has a higher priority than the second one, the second one has a higher priority than the third one, and so on. When all gestures are in the `BEGAN` state and the activation criteria for the second one is met, instead of activating it will wait until the first one fails (and only then it will activate) or until the first one activates (and then the second one will get cancelled). It is useful when you want to compose gestures with similar activation criteria (e.g. single and double tap at the same component, without Exclusive the single tap would activate every time user taps thus cancelling the double tap). diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/long-press-gesture.md b/docs/versioned_docs/version-2.3.0/api/gestures/long-press-gesture.md deleted file mode 100644 index 9f174d58e7..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/long-press-gesture.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -id: long-press-gesture -title: Long press gesture -sidebar_label: Long press gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './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](../../under-the-hood/states-events.md#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](#mindurationms) or if the finger is moved further than the [allowable distance](#maxdist). - -## Config - -### Properties specific to `LongPressGesture`: - -### `minDuration(value: number)` - -Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. - -### `maxDistance(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. The default value is 10. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `LongPressGesture`: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `duration` - -Duration of the long press (time since the start of the gesture), expressed in milliseconds. - - - -## Example - -```jsx -const longPressGesture = Gesture.LongPress().onEnd((e, success) => { - if (success) { - Alert.alert(`Long pressed for ${e.duration} ms!`); - } -}); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/manual-gesture.md b/docs/versioned_docs/version-2.3.0/api/gestures/manual-gesture.md deleted file mode 100644 index a92c6986ef..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/manual-gesture.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -id: manual-gesture -title: Manual gesture -sidebar_label: Manual gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A plain gesture that has no specific activation criteria nor event data set. Its state has to be controlled manually using a [state manager](./state-manager.md). It will not fail when all the pointers are lifted from the screen. - -## Config - - - -## Callbacks - - - - -## Event data - - diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/native-gesture.md b/docs/versioned_docs/version-2.3.0/api/gestures/native-gesture.md deleted file mode 100644 index 6fa7249eed..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/native-gesture.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -id: native-gesture -title: Native gesture -sidebar_label: Native gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A gesture that allows other touch handling components to participate in RNGH's gesture system. When used, the other component should be the direct child of a `GestureDetector`. - -## Config - -### Properties specific to `NativeGesture`: - -### `shouldActivateOnStart(value: boolean)` (**Android only**) - -When `true`, underlying handler will activate unconditionally when in `BEGAN` or `UNDETERMINED` state. - -### `disallowInterruption(value: boolean)` - -When `true`, cancels all other gesture handlers when this `NativeViewGestureHandler` receives an `ACTIVE` state event. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `NativeGesture`: - -### `pointerInside` - -True if gesture was performed inside of containing view, false otherwise. - - diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/pan-gesture.md b/docs/versioned_docs/version-2.3.0/api/gestures/pan-gesture.md deleted file mode 100644 index c8be974e7f..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/pan-gesture.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -id: pan-gesture -title: Pan gesture -sidebar_label: Pan gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that can recognize a panning (dragging) gesture and track its movement. - -The gesture [activates](../../under-the-hood/states-events.md#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. - -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. - -## 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. - -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 [`avgTouches`](#avgtouches-android-only) flag. - -Note that on both Android and iOS when the additional finger is placed on the screen that translation prop is not affected even though the position of the pointer being tracked might have changed. -Therefore it is safe to rely on translation most of the time as it only reflects the movement that happens regardless of how many fingers are placed on the screen and if that number changes over time. -If you wish to track the "center of mass" virtual pointer and account for its changes when the number of finger changes you can use relative or absolute position provided in the event ([`x`](#x) and [`y`](#y) or [`absoluteX`](#absolutex) and [`absoluteY`](#absolutey)). - -## Config - -### Properties specific to `PanGesture`: - -### `minDistance(value: number)` - -Minimum distance the finger (or multiple finger) need to travel before the gesture [activates](../../under-the-hood/states-events.md#active). Expressed in points. - -### `minPointers(value: number)` - -A number of fingers that is required to be placed before gesture can [activate](../../under-the-hood/states-events.md#active). Should be a higher or equal to 0 integer. - -### `maxPointers(value: number)` - -When the given number of fingers is placed on the screen and gesture hasn't yet [activated](../../under-the-hood/states-events.md#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. - -### `activeOffsetX(value: number | number[])` - -Range along X axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `activeOffsetY(value: number | number[])` - -Range along Y axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `failOffsetY(value: number | number[])` - -When the finger moves outside this range (in points) along Y axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `failOffsetX(value: number | number[])` - -When the finger moves outside this range (in points) along X axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `averageTouches(value: boolean)` (Android only) - -### `enableTrackpadTwoFingerGesture(value: boolean)` (iOS only) - -Enables two-finger gestures on supported devices, for example iPads with trackpads. If not enabled the gesture will require click + drag, with enableTrackpadTwoFingerGesture swiping with two fingers will also trigger the gesture. - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `PanGesture`: - -### `translationX` - -Translation of the pan gesture along X axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `translationY` - -Translation of the pan gesture along Y axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `velocityX` - -Velocity of the pan gesture along the X axis in the current moment. The value is expressed in point units per second. - -### `velocityY` - -Velocity of the pan gesture along the Y axis in the current moment. The value is expressed in point units per second. - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - - - -## Example - -```jsx -const END_POSITION = 200; -const onLeft = useSharedValue(true); -const position = useSharedValue(0); - -const panGesture = Gesture.Pan() - .onUpdate((e) => { - if (onLeft.value) { - position.value = e.translationX; - } else { - position.value = END_POSITION + e.translationX; - } - }) - .onEnd((e) => { - if (position.value > END_POSITION / 2) { - position.value = withTiming(END_POSITION, { duration: 100 }); - onLeft.value = false; - } else { - position.value = withTiming(0, { duration: 100 }); - onLeft.value = true; - } - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ translateX: position.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/pinch-gesture.md b/docs/versioned_docs/version-2.3.0/api/gestures/pinch-gesture.md deleted file mode 100644 index 5b56e7d043..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/pinch-gesture.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -id: pinch-gesture -title: Pinch gesture -sidebar_label: Pinch gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. -The gesture [activates](../../under-the-hood/states-events.md#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. - -## Config - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `PinchGesture`: - -### `scale` - -The scale factor relative to the points of the two touches in screen coordinates. - -### `velocity` - -Velocity of the pan gesture the current moment. The value is expressed in point units per second. - -### `focalX` - -Position expressed in points along X axis of center anchor point of gesture - -### `focalY` - -Position expressed in points along Y axis of center anchor point of gesture - - - -## Example - -```jsx -const scale = useSharedValue(1); -const savedScale = useSharedValue(1); - -const pinchGesture = Gesture.Pinch() - .onUpdate((e) => { - scale.value = savedScale.value * e.scale; - }) - .onEnd(() => { - savedScale.value = scale.value; - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ scale: scale.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/rotation-gesture.md b/docs/versioned_docs/version-2.3.0/api/gestures/rotation-gesture.md deleted file mode 100644 index 6550e0ea98..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/rotation-gesture.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -id: rotation-gesture -title: Rotation gesture -sidebar_label: Rotation gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that can recognize a rotation gesture and track its movement. - -The gesture [activates](../../under-the-hood/states-events.md#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. - -## Config - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `RotationGesture`: - -### `rotation` - -Amount rotated, expressed in radians, from the gesture's focal point (anchor). - -### `velocity` - -Instantaneous velocity, expressed in point units per second, of the gesture. - -### `anchorX` - -X coordinate, expressed in points, of the gesture's central focal point (anchor). - -### `anchorY` - -Y coordinate, expressed in points, of the gesture's central focal point (anchor). - - - -## Example - -```jsx -const rotation = useSharedValue(1); -const savedRotation = useSharedValue(1); - -const rotationGesture = Gesture.Rotation() - .onUpdate((e) => { - rotation.value = savedRotation.value + e.rotation; - }) - .onEnd(() => { - savedRotation.value = rotation.value; - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ rotateZ: `${(rotation.value / Math.PI) * 180}deg` }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/state-manager.md b/docs/versioned_docs/version-2.3.0/api/gestures/state-manager.md deleted file mode 100644 index cb50e8212b..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/state-manager.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: state-manager -title: Gesture state manager -sidebar_label: Gesture state manager ---- - -`GestureStateManager` allows to manually control the state of the gestures. Please note that `react-native-reanimated` is required to use it, since it allows for synchronously executing methods in worklets. - -## Methods - -### `begin()` - -Transition the gesture to the [`BEGAN`](../../under-the-hood/states-events.md#began) state. This method will have no effect if the gesture has already activated or finished. - -### `activate()` - -Transition the gesture to the [`ACTIVE`](../../under-the-hood/states-events.md#active) state. This method will have no effect if the handler is already active, or has finished. -If the gesture is [`exclusive`](../../gesture-composition) with another one, the activation will be delayed until the gesture with higher priority fails. - -### `end()` - -Transition the gesture to the [`END`](../../under-the-hood/states-events.md#end) state. This method will have no effect if the handler has already finished. - -### `fail()` - -Transition the gesture to the [`FAILED`](../../under-the-hood/states-events.md#failed) state. This method will have no effect if the handler has already finished. diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/tap-gesture.md b/docs/versioned_docs/version-2.3.0/api/gestures/tap-gesture.md deleted file mode 100644 index b0eb8216ea..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/tap-gesture.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -id: tap-gesture -title: Tap gesture -sidebar_label: Tap gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; - -A discrete gesture that recognizes one or many taps. - -Tap gestures detect one or more fingers briefly touching the screen. -The fingers involved in these gestures must not move significantly from their initial touch positions. -The required number of taps and allowed distance from initial position may be configured. -For example, you might configure tap gesture recognizers to detect single taps, double taps, or triple taps. - -In order for a gesture to [activate](../../under-the-hood/states-events.md#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the gesture [activates](../../under-the-hood/states-events.md#active), it will [end](../../under-the-hood/states-events.md#end). - -## Config - -### Properties specific to `TapGesture`: - -### `minPointers(value: number)` - -Minimum number of pointers (fingers) required to be placed before the gesture [activates](../../under-the-hood/states-events.md#active). Should be a positive integer. The default value is 1. - -### `maxDuration(value: number)` - -Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch. The default value is 500. - -### `maxDelay(value: number)` - -Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required. The default value is 500. - -### `numberOfTaps(value: number)` - -Number of tap gestures required to [activate](../../under-the-hood/states-events.md#active) the gesture. The default value is 1. - -### `maxDeltaX(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the X axis during a tap gesture. If the finger travels further than the defined distance along the X axis and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - -### `maxDeltaY(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the Y axis during a tap gesture. If the finger travels further than the defined distance along the Y axis and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - -### `maxDistance(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a tap gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `TapGesture`: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - - - -## Example - -```jsx -const singleTap = Gesture.Tap() - .maxDurationMs(250) - .onStart(() => { - Alert.alert('Single tap!'); - }); - -const doubleTap = Gesture.Tap() - .maxDurationMs(250) - .onStart(() => { - Alert.alert('Double tap!'); - }); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.3.0/api/gestures/touch-events.md b/docs/versioned_docs/version-2.3.0/api/gestures/touch-events.md deleted file mode 100644 index 58103d7b25..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/gestures/touch-events.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -id: touch-events -title: Touch events -sidebar_label: Touch events ---- - -### Touch event attributes: - -### `eventType` - -Type of the current event - whether the finger was placed on the screen, moved, lifted or cancelled. - -### `changedTouches` - -An array of objects where every object represents a single touch. Contains information only about the touches that were affected by the event i.e. those that were placed down, moved, lifted or cancelled. - -### `allTouches` - -An array of objects where every object represents a single touch. Contains information about all active touches. - -### `numberOfTouches` - -Number representing the count of currently active touches. - -:::caution -Don't rely on the order of items in the `touches` as it may change during the gesture, instead use the `id` attribute to track individual touches across events. -::: - -### PointerData attributes: - -### `id` - -A number representing id of the touch. It may be used to track the touch between events as the id will not change while it is being tracked. - -### `x` - -X coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the touch relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the touch relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. diff --git a/docs/versioned_docs/version-2.3.0/api/test-api.md b/docs/versioned_docs/version-2.3.0/api/test-api.md deleted file mode 100644 index 2eacd0c711..0000000000 --- a/docs/versioned_docs/version-2.3.0/api/test-api.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -id: test-api -title: Testing ---- - -:::info -If you want to use `fireGestureHandler` and `getByGestureTestId`, you need to import them from `react-native-gesture-handler/jest-utils` package. -::: - -## fireGestureHandler(gestureOrHandler, eventList) - -Simulates one event stream (i.e. event sequence starting with `BEGIN` state and ending -with one of `END`/`FAIL`/`CANCEL` states), calling appropriate callbacks associated with given gesture handler. - -### Arguments - -#### `gestureOrHandler` - -Represents either: - -1. Gesture handler component found by Jest queries (e.g. `getByTestId`) -2. Gesture found by [`getByGestureTestId()`](#getbygestureidtestid) - -#### `eventList` - -Event data passed to appropriate callback. RNGH fills event list if required -data is missing using these rules: - -1. `oldState` is filled using state of the previous event. `BEGIN` events use - `UNDETERMINED` value as previous event. -2. Events after first `ACTIVE` state can omit `state` field. -3. Handler specific data is filled (e.g. `numberOfTouches`, `x` fields) with - defaults. -4. Missing `BEGIN` and `END` events are added with data copied from first and last - passed event, respectively. -5. If first event don't have `state` field, the `ACTIVE` state is assumed. - -Some examples: - -```jsx -const oldStateFilled = [ - { state: State.BEGAN }, - { state: State.ACTIVE }, - { state: State.END }, -]; // three events with specified state are fired. - -const implicitActiveState = [ - { state: State.BEGAN }, - { state: State.ACTIVE }, - { x: 5 }, - { state: State.END }, -]; // 4 events, including two ACTIVE events (second one has overriden additional data). - -const implicitBegin = [ - { x: 1, y: 11 }, - { x: 2, y: 12, state: State.FAILED }, -]; // 3 events, including implicit BEGAN, one ACTIVE, and one FAILED event with additional data. - -const implicitBeginAndEnd = [ - { x: 5, y: 15 }, - { x: 6, y: 16 }, - { x: 7, y: 17 }, -]; // 5 events, including 3 ACTIVE events and implicit BEGAN and END events. BEGAN uses first event's additional data, END uses last event's additional data. - -const allImplicits = []; // 3 events, one BEGIN, one ACTIVE, one END with defaults. -``` - -### Example - -Extracted from RNGH tests, check `Events.test.tsx` for full implementation. - -```tsx -it('sends events with additional data to handlers', () => { - const panHandlers = mockedEventHandlers(); - render(); - fireGestureHandler(getByGestureTestId('pan'), [ - { state: State.BEGAN, translationX: 0 }, - { state: State.ACTIVE, translationX: 10 }, - { translationX: 20 }, - { translationX: 20 }, - { state: State.END, translationX: 30 }, - ]); - - expect(panHandlers.active).toBeCalledTimes(3); - expect(panHandlers.active).toHaveBeenLastCalledWith( - expect.objectContaining({ translationX: 20 }) - ); -}); -``` - -## getByGestureTestId(testID) - -Returns opaque data type associated with gesture. Gesture is found via `testID` attribute in rendered -components (see [`withTestID` method](./gestures/base-gesture-config.md#withrefref)). - -### Arguments - -#### `testID` - -String identifying gesture. - -### Notes - -`testID` must be unique among components rendered in test. - -### Example - -See above example for `fireGestureHandler`. diff --git a/docs/versioned_docs/version-2.3.0/gesture-composition.md b/docs/versioned_docs/version-2.3.0/gesture-composition.md deleted file mode 100644 index e55e06fae6..0000000000 --- a/docs/versioned_docs/version-2.3.0/gesture-composition.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -id: gesture-composition -title: Composing gestures -sidebar_label: Composing gestures ---- - -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 -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 -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 -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 ( - - - -); -``` - -## Composition vs `simultaneousWithExternalGesture` and `requireExternalGestureToFail` - -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. If you want to make a relation between gestures that are attached to separate `GestureDetectors`, we have a separate mechanism for that: `simultaneousWithExternalGesture` and `requireExternalGestureToFail` methods that are available on every base gesture. They work exactly the same way as `simultaneousHandlers` and `waitFor` on gesture handlers, that is they just mark the relation between the gestures without joining them into single object. diff --git a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/common-gh.md b/docs/versioned_docs/version-2.3.0/gesture-handlers/api/common-gh.md deleted file mode 100644 index d003c0dde2..0000000000 --- a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/common-gh.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -id: common-gh -title: Common handler properties -sidebar_label: Common handler properties ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -This page covers the common set of properties all gesture handler components expose. - -### Units - -All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". -These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://facebook.github.io/react-native/docs/flexbox.html)). -They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. - -## Properties - -This section describes properties that can be used with all gesture handler components: - -### `enabled` - -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`](../basics/state.md#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`](../basics/state.md#failed) or [`CANCELLED`](../basics/state.md#cancelled) (depending on its current state). -Default value is `true`. - -### `shouldCancelWhenOutside` - -Accepts a boolean value. -When `true` the handler will [cancel](../basics/state.md#cancelled) or [fail](../basics/state.md#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.md) and [`TapGestureHandler`](./tap-gh.md) 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](../basics/state.md#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](../basics/state.md#active) state. It will also prevent the provided handlers from [cancelling](../basics/state.md#cancelled) the current handler when they [activate](../basics/state.md#active). Read more in the [cross handler interaction](../basics/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](../basics/state.md#active) as long as the handlers provided by their refs are in the [`BEGAN`](../basics/state.md#began) state. Read more in the [cross handler interaction](../basics/interactions.md#awaiting-other-handlers) section. - -### `hitSlop` - -This parameter enables control over what part of the connected view area can be used to [begin](../basics/state.md#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://facebook.github.io/react-native/docs/view.html#props) property. - -### `onGestureEvent` - -Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](../basics/state.md#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.md#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://facebook.github.io/react-native/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](../basics/state.md) 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](../basics/state.md) of the handler right before the change. - -Instead of a callback [`Animated.event`](https://facebook.github.io/react-native/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. - -## Event data - -This section describes the attributes of event object being provided to [`onGestureEvent`](#ongestureevent) and [`onHandlerStateChange`](#onhandlerstatechange) callbacks: - -### `state` - -Current [state](../basics/state.md) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](../basics/state.md) to learn more about how to use it. - -### `numberOfPointers` - -Represents the number of pointers (fingers) currently placed on the screen. diff --git a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/create-native-wrapper.md b/docs/versioned_docs/version-2.3.0/gesture-handlers/api/create-native-wrapper.md deleted file mode 100644 index a33fd58d36..0000000000 --- a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/create-native-wrapper.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: create-native-wrapper -title: createNativeWrapper -sidebar_label: createNativeWrapper() ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -Creates provided component with NativeViewGestureHandler, allowing it to be part of RNGH's -gesture system. - -## Arguments - -### Component - -The component we want to wrap. - -### config - -Config is an object with properties that can be used on [`NativeViewGestureHandler`](./nativeview-gh.md) - -## Returns - -Wrapped component. diff --git a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/fling-gh.md b/docs/versioned_docs/version-2.3.0/gesture-handlers/api/fling-gh.md deleted file mode 100644 index b356e09cc0..0000000000 --- a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/fling-gh.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -id: fling-gh -title: FlingGestureHandler -sidebar_label: Fling ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A discrete gesture handler that activates when the movement is sufficiently long and fast. -Handler gets [ACTIVE](../basics/state#active) when movement is sufficiently long and it does not take too much time. -When handler gets activated it will turn into [END](../basics/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](./common-gh.md#properties). Below is a list of properties specific to `FlingGestureHandler` component: - -### `direction` - -Expressed allowed direction of movement. It's possible to pass one or many directions in one parameter: - -```js -direction={Directions.RIGHT | Directions.LEFT} -``` - -or - -```js -direction={Directions.DOWN} -``` - -### `numberOfPointers` - -Determine exact number of points required to handle the fling gesture. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `FlingGestureHandler`: - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - -## Example - -See the [fling example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/release_tests/fling/index.tsx) from Gesture Handler Example App. - -```js -const LongPressButton = () => ( - { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert("I'm flinged!"); - } - }}> - - -); -``` diff --git a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/nativeview-gh.md b/docs/versioned_docs/version-2.3.0/gesture-handlers/api/nativeview-gh.md deleted file mode 100644 index d515560d36..0000000000 --- a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/nativeview-gh.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: nativeview-gh -title: NativeViewGestureHandler -sidebar_label: NativeView ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A gesture handler that allows other touch handling components to participate in -RNGH's gesture system. - -Used by [`createNativeWrapper()`](./create-native-wrapper.md). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to `NativeViewGestureHandler` component: - -### `shouldActivateOnStart` (**Android only**) - -When `true`, underlying handler will activate unconditionally when in `BEGAN` or `UNDETERMINED` state. - -### `disallowInterruption` - -When `true`, cancels all other gesture handlers when this `NativeViewGestureHandler` receives an `ACTIVE` state event. diff --git a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/pan-gh.md b/docs/versioned_docs/version-2.3.0/gesture-handlers/api/pan-gh.md deleted file mode 100644 index 6ed5dc35e7..0000000000 --- a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/pan-gh.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -id: pan-gh -title: PanGestureHandler -sidebar_label: Pan ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A continuous gesture handler that can recognize a panning (dragging) gesture and track its movement. - -The handler [activates](../basics/state.md#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. - -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. - -The handler is implemented using [UIPanGestureRecognizer](https://developer.apple.com/documentation/uikit/uipangesturerecognizer) on iOS and [PanGestureHandler](https://github.com/software-mansion/react-native-gesture-handler/blob/main/android/lib/src/main/java/com/swmansion/gesturehandler/PanGestureHandler.java) on Android. - -## 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](../basics/state.md#active) or [fail](../basics/state.md#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. -Another example would be setting both [`maxDeltaX`](#maxdeltaX) and [`maxDeltaY`](#maxdeltay) to 20 and [`minDist`](#mindist) to 23. -In such a case, if we move a finger along the X-axis by 20 points and along the Y-axis by 0 points, the handler will fail even though the finger is still within the bounds of translation along Y-axis. - -## 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. - -The default behavior for native components like scroll view, pager views or drawers is different and hence gesture handler 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 [`avgTouches`](#avgtouches-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)). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#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](../basics/state.md#active). Expressed in points. - -### `minPointers` - -A number of fingers that is required to be placed before handler can [activate](../basics/state.md#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](../basics/state.md#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. - -### `activeOffsetX` - -Range along X axis (in points) where fingers travels without activation of handler. Moving outside of this range implies activation of handler. 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` - -Range along Y axis (in points) where fingers travels without activation of handler. Moving outside of this range implies activation of handler. 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` - -When the finger moves outside this range (in points) along Y axis and handler 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` - -When the finger moves outside this range (in points) along X axis and handler 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. - -### `maxDeltaX` - -> 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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#active) for the movement in one particular direction use [`minOffsetY`](#minoffsety) instead. - -### `avgTouches` (Android only) - -### `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. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `PanGestureHandler`: - -### `translationX` - -Translation of the pan gesture along X axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `translationY` - -Translation of the pan gesture along Y axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `velocityX` - -Velocity of the pan gesture along the X axis in the current moment. The value is expressed in point units per second. - -### `velocityY` - -Velocity of the pan gesture along the Y axis in the current moment. The value is expressed in point units per second. - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - -## Example - -See the [draggable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/draggable/index.tsx) from Gesture Handler Example App. - -```js -const circleRadius = 30; -class Circle extends Component { - _touchX = new Animated.Value(windowWidth / 2 - circleRadius); - _onPanGestureEvent = Animated.event([{ nativeEvent: { x: this._touchX } }], { - useNativeDriver: true, - }); - render() { - return ( - - - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/pinch-gh.md b/docs/versioned_docs/version-2.3.0/gesture-handlers/api/pinch-gh.md deleted file mode 100644 index d587fbd1aa..0000000000 --- a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/pinch-gh.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: pinch-gh -title: PinchGestureHandler -sidebar_label: Pinch ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) 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](../basics/state.md#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. - -The handler is implemented using [UIPinchGestureRecognizer](https://developer.apple.com/documentation/uikit/uipinchgesturerecognizer) on iOS and from scratch on Android. - -## Properties - -Properties provided to `PinchGestureHandler` do not extend [common set of properties from base handler class](./common-gh.md#properties). - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `PinchGestureHandler`: - -### `scale` - -The scale factor relative to the points of the two touches in screen coordinates. - -### `velocity` - -Velocity of the pan gesture the current moment. The value is expressed in point units per second. - -### `focalX` - -Position expressed in points along X axis of center anchor point of gesture - -### `focalY` - -Position expressed in points along Y axis of center anchor point of gesture - -## Example - -See the [scale and rotation example](hhttps://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from Gesture Handler Example App. - -```js -export class PinchableBox extends React.Component { - _baseScale = new Animated.Value(1); - _pinchScale = new Animated.Value(1); - _scale = Animated.multiply(this._baseScale, this._pinchScale); - _lastScale = 1; - _onPinchGestureEvent = Animated.event( - [{ nativeEvent: { scale: this._pinchScale } }], - { useNativeDriver: USE_NATIVE_DRIVER } - ); - - _onPinchHandlerStateChange = (event) => { - if (event.nativeEvent.oldState === State.ACTIVE) { - this._lastScale *= event.nativeEvent.scale; - this._baseScale.setValue(this._lastScale); - this._pinchScale.setValue(1); - } - }; - - render() { - return ( - - - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/rotation-gh.md b/docs/versioned_docs/version-2.3.0/gesture-handlers/api/rotation-gh.md deleted file mode 100644 index 862e703afe..0000000000 --- a/docs/versioned_docs/version-2.3.0/gesture-handlers/api/rotation-gh.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -id: rotation-gh -title: RotationGestureHandler -sidebar_label: Rotation ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A continuous gesture handler that can recognize a rotation gesture and track its movement. - -The handler [activates](../basics/state.md#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. - -The handler is implemented using [UIRotationGestureRecognizer](https://developer.apple.com/documentation/uikit/uirotationgesturerecognizer) on iOS and from scratch on Android. - -## Properties - -Properties provided to `RotationGestureHandler` do not extend [common set of properties from base handler class](./common-gh.md#properties). - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `RotationGestureHandler`: - -### `rotation` - -Amount rotated, expressed in radians, from the gesture's focal point (anchor). - -### `velocity` - -Instantaneous velocity, expressed in point units per second, of the gesture. - -### `anchorX` - -X coordinate, expressed in points, of the gesture's central focal point (anchor). - -### `anchorY` - -Y coordinate, expressed in points, of the gesture's central focal point (anchor). - -## Example - -See the [scale and rotation example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from Gesture Handler Example App. - -```js -class RotableBox extends React.Component { - _rotate = new Animated.Value(0); - _rotateStr = this._rotate.interpolate({ - inputRange: [-100, 100], - outputRange: ['-100rad', '100rad'], - }); - _lastRotate = 0; - _onRotateGestureEvent = Animated.event( - [{ nativeEvent: { rotation: this._rotate } }], - { useNativeDriver: USE_NATIVE_DRIVER } - ); - _onRotateHandlerStateChange = (event) => { - if (event.nativeEvent.oldState === State.ACTIVE) { - this._lastRotate += event.nativeEvent.rotation; - this._rotate.setOffset(this._lastRotate); - this._rotate.setValue(0); - } - }; - render() { - return ( - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.3.0/gesture-handlers/basics/about-handlers.md b/docs/versioned_docs/version-2.3.0/gesture-handlers/basics/about-handlers.md deleted file mode 100644 index 4c2062a24f..0000000000 --- a/docs/versioned_docs/version-2.3.0/gesture-handlers/basics/about-handlers.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -id: about-handlers -title: About Gesture Handlers -sidebar_label: About Gesture Handlers ---- - -Gesture handlers are the core building blocks of this library. -We use this term to describe elements of the native touch system that the library allows us to instantiate and control from Javascript using [React's Component](https://reactjs.org/docs/react-component.html) interface. - -Each handler type is capable of recognizing one type of gesture (pan, pinch, etc.) and provides gesture-specific information via events (translation, scale, 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](./state.md). -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](./state.md#active), it cancels all the other gestures (read more about how to influence this process in ["Cross handler interactions"](./interactions.md) 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. - -### Available gesture handlers - -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`](../api/pan-gh.md) -- [`TapGestureHandler`](../api/tap-gh.md) -- [`LongPressGestureHandler`](../api/longpress-gh.md) -- [`RotationGestureHandler`](../api/rotation-gh.md) -- [`FlingGestureHandler`](../api/fling-gh.md) -- [`PinchGestureHandler`](../api/pinch-gh.md) -- [`ForceTouchGestureHandler`](../api/force-gh.md) - -### Discrete vs continuous - -We distinguish between two types of gestures: discrete and continuous. - -Continuous gesture handlers can be [active](./state.md#active) for a long period of time and will generate a stream of [gesture events](../api/common-gh.md#ongestureevent) until the gesture is [over](./state.md#ended). -An example of a continuous handler is [`PanGestureHandler`](../api/pan-gh.md) that once [activated](./state.md#active), will start providing updates about [translation](../api/pan-gh.md#translationx) and other properties. - -On the other hand, discrete gesture handlers once [activated](./state.md#active) will not stay in the active state but will [end](./state.md#ended) immediately. -[`LongPressGestureHandler`](../api/longpress-gh.md) 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`](../api/pan-gh.md)). - -Keep in mind that `onGestureEvent` is only generated in continuous gesture handlers and shouldn't be used in the `TapGestureHandler` and other discrete handlers. - -### Nesting handlers - -Handler components can be nested. In any case it is recommended that the innermost handler renders a native view component. There are some limitations that apply when [using `useNativeDriver` flag](#events-with-usenativedriver). An example of nested handlers: - -```js -class Multitap extends Component { - render() { - return ( - - - - - - - - ); - } -} -``` - -### Using native components - -Gesture handler library exposes a set of components normally available in React Native that are wrapped in [`NativeViewGestureHandler`](../api/nativeview-gh.md). -Here is a list of exposed components: - -- `ScrollView` -- `FlatList` -- `Switch` -- `TextInput` -- `DrawerLayoutAndroid` (**Android only**) - -If you want to use other handlers or [buttons](../../api/components/buttons.mdx) nested in a `ScrollView`, use the [`waitFor`](../api/common-gh.md#waitfor) property to define interaction between a handler and `ScrollView` - -### Events with `useNativeDriver` - -Because handlers do not instantiate native views but instead hook up to their child views, directly nesting two gesture handlers using `Animated.event` is not currently supported. -To workaround this limitation we recommend placing an `` component in between the handlers. - -Instead of doing: - -```js -const PanAndRotate = () => ( - - - - - -); -``` - -Place an `` in between the handlers: - -```js -const PanAndRotate = () => ( - - - - - - - -); -``` - -Another consequence of handlers depending on their native child components is that when using a `useNativeDriver` flag with an `Animated.event`, the child component must be wrapped by an `Animated.API` e.g. `` instead of just a ``: - -```js -class Draggable extends Component { - render() { - return ( - - {/* <-- NEEDS TO BE Animated.View */} - - ); - } -}; -``` diff --git a/docs/versioned_docs/version-2.3.0/gesture-handlers/basics/interactions.md b/docs/versioned_docs/version-2.3.0/gesture-handlers/basics/interactions.md deleted file mode 100644 index 5b7408cf5f..0000000000 --- a/docs/versioned_docs/version-2.3.0/gesture-handlers/basics/interactions.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -id: interactions -title: Cross handler interactions -sidebar_label: Cross handler interactions ---- - -Gesture handlers can "communicate" with each other to support complex gestures and control how they _[activate](./state.md#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. -Gesture handler relies on ref objects created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html) and introduced in [React 16.3](https://reactjs.org/blog/2018/03/29/react-v-16-3.html#createref-api). - -## Simultaneous recognition - -By default, only one gesture handler is allowed to be in the [`ACTIVE`](./state.md#active) state. -So when a gesture handler recognizes a gesture it [cancels](./state.md#cancelled) all other handlers in the [`BEGAN`](./state.md#began) state and prevents any new handlers from receiving a stream of touch events as long as it remains [`ACTIVE`](./state.md#active). - -This behavior can be altered using the [`simultaneousHandlers`](../api/common-gh.md#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`](./state.md#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`](../api/pinch-gh.md), [`RotationGestureHandler`](../api/rotation-gh.md) and [`PanGestureHandler`](../api/pan-gh.md) that would have to simultaneously recognize gestures. - -### Example - -See the ["Scale, rotate & tilt" example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from the GestureHandler Example App or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -class PinchableBox extends React.Component { - // ...take a look on full implementation in an Example app - render() { - const imagePinch = React.createRef(); - const imageRotation = React.createRef(); - return ( - - - - - - - - - - ); - } -} -``` - -## Awaiting other handlers - -### Use cases - -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](./state.md#cancelled) the double tap handler. - -### Example - -See the ["Multitap" example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from GestureHandler Example App or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -const doubleTap = React.createRef(); -const PressBox = () => ( - - nativeEvent.state === State.ACTIVE && Alert.alert('Single tap!') - } - waitFor={doubleTap}> - - nativeEvent.state === State.ACTIVE && Alert.alert("You're so fast") - } - numberOfTaps={2}> - - - -); -``` diff --git a/docs/versioned_docs/version-2.3.0/gesture-handlers/basics/state.md b/docs/versioned_docs/version-2.3.0/gesture-handlers/basics/state.md deleted file mode 100644 index 1f15f94f2f..0000000000 --- a/docs/versioned_docs/version-2.3.0/gesture-handlers/basics/state.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: state -title: Handler State -sidebar_label: Handler State ---- - -As described in ["About Gesture Handlers"](./about-handlers.md), 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: - -- [UNDETERMINED](#undetermined) -- [FAILED](#failed) -- [BEGAN](#began) -- [CANCELLED](#cancelled) -- [ACTIVE](#active) -- [END](#end) - -Each state has its own description below. - -## Accessing state - -We can monitor a handler's state changes by using the [`onHandlerStateChange`](../api/common-gh.md#onhandlerstatechange) callback and the destructured `nativeEvent` argument passed to it. -This can be done by comparing the `nativeEvent`'s [`state`](../api/common-gh.md#state) attribute to one of the constants exported under the `State` object (see example below). - -``` -import { State, LongPressGestureHandler } from 'react-native-gesture-handler'; - -class Demo extends Component { - _handleStateChange = ({ nativeEvent }) => { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert('Longpress'); - } - }; - render() { - return ( - - Longpress me - - ); - } -} -``` - -## State flows - -The most typical flow of state is when a gesture handler picks up on an initial touch event then recognizes it then acknowledges its ending then resets itself back to the initial state. - -The flow looks as follows (longer arrows represent that there are possibly more touch events received before the state changes): - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`END`](#end) -> [`UNDETERMINED`](#undetermined) - -Another possible flow is when a handler receives touches that cause a recognition failure: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`FAILED`](#failed) -> [`UNDETERMINED`](#undetermined) - -At last, when a handler does properly recognize the gesture but then is interrupted by the touch system. In that case, the gesture recognition is canceled and the flow looks as follows: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`CANCELLED`](#cancelled) -> [`UNDETERMINED`](#undetermined) - -## States - -The section below describes all possible handler states: - -### UNDETERMINED - -This is the initial state of each handler and it goes into this state after it's done recognizing a gesture. - -### FAILED - -A handler 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 handler won't become active but will fail instead. Afterwards, it's state will be reset to `UNDETERMINED`. - -### BEGAN - -Handler 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 - -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](about-handlers#discrete-vs-continuous) to understand how long a handler can be kept in the `ACTIVE` state. - -### END - -The gesture recognizer has received touches signalling the end of a gesture. Its state will become `END` until it is reset to `UNDETERMINED`. diff --git a/docs/versioned_docs/version-2.3.0/guides/testing.md b/docs/versioned_docs/version-2.3.0/guides/testing.md deleted file mode 100644 index 980160bdbd..0000000000 --- a/docs/versioned_docs/version-2.3.0/guides/testing.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -id: testing -title: Testing with Jest ---- - -## Mocking native modules - -In order to load mocks provided by RNGH add following to your jest config in `package.json`: - -```json -"setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"] -``` - -Example: - -```json -"jest": { - "preset": "react-native", - "setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"] -} -``` - -## Testing Gestures' and Gesture handlers' callbacks - -RNGH provides an API for triggering selected handlers: - -- [`fireGestureHandler(gestureOrHandler, eventList)`](../api/test-api#firegesturehandlergestureorhandler-eventlist) -- [`getByGestureTestId(testID)`](../api/test-api#getbygesturetestidtestid) diff --git a/docs/versioned_docs/version-2.3.0/installation.md b/docs/versioned_docs/version-2.3.0/installation.md deleted file mode 100644 index 1a27889191..0000000000 --- a/docs/versioned_docs/version-2.3.0/installation.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -id: installation -title: Installation ---- - -## Requirements - -| version | `react-native` version | -| --------- | ---------------------- | -| 2.0.0+ | 0.63.0+ | -| 1.4.0+ | 0.60.0+ | -| 1.1.0+ | 0.57.2+ | -| <1.1.0 | 0.50.0+ | - -It may be possible to use newer versions of react-native-gesture-handler on React Native with version <= 0.59 by reverse Jetifying. -Read more on that here https://github.com/mikehardy/jetifier#to-reverse-jetify--convert-node_modules-dependencies-to-support-libraries - -Note that if you wish to use [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html) support for [interactions](./gesture-handlers/basics/interactions.md) you need to use v16.3 of [React](https://reactjs.org/) - -In order to fully utilize the [touch events](./api/gestures/touch-events.md) you also need to use `react-native-reanimated` 2.3.0-beta.4 or newer. - -## Expo - -### Managed [Expo](https://expo.io) - -To use the version of react-native-gesture-handler that is compatible with your managed Expo project, run `expo install react-native-gesture-handler`. - -The Expo SDK incorporates the latest version of react-native-gesture-handler available at the time of each SDK release, so managed Expo apps might not always support all our latest features as soon as they are available. - -### Bare [React Native](http://facebook.github.io/react-native/) - -Since the library uses native support for handling gestures, it requires an extended installation to the norm. If you are starting a new project, you may want to initialize it with [expo-cli](https://docs.expo.io/versions/latest/workflow/expo-cli/) and use a bare template, they come pre-installed with react-native-gesture-handler. - -## JS - -First, install the library using `yarn`: - -```bash -yarn add react-native-gesture-handler -``` - -or with `npm` if you prefer: - -```bash -npm install --save react-native-gesture-handler -``` - -After installation, wrap your entry point with `` or -`gestureHandlerRootHOC`. - -For example: - -```js -export default function App() { - return {/* content */}; -} -``` - -:::info -If you use props such as `shouldCancelWhenOutside`, `simultaneousHandlers`, `waitFor` etc. with gesture handlers, the handlers need to be mounted under a single `GestureHandlerRootView`. So it's important to keep the `GestureHandlerRootView` as close to the actual root view as possible. - -Note that `GestureHandlerRootView` acts like a normal `View`. So if you want it to fill the screen, you will need to pass `{ flex: 1 }` like you'll need to do with a normal `View`. By default, it'll take the size of the content nested inside. -::: - -:::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. -::: - -### Linking - -> **Important**: You only need to do this step if you're using React Native 0.59 or lower. Since v0.60, linking happens automatically. - -```bash -react-native link react-native-gesture-handler -``` - -## Fabric -Starting with version 2.3.0, Gesture Handler now supports [Fabric](https://reactnative.dev/docs/fabric-renderer)!. To use Gesture Handler in your Fabric application you have to: -#### on iOS: -Install pods using `RCT_NEW_ARCH_ENABLED=1 pod install` – this is the same command you run to prepare a Fabric build but you also need to run it after a new native library gets added. -#### on Android: -There are no additional steps required so long as your app is configured to build with Fabric – this is typically configured by setting `newArchEnabled=true` in `gradle.properties` file in your project. - -## Android - -### Usage with modals on Android - -On Android RNGH does not work by default because modals are not located under React Native Root view in native hierarchy. -To fix that, components need to be wrapped with `gestureHandlerRootHOC` (it's no-op on iOS and web). - -For example: - -```js -const ExampleWithHoc = gestureHandlerRootHOC(() => ( - - - - ); -); - -export default function Example() { - return ( - - - - ); -} -``` - -### Kotlin - -Since version `2.0.0` RNGH has been rewritten with Kotlin. The default version of the Kotlin plugin used in this library is `1.5.20`. - -If you need to use a different Kotlin version, set the `kotlinVersion` ext property in `android/build.gradle` file and RNGH will use that version: - -``` -buildscript { - ext { - ... - kotlinVersion = "1.5.20" - } -} -``` - -The minimal version of the Kotlin plugin supported by RNGH is `1.4.10`. - -## iOS - -There is no additional configuration required on iOS except what follows in the next steps. - -If you're in a CocoaPods project (the default setup since React Native 0.60), -make sure to install pods before you run your app: - -```bash -cd ios && pod install -``` - -For React Native 0.61 or greater, add the library as the first import in your index.js file: - -```js -import 'react-native-gesture-handler'; -``` diff --git a/docs/versioned_docs/version-2.3.0/introduction.md b/docs/versioned_docs/version-2.3.0/introduction.md deleted file mode 100644 index 7f436751cc..0000000000 --- a/docs/versioned_docs/version-2.3.0/introduction.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -id: introduction -title: Introduction -sidebar_label: Introduction -slug: / ---- - -Gesture Handler aims to replace React Native's built in touch system called [Gesture Responder System](http://facebook.github.io/react-native/docs/gesture-responder-system). - -The motivation for building this library was to address the performance limitations of React Native's Gesture Responder System and to provide more control over the built-in native components that can handle gestures. -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. - -In a nutshell, the library provides: - -- A way to use a platform's native touch handling system for recognizing pinch, rotation and pan (besides a few other gestures). -- The ability to define relations between gesture handlers, e.g. when you have a pan handler in `ScrollView` you can make that `ScrollView` wait until it knows pan won't recognize. -- Mechanisms to use touchables 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. - -:::info -It is recommended to use Reanimated 2 for animations when using React Native Gesture Handler as its more advanced features rely heavily on the worklets provided by Reanimated. -::: - -## RNGH 2.0 - -RNGH2 introduces a new way of creating gestures. Instead of creating a gesture handler component for every gesture you want to create, you just need to create a `GestureDetector` component and assign to it all the gestures you want it to recognize. It is also designed to work seamlessly with `Reanimated 2` and it will automatically detect if it is installed, and start using it if it is. -You can create gestures using the `Gesture` object and methods it provides, and configure them in the builder-like pattern. If you want to specify behavior between the gestures instead of using `waitFor` and `simultaneousGestures` you can use the new system of [gesture composition](./gesture-composition). -Along the new API, version 2.0 brings one of the most requested features: [touch events and manual gestures](manual-gestures). Thanks to great work done by the Reanimated team, we were able to provide synchronous communication between gestures and their native implementation using worklets. This allows to manage gesture state from the JS without risking race-conditions. - -### Interoperability with gesture handlers - -The new API with gestures is somewhat compatible with the old gesture handlers. Unfortunately you cannot use the new gesture composing with gesture handlers, however you can still mark relations using refs. If you want to make a gesture handler wait for (or simultaneous with) a gesture, simply use withRef method on the gesture to set the ref object and pass it to the appropriate property on the gesture handler. - -Similarly, if you want to make a gesture simultaneous with (or wait for failure of) a gesture handler, set the ref prop of the gesture handler and pass the same ref to the simultaneousWithExternalGesture or requireExternalGestureToFail method on the gesture object. - -This should allow you to migrate your codebase from the gesture handlers to gestures smoothly and at your own pace. Just keep in mind that the gesture handlers cannot have the GestureDetector as their direct child, as it's a functional component. - -## Learning resources - -### Apps - -[Gesture Handler Example App](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example) – official gesture handler "showcase" app. - -[Gesture Handler Example on Expo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo) – the official app you can install and play with using [Expo](https://expo.io). - -### 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 Vetne](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 [me on Twitter](https://twitter.com/kzzzf)! - -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
-
- -
-
- -
-
Jakub Gonet
-
- -
-
- -
-
Krzysztof Magiera
- @kzzzf -
- -
- -### 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: - -
- -
- -
- -
-
Shopify
- -
- -
- -
- -
-
Expo
- -
- -
diff --git a/docs/versioned_docs/version-2.3.0/manual-gestures/manual-gestures.md b/docs/versioned_docs/version-2.3.0/manual-gestures/manual-gestures.md deleted file mode 100644 index eae7fffd2d..0000000000 --- a/docs/versioned_docs/version-2.3.0/manual-gestures/manual-gestures.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -id: manual-gestures -title: Manual gestures -sidebar_label: Manual gestures ---- - -import Step, { Divider } from '@site/src/theme/Step'; -import Step1 from './step1.md'; -import Step2 from './step2.md'; -import Step3 from './step3.md'; -import Step4 from './step4.md'; -import Step5 from './step5.md'; -import Step6 from './step6.md'; -import Step7 from './step7.md'; - -RNGH2 finally brings one of the most requested features: manual gestures and touch events. To demonstrate how to make a manual gesture we will make a simple one that tracks all pointers on the screen. - - - - - First, we need a way to store information about the pointer: whether it should be visible and its position. - - - - - - - We also need a component to mark where a pointer is. In order to accomplish that we will make a component that accepts two shared values: one holding information about the pointer using the interface we just created, the other holding a bool indicating whether the gesture has activated. - In this example when the gesture is not active, the ball representing it will be blue and when it is active the ball will be red and slightly bigger. - - - - - - - Now we have to make a component that will handle the gesture and draw all the pointer indicators. We will store data about pointers in an array of size 12 as that is the maximum number of touches that RNGH will track, and render them inside an Animated.View. - - - - - - - We have our components set up and we can finally get to making the gesture! We will start with onTouchesDown where we need to set position of the pointers and make them visible. We can get this information from the touches property of the event. In this case we will also check how many pointers are on the screen and activate the gesture if there are at least two. - - - - - - - Next, we will handle pointer movement. In onTouchesMove we will simply update the position of moved pointers. - - - - - - - We also need to handle lifting fingers from the screen, which corresponds to onTouchesUp. Here we will just hide the pointers that were lifted and end the gesture if there are no more pointers on the screen. - Note that we are not handling onTouchesCancelled as in this very basic case we don't expect it to happen, however you should clear data about cancelled pointers (most of the time all active ones) when it is called. - - - - - - - Now that our pointers are being tracked correctly and we have the state management, we can handle activation and ending of the gesture. In our case, we will simply set the active shared value either to true or false. - - - - - -And that's all! As you can see using manual gestures is really easy but as you can imagine, manual gestures are a powerful tool that makes it possible to accomplish things that were previously impossible with RNGH. - -## Modifying existing gestures - -While manual gestures open great possibilities we are aware that reimplementing pinch or rotation from scratch just because you need to activate in specific circumstances or require position of the fingers, would be a waste of time as those gestures are already there. Because of that you can use touch events with every gesture so that you can extract more informations about gesture than is sent to you in events. We also added a `manualActivation` modifier on all continous gestures, which prevents the gesture it is applied to from activating by itself thus giving you full control of its behavior. - -This functionality makes another highly requested feature possible: drag after long press. Simply set `manualActivation` to `true` on a `PanGesture` and use `StateManager` to fail the gesture if the user attempts to drag the component sooner than the duration of the long press. diff --git a/docs/versioned_docs/version-2.3.0/manual-gestures/step1.md b/docs/versioned_docs/version-2.3.0/manual-gestures/step1.md deleted file mode 100644 index 4c6331c1c8..0000000000 --- a/docs/versioned_docs/version-2.3.0/manual-gestures/step1.md +++ /dev/null @@ -1,7 +0,0 @@ -```jsx -interface Pointer { - visible: boolean; - x: number; - y: number; -} -``` diff --git a/docs/versioned_docs/version-2.3.0/manual-gestures/step2.md b/docs/versioned_docs/version-2.3.0/manual-gestures/step2.md deleted file mode 100644 index 3137d334ef..0000000000 --- a/docs/versioned_docs/version-2.3.0/manual-gestures/step2.md +++ /dev/null @@ -1,35 +0,0 @@ -```jsx -function PointerElement(props: { - pointer: Animated.SharedValue, - active: Animated.SharedValue, -}) { - const animatedStyle = useAnimatedStyle(() => ({ - transform: [ - { translateX: props.pointer.value.x }, - { translateY: props.pointer.value.y }, - { - scale: - (props.pointer.value.visible ? 1 : 0) * - (props.active.value ? 1.3 : 1), - }, - ], - backgroundColor: props.active.value ? 'red' : 'blue', - })); - - return ; -} - -... - -const styles = StyleSheet.create({ - pointer: { - width: 60, - height: 60, - borderRadius: 30, - backgroundColor: 'red', - position: 'absolute', - marginStart: -30, - marginTop: -30, - }, -}); -``` diff --git a/docs/versioned_docs/version-2.3.0/manual-gestures/step3.md b/docs/versioned_docs/version-2.3.0/manual-gestures/step3.md deleted file mode 100644 index c9b32e5c2a..0000000000 --- a/docs/versioned_docs/version-2.3.0/manual-gestures/step3.md +++ /dev/null @@ -1,29 +0,0 @@ -```jsx -export default function Example() { - const trackedPointers: Animated.SharedValue[] = []; - const active = useSharedValue(false); - - for (let i = 0; i < 12; i++) { - trackedPointers[i] = - useSharedValue < - Pointer > - { - visible: false, - x: 0, - y: 0, - }; - } - - const gesture = Gesture.Manual(); - - return ( - - - {trackedPointers.map((pointer, index) => ( - - ))} - - - ); -} -``` diff --git a/docs/versioned_docs/version-2.3.0/manual-gestures/step4.md b/docs/versioned_docs/version-2.3.0/manual-gestures/step4.md deleted file mode 100644 index 36ec2c34bd..0000000000 --- a/docs/versioned_docs/version-2.3.0/manual-gestures/step4.md +++ /dev/null @@ -1,15 +0,0 @@ -```jsx {2-15} -const gesture = Gesture.Manual().onTouchesDown((e, manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: true, - x: touch.x, - y: touch.y, - }; - } - - if (e.numberOfTouches >= 2) { - manager.activate(); - } -}); -``` diff --git a/docs/versioned_docs/version-2.3.0/manual-gestures/step5.md b/docs/versioned_docs/version-2.3.0/manual-gestures/step5.md deleted file mode 100644 index d2f9377cc8..0000000000 --- a/docs/versioned_docs/version-2.3.0/manual-gestures/step5.md +++ /dev/null @@ -1,13 +0,0 @@ -```jsx {3-12} -const gesture = Gesture.Manual() - ... - .onTouchesMove((e, _manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: true, - x: touch.x, - y: touch.y, - }; - } - }) -``` diff --git a/docs/versioned_docs/version-2.3.0/manual-gestures/step6.md b/docs/versioned_docs/version-2.3.0/manual-gestures/step6.md deleted file mode 100644 index 323f9516cb..0000000000 --- a/docs/versioned_docs/version-2.3.0/manual-gestures/step6.md +++ /dev/null @@ -1,17 +0,0 @@ -```jsx {3-16} -const gesture = Gesture.Manual() - ... - .onTouchesUp((e, manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: false, - x: touch.x, - y: touch.y, - }; - } - - if (e.numberOfTouches === 0) { - manager.end(); - } - }) -``` diff --git a/docs/versioned_docs/version-2.3.0/manual-gestures/step7.md b/docs/versioned_docs/version-2.3.0/manual-gestures/step7.md deleted file mode 100644 index 913e766ae8..0000000000 --- a/docs/versioned_docs/version-2.3.0/manual-gestures/step7.md +++ /dev/null @@ -1,10 +0,0 @@ -```jsx {3-10} -const gesture = Gesture.Manual() - ... - .onStart(() => { - active.value = true; - }) - .onEnd(() => { - active.value = false; - }); -``` diff --git a/docs/versioned_docs/version-2.3.0/quickstart/quickstart.md b/docs/versioned_docs/version-2.3.0/quickstart/quickstart.md deleted file mode 100644 index c1ba3d7219..0000000000 --- a/docs/versioned_docs/version-2.3.0/quickstart/quickstart.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -id: quickstart -title: Quick start -sidebar_label: Quick start ---- - -import Step, { Divider } from '@site/src/theme/Step'; -import Step1 from './step1.md'; -import Step2 from './step2.md'; -import Step3 from './step3.md'; -import Step4 from './step4.md'; -import Step5 from './step5.md'; - -RNGH2 provides much simpler way to add gestures to your app. All you need to do is wrap the view that you want your gesture to work on with [`GestureDetector`](../api/gestures/gesture-detector), define the gesture and pass it to detector. That's all! - -To demonstrate how you would use the new API, let's make a simple app where you can drag a ball around. You will need to add `react-native-gesture-handler` (for gestures) and `react-native-reanimated` (for animations) modules. - - - - -
First let's define styles we will need to make the app:
- - - - - - -
Then we can start writing our `Ball` component:
- - - - - - -
- We also need to define{' '} - - shared values - {' '} - to keep track of the ball position and create animated styles in order to be - able to position the ball on the screen: -
- - - - - - -
And add it to the ball's styles:
- - - - - - -
- The only thing left is to define the pan gesture and assign it to the - detector: -
- - - - - -Note the `start` shared value. We need it to store the position of the ball at the moment we grab it to be able to correctly position it later, because we only have access to translation relative to the starting point of the gesture. - -Now you can just add `Ball` component to some view in the app and see the results! (Or you can just check the code [here](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/new_api/reanimated/index.tsx) and see it in action in the Example app.) diff --git a/docs/versioned_docs/version-2.3.0/quickstart/step1.md b/docs/versioned_docs/version-2.3.0/quickstart/step1.md deleted file mode 100644 index 1995cd907c..0000000000 --- a/docs/versioned_docs/version-2.3.0/quickstart/step1.md +++ /dev/null @@ -1,11 +0,0 @@ -```jsx -const styles = StyleSheet.create({ - ball: { - width: 100, - height: 100, - borderRadius: 100, - backgroundColor: 'blue', - alignSelf: 'center', - }, -}); -``` diff --git a/docs/versioned_docs/version-2.3.0/quickstart/step2.md b/docs/versioned_docs/version-2.3.0/quickstart/step2.md deleted file mode 100644 index 34c528266b..0000000000 --- a/docs/versioned_docs/version-2.3.0/quickstart/step2.md +++ /dev/null @@ -1,9 +0,0 @@ -```jsx -function Ball() { - return ( - - - - ); -} -``` diff --git a/docs/versioned_docs/version-2.3.0/quickstart/step3.md b/docs/versioned_docs/version-2.3.0/quickstart/step3.md deleted file mode 100644 index ee7184ffc7..0000000000 --- a/docs/versioned_docs/version-2.3.0/quickstart/step3.md +++ /dev/null @@ -1,14 +0,0 @@ -```jsx -const isPressed = useSharedValue(false); -const offset = useSharedValue({ x: 0, y: 0 }); -const animatedStyles = useAnimatedStyle(() => { - return { - transform: [ - { translateX: offset.value.x }, - { translateY: offset.value.y }, - { scale: withSpring(isPressed.value ? 1.2 : 1) }, - ], - backgroundColor: isPressed.value ? 'yellow' : 'blue', - }; -}); -``` diff --git a/docs/versioned_docs/version-2.3.0/quickstart/step4.md b/docs/versioned_docs/version-2.3.0/quickstart/step4.md deleted file mode 100644 index 8e2112a3cd..0000000000 --- a/docs/versioned_docs/version-2.3.0/quickstart/step4.md +++ /dev/null @@ -1,9 +0,0 @@ -```jsx {4} -... -return ( - - - -); -... -``` diff --git a/docs/versioned_docs/version-2.3.0/quickstart/step5.md b/docs/versioned_docs/version-2.3.0/quickstart/step5.md deleted file mode 100644 index c7c2e07265..0000000000 --- a/docs/versioned_docs/version-2.3.0/quickstart/step5.md +++ /dev/null @@ -1,32 +0,0 @@ -```jsx -const start = useSharedValue({ x: 0, y: 0 }); -const gesture = Gesture.Pan() - .onBegin(() => { - isPressed.value = 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, - }; - }) - .onFinalize(() => { - isPressed.value = false; - }); -``` - -```jsx {3} -... -return ( - - - -); -... -``` diff --git a/docs/versioned_docs/version-2.3.0/troubleshooting.md b/docs/versioned_docs/version-2.3.0/troubleshooting.md deleted file mode 100644 index 3ce6df850c..0000000000 --- a/docs/versioned_docs/version-2.3.0/troubleshooting.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -id: troubleshooting -title: Troubleshooting ---- - -## Troubleshooting - -Thanks for giving this library a try! We are sorry that you might have encountered issues though. Here is how you can seek help: - -1. Search over the [issues on Github](https://github.com/software-mansion/react-native-gesture-handler/issues). There is a chance someone had this problem in the past and it has been resolved! -2. When sure your problem hasn't been reported or was reported but the proposed solution doesn't work for you please follow [our issue reporting guidelines](#reporting-issues). -3. You can try seeking help on [Expo Developers Discord](https://chat.expo.dev/) where we often hang out. -4. If you feel like reading the source code I highly recommend it, as this is by far the best resource and gives you the most up to date insights into how the library works and what might be causing the bug. -5. If you managed to find the solution consider [contributing](introduction.md#contributing) a fix or update our documentation to make this information easier to find for the others in the future. - -## Reporting issues - -This library is maintained by a very small team. -Please be mindful of that when reporting issue and when it happens that we can't get back to you as soon as you might expect. -We would love to fix all the problems as soon as possible, but often our time is constraint with other issues/features or projects. -To make it easier for us to understand your issue and to be able to approach it sooner you can help by: - -- Making sure the issue description is complete. Please include all the details about your environment (library version, RN version, device OS etc). -- It is the best to provide an example app that reproduces the issue you are having. Put it up on [gist](https://gist.github.com/), [snack](https://snack.expo.io) or create a repo on Github – it doesn't matter as long as we can easily pull it in, run and see the issue. -- Explain how you run your repro app and what steps to take to reproduce the issue. -- Isolate your issue from other dependencies you might be using and make the repro app as minimal as possible. -- If you have spent some time figuring out the root cause of the problem you can leave a note about your findings so far. -- **Do not comment on closed issues**. It is very unlikely that we are going to notice your comment in such a case. If the issue has been closed, but the proposed solution doesn't work for you, please open a new one providing all the information necessary and linking to the solution you have tried. - -## It's not a bug, it's a feature - -- Changing `enabled` prop during a gesture has no effect, only when a gesture starts (that is a finger touches the screen) the `enabled` prop is taken into consideration to decide whether to extract (or not) the gesture and provide it with stream of events to analyze. -- `Native` gesture may not conform to the standard state flow due to platform specific workarounds to incorporate native views into RNGH. -- Keep in mind that `Touchables` from RNGH are rendering two additional views that may need to be styled separately to achieve desired effect (`style` and `containerStyle` props). -- In order for the gesture composition to work, all composed gestures must be attached to the same `GestureHandlerRootView`. diff --git a/docs/versioned_docs/version-2.3.0/under-the-hood/how-does-it-work.md b/docs/versioned_docs/version-2.3.0/under-the-hood/how-does-it-work.md deleted file mode 100644 index aebed78316..0000000000 --- a/docs/versioned_docs/version-2.3.0/under-the-hood/how-does-it-work.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -id: how-does-it-work -title: How does it work? -sidebar_label: How does it work? ---- - -### Units - -All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". -These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://facebook.github.io/react-native/docs/flexbox.html)). -They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. - -## iOS - -All gestures are implemented using [UIGestureRecognizers](https://developer.apple.com/documentation/uikit/uigesturerecognizer?language=objc), some of them have been slightly modified to allow for more customization and to conform to the state flow of RNGH. When you assign a gesture configuration to the `GestureDetector`, it creates all the required recognizers and assigns them to the child view of the detector. From this point most of the heavy lifting is handled by the [UIKit](https://developer.apple.com/documentation/uikit?language=objc) (with our help to correctly implement interactions between gestures). - -## Android - -Unfortunately, Android doesn't provide an easy way of handling gestures hence most of them were implemented from scratch, including a system for managing how the gestures should interact with each other. Here's a quick overview of how it works: -When you wrap a component with `GestureHandlerRootView` it allows for the RNGH to intercept all touch events on that component and process them, deciding whether they should be handled by one of the gesture handlers or passed to the underlying view. Gesture handlers are created when you assign a gesture configuration to the `GestureDetector`, it initializes all of the necessary handlers natively. Every `GestureHandlerRootView` also has a specific handler to decide whether to pass the touch events or to consume them. It can never activate, only begin, end or be cancelled. When this handler is in the `UNDETERMINED` state it means that there is no touch in progress, however when the touch starts it transitions to the `BEGAN` state. As long as it stays in that state, no touch event is consumed, but as soon as it gets cancelled (meaning that some handler has activated) all incoming touch events get consumed, preventing underlying view from receiving them. - -When a pointer touches the screen the view tree is traversed in order to extract all handlers attached to the views below the finger (including the one attached to the `GestureHandlerRootView`) and all extracted handlers transition to the `BEGAN` state, signalling that the gesture may heve began. The touch events continue to be delivered to all extracted handlers until one of them recognizes the gesture and tries to activate. At this point the orchestrator checks whether this gesture should wait for any other of the extracted gestures to fail. If it does, it's put to the waiting list, if it doesn't, it gets activated and all other gestures (that are not simultaneous with it) get cancelled. When a gesture handlers transitions to a finished state (the gesture recognized by it stops, it fails or gets cancelled) the orchestrator check the waiting handlers. Every one of them that waited for the gesture that just failed tries to activate again (and again the orchestrator checks if it should wait for any of the extracted gestures...). diff --git a/docs/versioned_docs/version-2.3.0/under-the-hood/states-events.md b/docs/versioned_docs/version-2.3.0/under-the-hood/states-events.md deleted file mode 100644 index 600f16a5cc..0000000000 --- a/docs/versioned_docs/version-2.3.0/under-the-hood/states-events.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -id: states-events -title: Gesture states & events -sidebar_label: Gesture states & events ---- - -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 (longer arrows represent that there are possibly more touch events received before the state changes): - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`END`](#end) -> [`UNDETERMINED`](#undetermined) - -Another possible flow is when a handler receives touches that cause a recognition failure: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`FAILED`](#failed) -> [`UNDETERMINED`](#undetermined) - -At last, when a handler does properly recognize the gesture but then is interrupted by the touch system the gesture recognition is canceled and the flow looks as follows: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`CANCELLED`](#cancelled) -> [`UNDETERMINED`](#undetermined) - -## 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. - -### `onPointerChange` - -Is called before `onPointerDown`, `onPointerMove`, `onPointerUp` and `onPointerCancelled` with the same event, which may be useful in case you share logic between them. It may carry information about more than one pointer because the events are batched. diff --git a/docs/versioned_docs/version-2.4.0/api/components/buttons.mdx b/docs/versioned_docs/version-2.4.0/api/components/buttons.mdx deleted file mode 100644 index ac8657a5eb..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/components/buttons.mdx +++ /dev/null @@ -1,170 +0,0 @@ ---- -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` -- `RectButton` -- `BorderlessButton` - -On top of that all the buttons are wrapped with `NativeViewGestureHandler` and therefore allow for all the [common gesture handler properties](#common-gesturehandler-properties) and `NativeViewGestureHandler`'s [extra properties](#nativeviewgesturehandler-extra-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). - -### `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`. - -## `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`](#basebutton-component), 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`](#basebutton-component), 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/docs/versioned_docs/version-2.4.0/api/components/drawer-layout.mdx b/docs/versioned_docs/version-2.4.0/api/components/drawer-layout.mdx deleted file mode 100644 index 04abc42c72..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/components/drawer-layout.mdx +++ /dev/null @@ -1,147 +0,0 @@ ---- -id: drawer-layout -title: Drawer Layout -sidebar_label: DrawerLayout ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import GifGallery from '@site/components/GifGallery'; - -This is a cross-platform replacement for React Native's [DrawerLayoutAndroid](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) component. It provides a compatible API but allows for the component to be used on both Android and iOS. Please refer to [React Native docs](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) for the detailed usage for standard parameters. - -## Usage: - -`DrawerLayout` component isn't exported by default from the `react-native-gesture-handler` package. To use it, import it in the following way: - -```js -import DrawerLayout from 'react-native-gesture-handler/DrawerLayout'; -``` - -## Properties: - -On top of the standard list of parameters DrawerLayout has an additional set of attributes to customize its behavior. Please refer to the list below: - -### `drawerType` - -possible values are: `front`, `back` or `slide` (default is `front`). It specifies the way the drawer will be displayed. When set to `front` the drawer will slide in and out along with the gesture and will display on top of the content view. When `back` is used the drawer displays behind the content view and can be revealed with gesture of pulling the content view to the side. Finally `slide` option makes the drawer appear like it is attached to the side of the content view; when you pull both content view and drawer will follow the gesture. - -Type `slide`: - - - - - -Type `front`: - - - - - -Type `back`: - - - - - -### `edgeWidth` - -number, allows for defining how far from the edge of the content view the gesture should activate. - -### `hideStatusBar` - -boolean, when set to `true` Drawer component will use [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html) API to hide the OS status bar whenever the drawer is pulled or when its in an "open" state. - -### `statusBarAnimation` - -possible values are: `slide`, `none` or `fade` (defaults to `slide`). Can be used when `hideStatusBar` is set to `true` and will select the animation used for hiding/showing the status bar. See [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html#statusbaranimation) documentation for more details. - -### `overlayColor` - -color (default to `"black"`) of a semi-transparent overlay to be displayed on top of the content view when drawer gets open. A solid color should be used as the opacity is added by the Drawer itself and the opacity of the overlay is animated (from 0% to 70%). - -### `renderNavigationView` - -function. This attribute is present in the standard implementation already and is one of the required params. Gesture handler version of DrawerLayout make it possible for the function passed as `renderNavigationView` to take an Animated value as a parameter that indicates the progress of drawer opening/closing animation (progress value is 0 when closed and 1 when opened). This can be used by the drawer component to animated its children while the drawer is opening or closing. - -### `onDrawerClose` - -function. This function is called when the drawer is closed. - -### `onDrawerOpen` - -function. This function is called when the drawer is opened. - -### `onDrawerSlide` - -function. This function is called as a drawer sliding open from touch events. The progress of the drawer opening/closing is passed back as 0 when closed and 1 when opened. - -### `onDrawerStateChanged` - -function. This function is called when the status of the drawer changes. Possible values that can be passed back are: 'Idle', 'Dragging', and 'Settling'. - -### `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` - -component or function. Children is a component which is rendered by default and is wrapped by drawer. However, it could be also a render function which takes an Animated value as a parameter that indicates the progress of drawer opening/closing animation (progress value is 0 when closed and 1 when opened) is the same way like `renderNavigationView` prop. - -## Methods - -### `openDrawer(options)` - -`openDrawer` can take an optional `options` parameter which is an object, enabling further customization of the open animation. - -`options` has two optional properties: - -`velocity`: number, the initial velocity of the object attached to the spring. Default 0 (object is at rest). -`speed`: number, controls speed of the animation. Default 12. - -### `closeDrawer(options)` - -`closeDrawer` can take an optional `options` parameter which is an object, enabling further customization of the close animation. - -`options` has two optional properties: - -`velocity`: number, the initial velocity of the object attached to the spring. Default 0 (object is at rest). -`speed`: number, controls speed of the animation. Default 12. - -## Example: - -See the [drawer example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/horizontalDrawer/index.tsx) from GestureHandler Example App or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -class Drawerable extends Component { - handleDrawerSlide = (status) => { - // outputs a value between 0 and 1 - console.log(status); - }; - - renderDrawer = () => { - return ( - - I am in the drawer! - - ); - }; - - render() { - return ( - - - - Hello, it's me - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.4.0/api/components/swipeable.md b/docs/versioned_docs/version-2.4.0/api/components/swipeable.md deleted file mode 100644 index 18fb7dfe78..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/components/swipeable.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -id: swipeable -title: Swipeable -sidebar_label: Swipeable ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import GifGallery from '@site/components/GifGallery' - - - - - -This component 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: - -Similarly to the `DrawerLayout`, `Swipeable` component isn't exported by default from the `react-native-gesture-handler` package. To use it, import it in the following way: - -```js -import Swipeable from 'react-native-gesture-handler/Swipeable'; -``` - -## 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. - -### `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 method 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 method 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. - -### `onSwipeableLeftOpen` - -:::caution -This callback is deprecated and will be removed in the next version. Please use `onSwipeableOpen(direction)` -::: - -method that is called when left action panel gets open. - -### `onSwipeableRightOpen` - -:::caution -This callback is deprecated and will be removed in the next version. Please use `onSwipeableOpen(direction)` -::: - -method that is called when right action panel gets open. - -### `onSwipeableOpen` - -method that is called when action panel gets open (either right or left). Takes swipe direction as -an argument. - -### `onSwipeableClose` - -method that is called when action panel is closed. Takes swipe direction as -an argument. - -### `onSwipeableLeftWillOpen` - -:::caution -This callback is deprecated and will be removed in the next version. Please use `onSwipeableWillOpen(direction)` -::: - -method that is called when left action panel starts animating on open. - -### `onSwipeableRightWillOpen` - -:::caution -This callback is deprecated and will be removed in the next version. Please use `onSwipeableWillOpen(direction)` -::: - -method that is called when right action panel starts animating on open. - -### `onSwipeableWillOpen` - -method that is called when action panel starts animating on open (either right or left). Takes swipe direction as -an argument. - -### `onSwipeableWillClose` - -method that is called when action panel starts animating on close. Takes swipe direction as -an argument. - -### `renderLeftActions` - -method that is expected to return an action panel that is going to be revealed from the left side when user swipes right. -This map describes the values to use as inputRange for extra interpolation: -AnimatedValue: [startValue, endValue] - -progressAnimatedValue: [0, 1] -dragAnimatedValue: [0, +] - -To support `rtl` flexbox layouts use `flexDirection` styling. - -### `renderRightActions` - -method that is expected to return an action panel that is going to be revealed from the right side when user swipes left. -This map describes the values to use as inputRange for extra interpolation: -AnimatedValue: [startValue, endValue] - -progressAnimatedValue: [0, 1] -dragAnimatedValue: [0, -] - -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`. - -### `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. - -## Methods - -Using reference to `Swipeable` it's possible to trigger some actions on it - -### `close` - -method that closes component. - -### `openLeft` - -method that opens component on left side. - -### `openRight` - -method that opens component on right side. - -### Example: - -See the [swipeable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/showcase/swipeable/index.tsx) from GestureHandler Example App or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -import React, { Component } from 'react'; -import { Animated, StyleSheet, View } from 'react-native'; -import { RectButton } from 'react-native-gesture-handler'; -import Swipeable from 'react-native-gesture-handler/Swipeable'; - -class AppleStyleSwipeableRow extends Component { - renderLeftActions = (progress, dragX) => { - const trans = dragX.interpolate({ - inputRange: [0, 50, 100, 101], - outputRange: [-20, 0, 0, 1], - }); - return ( - - - Archive - - - ); - }; - render() { - return ( - - "hello" - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/base-continous-gesture-callbacks.md b/docs/versioned_docs/version-2.4.0/api/gestures/base-continous-gesture-callbacks.md deleted file mode 100644 index 5504b2db8d..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/base-continous-gesture-callbacks.md +++ /dev/null @@ -1,9 +0,0 @@ -### Callbacks common to all continous gestures: - -### `onUpdate(callback)` - -Set the callback that is being called every time the gesture receives an update while it's active. - -### `onChange(callback)` - -Set the callback that is being called every time the gesture receives an update while it's active. This callback will receive information about change in value in relation to the last received event. diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/base-continous-gesture-config.md b/docs/versioned_docs/version-2.4.0/api/gestures/base-continous-gesture-config.md deleted file mode 100644 index a19473784e..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/base-continous-gesture-config.md +++ /dev/null @@ -1,5 +0,0 @@ -### Properties common to all continous gestures: - -### `manualActivation(value: boolead)` - -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](./state-manager.md). diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/base-gesture-callbacks.md b/docs/versioned_docs/version-2.4.0/api/gestures/base-gesture-callbacks.md deleted file mode 100644 index dff985b307..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/base-gesture-callbacks.md +++ /dev/null @@ -1,33 +0,0 @@ -### Callbacks common to all gestures: - -### `onBegin(callback)` - -Set the callback that is being called when given gesture handler starts receiving touches. At the moment of this callback the handler is not yet in an active state and we don't know yet if it will recognize the gesture at all. - -### `onStart(callback)` - -Set the callback that is being called when the gesture is recognized by the handler and it transitions to the active state. - -### `onEnd(callback)` - -Set the callback that is being called when the gesture that was recognized by the handler finishes. It will be called only if the handler was previously in the active state. - -### `onFinalize(callback)` - -Set the callback that is being called when the handler finalizes handling gesture - the gesture was recognized and has finished or it failed to recognize. - -### `onTouchesDown(callback)` - -Set the `onTouchesDown` callback which is called every time a finger is placed on the screen. - -### `onTouchesMove(callback)` - -Set the `onTouchesMove` callback which is called every time a finger is moved on the screen. - -### `onTouchesUp(callback)` - -Set the `onTouchesUp` callback which is called every time a finger is lifted from the screen. - -### `onTouchesCancelled(callback)` - -Set the `onTouchesCancelled` callback which is called every time a finger stops being tracked, for example when the gesture finishes. diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/base-gesture-config.md b/docs/versioned_docs/version-2.4.0/api/gestures/base-gesture-config.md deleted file mode 100644 index b096f17bb7..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/base-gesture-config.md +++ /dev/null @@ -1,59 +0,0 @@ -### 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`](../../under-the-hood/states-events.md#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`](../../under-the-hood/states-events.md#failed) or [`CANCELLED`](../../under-the-hood/states-events.md#cancelled) (depending on its current state). -Default value is `true`. - -### `shouldCancelWhenOutside(value: boolean)` - -When `true` the handler will [cancel](../../under-the-hood/states-events.md#cancelled) or [fail](../../under-the-hood/states-events.md#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`](./long-press-gesture.md) and [`TapGesture`](./tap-gesture.md) which default to `true`. - -### `hitSlop(settings)` - -This parameter enables control over what part of the connected view area can be used to [begin](../../under-the-hood/states-events.md#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://facebook.github.io/react-native/docs/view.html#props) 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`](../../under-the-hood/states-events.md#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](../../gesture-composition). [`GestureDetector`](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. - -**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](../../gesture-composition).[`GestureDetector`](gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/base-gesture-event-data.md b/docs/versioned_docs/version-2.4.0/api/gestures/base-gesture-event-data.md deleted file mode 100644 index 4d9056b1e5..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/base-gesture-event-data.md +++ /dev/null @@ -1,9 +0,0 @@ -### Event attributes common to all gestures: - -### `state` - -Current [state](.../../under-the-hood/states-events.md) 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. diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/composed-gestures.md b/docs/versioned_docs/version-2.4.0/api/gestures/composed-gestures.md deleted file mode 100644 index 84e2e451bd..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/composed-gestures.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: composed-gestures -title: Composed gestures -sidebar_label: Composed gestures ---- - -Composed gestures (`Race`, `Simultaneous`, `Exclusive`) provide a simple way of building relations between gestures. diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/fling-gesture.md b/docs/versioned_docs/version-2.4.0/api/gestures/fling-gesture.md deleted file mode 100644 index 09c2846276..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/fling-gesture.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -id: fling-gesture -title: Fling gesture -sidebar_label: Fling gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; - -A discrete gesture that activates when the movement is sufficiently long and fast. -Gesture gets [ACTIVE](../../under-the-hood/states-events.md#active) when movement is sufficiently long and it does not take too much time. -When gesture gets activated it will turn into [END](../../under-the-hood/states-events.md#end) state when finger is released. -The gesture will fail to recognize if the finger is lifted before being activated. - -## Config - -### Properties specific to `FlingGesture`: - -### `direction(value: Directions)` - -Expressed allowed direction of movement. Expected values are exported as constants in the `Directions` object. It's possible to pass one or many directions in one parameter: - -```js -fling.direction(Directions.RIGHT | Directions.LEFT); -``` - -or - -```js -fling.direction(Directions.DOWN); -``` - -### `numberOfPointers(value: number)` - -Determine exact number of points required to handle the fling gesture. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `FlingGesture`: - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - - - -## Example - -```jsx -const position = useSharedValue(0); - -const flingGesture = Gesture.Fling() - .direction(Directions.RIGHT) - .onStart((e) => { - position.value = withTiming(position.value + 10, { duration: 100 }); - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ translateX: position.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/force-touch-gesture.md b/docs/versioned_docs/version-2.4.0/api/gestures/force-touch-gesture.md deleted file mode 100644 index 8280f944b1..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/force-touch-gesture.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -id: force-touch-gesture -title: Force touch gesture (iOS only) -sidebar_label: Force touch gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-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](../../under-the-hood/states-events.md#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. - -There's no implementation provided on Android and it simply renders children without any wrappers. -Since this behaviour is only provided on some iOS devices, this gesture should not be used for defining any crucial behaviors. Use it only as an additional improvement and make all features to be accessed without this gesture as well. - -## Config - -### Properties specific to `ForceTouchGesture`: - -### `minForce(value: number)` - -A minimal pressure that is required before gesture can [activate](../../under-the-hood/states-events.md#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](../../under-the-hood/states-events.md#failed). Should be a value from range `[0.0, 1.0]`. - -### `feedbackOnActivation(value: boolean)` - -Value defining if haptic feedback has to be performed on activation. - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `ForceTouchGesture`: - -### `force` - -The pressure of a touch. - - diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/gesture-detector-functional1.md b/docs/versioned_docs/version-2.4.0/api/gestures/gesture-detector-functional1.md deleted file mode 100644 index 2397af9dfa..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/gesture-detector-functional1.md +++ /dev/null @@ -1,19 +0,0 @@ -```jsx -export default function Example() { - const tap = Gesture.Tap().onStart(() => { - console.log('tap'); - }); - - return ( - - - - - - ); -} - -function FunctionalComponent(props) { - return {props.children}; -} -``` diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/gesture-detector.md b/docs/versioned_docs/version-2.4.0/api/gestures/gesture-detector.md deleted file mode 100644 index ef8af9b62c..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/gesture-detector.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -id: gesture-detector -title: GestureDetector -sidebar_label: Gesture detector ---- - -import FunctionalComponents from './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.x/). - -:::caution -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. -::: - -## 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 synchrously. - -Starting with Reanimated-2.3.0-beta.4 Gesture Handler will provide a [StateManager](./state-manager.md) in the [touch events](./touch-events.md) that allows for managing the state of the gesture. -::: diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/gesture.md b/docs/versioned_docs/version-2.4.0/api/gestures/gesture.md deleted file mode 100644 index a84a48003a..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/gesture.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -id: gesture -title: Gesture -sidebar_label: Gesture ---- - -`Gesture` is the object that allows you to create and compose gestures. - -### Gesture.Tap() - -Creates a new instance of [`TapGesture`](./tap-gesture.md) with its default config and no callbacks. - -### Gesture.Pan() - -Creates a new instance of [`PanGesture`](./pan-gesture.md) with its default config and no callbacks. - -### Gesture.LongPress() - -Creates a new instance of [`LongPressGesture`](./long-press-gesture.md) with its default config and no callbacks. - -### Gesture.Fling() - -Creates a new instance of [`FlingGesture`](./fling-gesture.md) with its default config and no callbacks. - -### Gesture.Pinch() - -Creates a new instance of [`PinchGesture`](./pinch-gesture.md) with its default config and no callbacks. - -### Gesture.Rotation() - -Creates a new instance of [`RotationGesture`](./rotation-gesture.md) with its default config and no callbacks. - -### Gesture.ForceTouch() - -Creates a new instance of [`ForceTouchGesture`](./force-touch-gesture.md) with its default config and no callbacks. - -### Gesture.Manual() - -Creates a new instance of [`ManualGesture`](./manual-gesture.md) with its default config and no callbacks. - -### Gesture.Native() - -Creates a new instance of [`NativeGesture`](./native-gesture.md) with its default config and no callbacks. - -### Gesture.Race(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. Only one of those can become active and there are no restrictions to the activation of the gesture. The first one to activate will cancel all the others. - -### Gesture.Simultaneous(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. All of them can become active without cancelling the others. - -### Gesture.Exclusive(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. Only one of them can become active, but the first one has a higher priority than the second one, the second one has a higher priority than the third one, and so on. When all gestures are in the `BEGAN` state and the activation criteria for the second one is met, instead of activating it will wait until the first one fails (and only then it will activate) or until the first one activates (and then the second one will get cancelled). It is useful when you want to compose gestures with similar activation criteria (e.g. single and double tap at the same component, without Exclusive the single tap would activate every time user taps thus cancelling the double tap). diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/long-press-gesture.md b/docs/versioned_docs/version-2.4.0/api/gestures/long-press-gesture.md deleted file mode 100644 index 9f174d58e7..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/long-press-gesture.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -id: long-press-gesture -title: Long press gesture -sidebar_label: Long press gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './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](../../under-the-hood/states-events.md#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](#mindurationms) or if the finger is moved further than the [allowable distance](#maxdist). - -## Config - -### Properties specific to `LongPressGesture`: - -### `minDuration(value: number)` - -Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. - -### `maxDistance(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. The default value is 10. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `LongPressGesture`: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `duration` - -Duration of the long press (time since the start of the gesture), expressed in milliseconds. - - - -## Example - -```jsx -const longPressGesture = Gesture.LongPress().onEnd((e, success) => { - if (success) { - Alert.alert(`Long pressed for ${e.duration} ms!`); - } -}); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/manual-gesture.md b/docs/versioned_docs/version-2.4.0/api/gestures/manual-gesture.md deleted file mode 100644 index a92c6986ef..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/manual-gesture.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -id: manual-gesture -title: Manual gesture -sidebar_label: Manual gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A plain gesture that has no specific activation criteria nor event data set. Its state has to be controlled manually using a [state manager](./state-manager.md). It will not fail when all the pointers are lifted from the screen. - -## Config - - - -## Callbacks - - - - -## Event data - - diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/native-gesture.md b/docs/versioned_docs/version-2.4.0/api/gestures/native-gesture.md deleted file mode 100644 index 6fa7249eed..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/native-gesture.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -id: native-gesture -title: Native gesture -sidebar_label: Native gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A gesture that allows other touch handling components to participate in RNGH's gesture system. When used, the other component should be the direct child of a `GestureDetector`. - -## Config - -### Properties specific to `NativeGesture`: - -### `shouldActivateOnStart(value: boolean)` (**Android only**) - -When `true`, underlying handler will activate unconditionally when in `BEGAN` or `UNDETERMINED` state. - -### `disallowInterruption(value: boolean)` - -When `true`, cancels all other gesture handlers when this `NativeViewGestureHandler` receives an `ACTIVE` state event. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `NativeGesture`: - -### `pointerInside` - -True if gesture was performed inside of containing view, false otherwise. - - diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/pan-gesture.md b/docs/versioned_docs/version-2.4.0/api/gestures/pan-gesture.md deleted file mode 100644 index c8be974e7f..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/pan-gesture.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -id: pan-gesture -title: Pan gesture -sidebar_label: Pan gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that can recognize a panning (dragging) gesture and track its movement. - -The gesture [activates](../../under-the-hood/states-events.md#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. - -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. - -## 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. - -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 [`avgTouches`](#avgtouches-android-only) flag. - -Note that on both Android and iOS when the additional finger is placed on the screen that translation prop is not affected even though the position of the pointer being tracked might have changed. -Therefore it is safe to rely on translation most of the time as it only reflects the movement that happens regardless of how many fingers are placed on the screen and if that number changes over time. -If you wish to track the "center of mass" virtual pointer and account for its changes when the number of finger changes you can use relative or absolute position provided in the event ([`x`](#x) and [`y`](#y) or [`absoluteX`](#absolutex) and [`absoluteY`](#absolutey)). - -## Config - -### Properties specific to `PanGesture`: - -### `minDistance(value: number)` - -Minimum distance the finger (or multiple finger) need to travel before the gesture [activates](../../under-the-hood/states-events.md#active). Expressed in points. - -### `minPointers(value: number)` - -A number of fingers that is required to be placed before gesture can [activate](../../under-the-hood/states-events.md#active). Should be a higher or equal to 0 integer. - -### `maxPointers(value: number)` - -When the given number of fingers is placed on the screen and gesture hasn't yet [activated](../../under-the-hood/states-events.md#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. - -### `activeOffsetX(value: number | number[])` - -Range along X axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `activeOffsetY(value: number | number[])` - -Range along Y axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `failOffsetY(value: number | number[])` - -When the finger moves outside this range (in points) along Y axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `failOffsetX(value: number | number[])` - -When the finger moves outside this range (in points) along X axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `averageTouches(value: boolean)` (Android only) - -### `enableTrackpadTwoFingerGesture(value: boolean)` (iOS only) - -Enables two-finger gestures on supported devices, for example iPads with trackpads. If not enabled the gesture will require click + drag, with enableTrackpadTwoFingerGesture swiping with two fingers will also trigger the gesture. - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `PanGesture`: - -### `translationX` - -Translation of the pan gesture along X axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `translationY` - -Translation of the pan gesture along Y axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `velocityX` - -Velocity of the pan gesture along the X axis in the current moment. The value is expressed in point units per second. - -### `velocityY` - -Velocity of the pan gesture along the Y axis in the current moment. The value is expressed in point units per second. - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - - - -## Example - -```jsx -const END_POSITION = 200; -const onLeft = useSharedValue(true); -const position = useSharedValue(0); - -const panGesture = Gesture.Pan() - .onUpdate((e) => { - if (onLeft.value) { - position.value = e.translationX; - } else { - position.value = END_POSITION + e.translationX; - } - }) - .onEnd((e) => { - if (position.value > END_POSITION / 2) { - position.value = withTiming(END_POSITION, { duration: 100 }); - onLeft.value = false; - } else { - position.value = withTiming(0, { duration: 100 }); - onLeft.value = true; - } - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ translateX: position.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/pinch-gesture.md b/docs/versioned_docs/version-2.4.0/api/gestures/pinch-gesture.md deleted file mode 100644 index 5b56e7d043..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/pinch-gesture.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -id: pinch-gesture -title: Pinch gesture -sidebar_label: Pinch gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. -The gesture [activates](../../under-the-hood/states-events.md#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. - -## Config - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `PinchGesture`: - -### `scale` - -The scale factor relative to the points of the two touches in screen coordinates. - -### `velocity` - -Velocity of the pan gesture the current moment. The value is expressed in point units per second. - -### `focalX` - -Position expressed in points along X axis of center anchor point of gesture - -### `focalY` - -Position expressed in points along Y axis of center anchor point of gesture - - - -## Example - -```jsx -const scale = useSharedValue(1); -const savedScale = useSharedValue(1); - -const pinchGesture = Gesture.Pinch() - .onUpdate((e) => { - scale.value = savedScale.value * e.scale; - }) - .onEnd(() => { - savedScale.value = scale.value; - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ scale: scale.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/rotation-gesture.md b/docs/versioned_docs/version-2.4.0/api/gestures/rotation-gesture.md deleted file mode 100644 index 6550e0ea98..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/rotation-gesture.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -id: rotation-gesture -title: Rotation gesture -sidebar_label: Rotation gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that can recognize a rotation gesture and track its movement. - -The gesture [activates](../../under-the-hood/states-events.md#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. - -## Config - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `RotationGesture`: - -### `rotation` - -Amount rotated, expressed in radians, from the gesture's focal point (anchor). - -### `velocity` - -Instantaneous velocity, expressed in point units per second, of the gesture. - -### `anchorX` - -X coordinate, expressed in points, of the gesture's central focal point (anchor). - -### `anchorY` - -Y coordinate, expressed in points, of the gesture's central focal point (anchor). - - - -## Example - -```jsx -const rotation = useSharedValue(1); -const savedRotation = useSharedValue(1); - -const rotationGesture = Gesture.Rotation() - .onUpdate((e) => { - rotation.value = savedRotation.value + e.rotation; - }) - .onEnd(() => { - savedRotation.value = rotation.value; - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ rotateZ: `${(rotation.value / Math.PI) * 180}deg` }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/state-manager.md b/docs/versioned_docs/version-2.4.0/api/gestures/state-manager.md deleted file mode 100644 index cb50e8212b..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/state-manager.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: state-manager -title: Gesture state manager -sidebar_label: Gesture state manager ---- - -`GestureStateManager` allows to manually control the state of the gestures. Please note that `react-native-reanimated` is required to use it, since it allows for synchronously executing methods in worklets. - -## Methods - -### `begin()` - -Transition the gesture to the [`BEGAN`](../../under-the-hood/states-events.md#began) state. This method will have no effect if the gesture has already activated or finished. - -### `activate()` - -Transition the gesture to the [`ACTIVE`](../../under-the-hood/states-events.md#active) state. This method will have no effect if the handler is already active, or has finished. -If the gesture is [`exclusive`](../../gesture-composition) with another one, the activation will be delayed until the gesture with higher priority fails. - -### `end()` - -Transition the gesture to the [`END`](../../under-the-hood/states-events.md#end) state. This method will have no effect if the handler has already finished. - -### `fail()` - -Transition the gesture to the [`FAILED`](../../under-the-hood/states-events.md#failed) state. This method will have no effect if the handler has already finished. diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/tap-gesture.md b/docs/versioned_docs/version-2.4.0/api/gestures/tap-gesture.md deleted file mode 100644 index 6c6c0a0872..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/tap-gesture.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -id: tap-gesture -title: Tap gesture -sidebar_label: Tap gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; - -A discrete gesture that recognizes one or many taps. - -Tap gestures detect one or more fingers briefly touching the screen. -The fingers involved in these gestures must not move significantly from their initial touch positions. -The required number of taps and allowed distance from initial position may be configured. -For example, you might configure tap gesture recognizers to detect single taps, double taps, or triple taps. - -In order for a gesture to [activate](../../under-the-hood/states-events.md#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDuration, and maxDelayMs (explained below) must be met. Immediately after the gesture [activates](../../under-the-hood/states-events.md#active), it will [end](../../under-the-hood/states-events.md#end). - -## Config - -### Properties specific to `TapGesture`: - -### `minPointers(value: number)` - -Minimum number of pointers (fingers) required to be placed before the gesture [activates](../../under-the-hood/states-events.md#active). Should be a positive integer. The default value is 1. - -### `maxDuration(value: number)` - -Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch. The default value is 500. - -### `maxDelay(value: number)` - -Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required. The default value is 500. - -### `numberOfTaps(value: number)` - -Number of tap gestures required to [activate](../../under-the-hood/states-events.md#active) the gesture. The default value is 1. - -### `maxDeltaX(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the X axis during a tap gesture. If the finger travels further than the defined distance along the X axis and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - -### `maxDeltaY(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the Y axis during a tap gesture. If the finger travels further than the defined distance along the Y axis and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - -### `maxDistance(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a tap gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `TapGesture`: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - - - -## Example - -```jsx -const singleTap = Gesture.Tap() - .maxDuration(250) - .onStart(() => { - Alert.alert('Single tap!'); - }); - -const doubleTap = Gesture.Tap() - .maxDuration(250) - .onStart(() => { - Alert.alert('Double tap!'); - }); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.4.0/api/gestures/touch-events.md b/docs/versioned_docs/version-2.4.0/api/gestures/touch-events.md deleted file mode 100644 index 58103d7b25..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/gestures/touch-events.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -id: touch-events -title: Touch events -sidebar_label: Touch events ---- - -### Touch event attributes: - -### `eventType` - -Type of the current event - whether the finger was placed on the screen, moved, lifted or cancelled. - -### `changedTouches` - -An array of objects where every object represents a single touch. Contains information only about the touches that were affected by the event i.e. those that were placed down, moved, lifted or cancelled. - -### `allTouches` - -An array of objects where every object represents a single touch. Contains information about all active touches. - -### `numberOfTouches` - -Number representing the count of currently active touches. - -:::caution -Don't rely on the order of items in the `touches` as it may change during the gesture, instead use the `id` attribute to track individual touches across events. -::: - -### PointerData attributes: - -### `id` - -A number representing id of the touch. It may be used to track the touch between events as the id will not change while it is being tracked. - -### `x` - -X coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the touch relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the touch relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. diff --git a/docs/versioned_docs/version-2.4.0/api/test-api.md b/docs/versioned_docs/version-2.4.0/api/test-api.md deleted file mode 100644 index 2eacd0c711..0000000000 --- a/docs/versioned_docs/version-2.4.0/api/test-api.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -id: test-api -title: Testing ---- - -:::info -If you want to use `fireGestureHandler` and `getByGestureTestId`, you need to import them from `react-native-gesture-handler/jest-utils` package. -::: - -## fireGestureHandler(gestureOrHandler, eventList) - -Simulates one event stream (i.e. event sequence starting with `BEGIN` state and ending -with one of `END`/`FAIL`/`CANCEL` states), calling appropriate callbacks associated with given gesture handler. - -### Arguments - -#### `gestureOrHandler` - -Represents either: - -1. Gesture handler component found by Jest queries (e.g. `getByTestId`) -2. Gesture found by [`getByGestureTestId()`](#getbygestureidtestid) - -#### `eventList` - -Event data passed to appropriate callback. RNGH fills event list if required -data is missing using these rules: - -1. `oldState` is filled using state of the previous event. `BEGIN` events use - `UNDETERMINED` value as previous event. -2. Events after first `ACTIVE` state can omit `state` field. -3. Handler specific data is filled (e.g. `numberOfTouches`, `x` fields) with - defaults. -4. Missing `BEGIN` and `END` events are added with data copied from first and last - passed event, respectively. -5. If first event don't have `state` field, the `ACTIVE` state is assumed. - -Some examples: - -```jsx -const oldStateFilled = [ - { state: State.BEGAN }, - { state: State.ACTIVE }, - { state: State.END }, -]; // three events with specified state are fired. - -const implicitActiveState = [ - { state: State.BEGAN }, - { state: State.ACTIVE }, - { x: 5 }, - { state: State.END }, -]; // 4 events, including two ACTIVE events (second one has overriden additional data). - -const implicitBegin = [ - { x: 1, y: 11 }, - { x: 2, y: 12, state: State.FAILED }, -]; // 3 events, including implicit BEGAN, one ACTIVE, and one FAILED event with additional data. - -const implicitBeginAndEnd = [ - { x: 5, y: 15 }, - { x: 6, y: 16 }, - { x: 7, y: 17 }, -]; // 5 events, including 3 ACTIVE events and implicit BEGAN and END events. BEGAN uses first event's additional data, END uses last event's additional data. - -const allImplicits = []; // 3 events, one BEGIN, one ACTIVE, one END with defaults. -``` - -### Example - -Extracted from RNGH tests, check `Events.test.tsx` for full implementation. - -```tsx -it('sends events with additional data to handlers', () => { - const panHandlers = mockedEventHandlers(); - render(); - fireGestureHandler(getByGestureTestId('pan'), [ - { state: State.BEGAN, translationX: 0 }, - { state: State.ACTIVE, translationX: 10 }, - { translationX: 20 }, - { translationX: 20 }, - { state: State.END, translationX: 30 }, - ]); - - expect(panHandlers.active).toBeCalledTimes(3); - expect(panHandlers.active).toHaveBeenLastCalledWith( - expect.objectContaining({ translationX: 20 }) - ); -}); -``` - -## getByGestureTestId(testID) - -Returns opaque data type associated with gesture. Gesture is found via `testID` attribute in rendered -components (see [`withTestID` method](./gestures/base-gesture-config.md#withrefref)). - -### Arguments - -#### `testID` - -String identifying gesture. - -### Notes - -`testID` must be unique among components rendered in test. - -### Example - -See above example for `fireGestureHandler`. diff --git a/docs/versioned_docs/version-2.4.0/gesture-composition.md b/docs/versioned_docs/version-2.4.0/gesture-composition.md deleted file mode 100644 index e55e06fae6..0000000000 --- a/docs/versioned_docs/version-2.4.0/gesture-composition.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -id: gesture-composition -title: Composing gestures -sidebar_label: Composing gestures ---- - -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 -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 -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 -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 ( - - - -); -``` - -## Composition vs `simultaneousWithExternalGesture` and `requireExternalGestureToFail` - -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. If you want to make a relation between gestures that are attached to separate `GestureDetectors`, we have a separate mechanism for that: `simultaneousWithExternalGesture` and `requireExternalGestureToFail` methods that are available on every base gesture. They work exactly the same way as `simultaneousHandlers` and `waitFor` on gesture handlers, that is they just mark the relation between the gestures without joining them into single object. diff --git a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/common-gh.md b/docs/versioned_docs/version-2.4.0/gesture-handlers/api/common-gh.md deleted file mode 100644 index db42b80583..0000000000 --- a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/common-gh.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -id: common-gh -title: Common handler properties -sidebar_label: Common handler properties ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -This page covers the common set of properties all gesture handler components expose. - -### Units - -All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". -These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://facebook.github.io/react-native/docs/flexbox.html)). -They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. - -## Properties - -This section describes properties that can be used with all gesture handler components: - -### `enabled` - -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`](../basics/state.md#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`](../basics/state.md#failed) or [`CANCELLED`](../basics/state.md#cancelled) (depending on its current state). -Default value is `true`. - -### `shouldCancelWhenOutside` - -Accepts a boolean value. -When `true` the handler will [cancel](../basics/state.md#cancelled) or [fail](../basics/state.md#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.md) and [`TapGestureHandler`](./tap-gh.md) 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`](../basics/state.md#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](../basics/state.md#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](../basics/state.md#active) state. It will also prevent the provided handlers from [cancelling](../basics/state.md#cancelled) the current handler when they [activate](../basics/state.md#active). Read more in the [cross handler interaction](../basics/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](../basics/state.md#active) as long as the handlers provided by their refs are in the [`BEGAN`](../basics/state.md#began) state. Read more in the [cross handler interaction](../basics/interactions.md#awaiting-other-handlers) section. - -### `hitSlop` - -This parameter enables control over what part of the connected view area can be used to [begin](../basics/state.md#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://facebook.github.io/react-native/docs/view.html#props) property. - -### `onGestureEvent` - -Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](../basics/state.md#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.md#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://facebook.github.io/react-native/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](../basics/state.md) 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](../basics/state.md) of the handler right before the change. - -Instead of a callback [`Animated.event`](https://facebook.github.io/react-native/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. - -## Event data - -This section describes the attributes of event object being provided to [`onGestureEvent`](#ongestureevent) and [`onHandlerStateChange`](#onhandlerstatechange) callbacks: - -### `state` - -Current [state](../basics/state.md) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](../basics/state.md) to learn more about how to use it. - -### `numberOfPointers` - -Represents the number of pointers (fingers) currently placed on the screen. diff --git a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/fling-gh.md b/docs/versioned_docs/version-2.4.0/gesture-handlers/api/fling-gh.md deleted file mode 100644 index b356e09cc0..0000000000 --- a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/fling-gh.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -id: fling-gh -title: FlingGestureHandler -sidebar_label: Fling ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A discrete gesture handler that activates when the movement is sufficiently long and fast. -Handler gets [ACTIVE](../basics/state#active) when movement is sufficiently long and it does not take too much time. -When handler gets activated it will turn into [END](../basics/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](./common-gh.md#properties). Below is a list of properties specific to `FlingGestureHandler` component: - -### `direction` - -Expressed allowed direction of movement. It's possible to pass one or many directions in one parameter: - -```js -direction={Directions.RIGHT | Directions.LEFT} -``` - -or - -```js -direction={Directions.DOWN} -``` - -### `numberOfPointers` - -Determine exact number of points required to handle the fling gesture. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `FlingGestureHandler`: - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - -## Example - -See the [fling example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/release_tests/fling/index.tsx) from Gesture Handler Example App. - -```js -const LongPressButton = () => ( - { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert("I'm flinged!"); - } - }}> - - -); -``` diff --git a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/force-gh.md b/docs/versioned_docs/version-2.4.0/gesture-handlers/api/force-gh.md deleted file mode 100644 index ea3bb6835e..0000000000 --- a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/force-gh.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -id: force-gh -title: ForceTouchGestureHandler (iOS only) -sidebar_label: Force touch ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) 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](../basics/state.md#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. - -The handler is implemented using custom [UIGestureRecognizer](https://developer.apple.com/documentation/uikit/uigesturerecognizer) on iOS. There's no implementation provided on Android and it simply render children without any wrappers. -Since this behaviour is only provided on some iOS devices, this handler should not be used for defining any crucial behaviors. Use it only as an additional improvement and make all features to be accessed without this handler as well. - -# Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to `ForceTouchGestureHandler` component: - -### `minForce` - -A minimal pressure that is required before handler can [activate](../basics/state.md#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](../basics/state.md#failed). Should be a value from range `[0.0, 1.0]`. - -### `feedbackOnActivation` - -Boolean value defining if haptic feedback has to be performed on activation. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `ForceTouchGestureHandler`: - -### `force` - -The pressure of a touch. - -## Static method - -### `forceTouchAvailable` - -You may check if it's possible to use `ForceTouchGestureHandler` with `ForceTouchGestureHandler.forceTouchAvailable` - -## Example - -See the [force touch handler example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/forcetouch/index.tsx) from Gesture Handler Example App. - -```js - - - -``` diff --git a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/longpress-gh.md b/docs/versioned_docs/version-2.4.0/gesture-handlers/api/longpress-gh.md deleted file mode 100644 index 1402df76df..0000000000 --- a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/longpress-gh.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -id: longpress-gh -title: LongPressGestureHandler -sidebar_label: Long press ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) 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](../basics/state.md#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.java) on Android. - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to the `LongPressGestureHandler` component: - -### `minDurationMs` - -Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. - -### `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](../basics/state.md#active), it will fail to recognize the gesture. The default value is 10. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to the `LongPressGestureHandler` component: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `duration` - -Duration of the long press (time since the start of the event), expressed in milliseconds. - -## Example - -See the [multitap example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from GestureHandler Example App. - -```js -const LongPressButton = () => ( - { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert("I'm being pressed for so long"); - } - }} - minDurationMs={800}> - - -); -``` diff --git a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/pan-gh.md b/docs/versioned_docs/version-2.4.0/gesture-handlers/api/pan-gh.md deleted file mode 100644 index 4b2daeaff0..0000000000 --- a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/pan-gh.md +++ /dev/null @@ -1,225 +0,0 @@ ---- -id: pan-gh -title: PanGestureHandler -sidebar_label: Pan ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A continuous gesture handler that can recognize a panning (dragging) gesture and track its movement. - -The handler [activates](../basics/state.md#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. - -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. - -The handler is implemented using [UIPanGestureRecognizer](https://developer.apple.com/documentation/uikit/uipangesturerecognizer) on iOS and [PanGestureHandler](https://github.com/software-mansion/react-native-gesture-handler/blob/main/android/lib/src/main/java/com/swmansion/gesturehandler/PanGestureHandler.java) on Android. - -## 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](../basics/state.md#active) or [fail](../basics/state.md#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. -Another example would be setting both [`maxDeltaX`](#maxdeltaX) and [`maxDeltaY`](#maxdeltay) to 20 and [`minDist`](#mindist) to 23. -In such a case, if we move a finger along the X-axis by 20 points and along the Y-axis by 0 points, the handler will fail even though the finger is still within the bounds of translation along Y-axis. - -## 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. - -The default behavior for native components like scroll view, pager views or drawers is different and hence gesture handler 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 [`avgTouches`](#avgtouches-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)). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#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](../basics/state.md#active). Expressed in points. - -### `minPointers` - -A number of fingers that is required to be placed before handler can [activate](../basics/state.md#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](../basics/state.md#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. - -### `activeOffsetX` - -Range along X axis (in points) where fingers travels without activation of handler. Moving outside of this range implies activation of handler. 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` - -Range along Y axis (in points) where fingers travels without activation of handler. Moving outside of this range implies activation of handler. 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` - -When the finger moves outside this range (in points) along Y axis and handler 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` - -When the finger moves outside this range (in points) along X axis and handler 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. - -### `maxDeltaX` - -> 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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#active) for the movement in one particular direction use [`minOffsetY`](#minoffsety) instead. - -### `avgTouches` (Android only) - -### `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. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `PanGestureHandler`: - -### `translationX` - -Translation of the pan gesture along X axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `translationY` - -Translation of the pan gesture along Y axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `velocityX` - -Velocity of the pan gesture along the X axis in the current moment. The value is expressed in point units per second. - -### `velocityY` - -Velocity of the pan gesture along the Y axis in the current moment. The value is expressed in point units per second. - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - -## Example - -See the [draggable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/draggable/index.tsx) from Gesture Handler Example App. - -```js -import React, { Component } from 'react'; -import { Animated, Dimensions } from 'react-native'; -import { - GestureHandlerRootView, - PanGestureHandler, -} from 'react-native-gesture-handler'; - -const { width } = Dimensions.get('screen'); -const circleRadius = 30; - -class Circle extends Component { - _touchX = new Animated.Value(width / 2 - circleRadius); - - _onPanGestureEvent = Animated.event([{ nativeEvent: { x: this._touchX } }], { - useNativeDriver: true, - }); - - render() { - return ( - - - - - - - - ); - } -} - -export default function App() { - return ; -} -``` diff --git a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/pinch-gh.md b/docs/versioned_docs/version-2.4.0/gesture-handlers/api/pinch-gh.md deleted file mode 100644 index beaa3fb778..0000000000 --- a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/pinch-gh.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: pinch-gh -title: PinchGestureHandler -sidebar_label: Pinch ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) 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](../basics/state.md#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. - -The handler is implemented using [UIPinchGestureRecognizer](https://developer.apple.com/documentation/uikit/uipinchgesturerecognizer) on iOS and from scratch on Android. - -## Properties - -Properties provided to `PinchGestureHandler` do not extend [common set of properties from base handler class](./common-gh.md#properties). - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `PinchGestureHandler`: - -### `scale` - -The scale factor relative to the points of the two touches in screen coordinates. - -### `velocity` - -Velocity of the pan gesture the current moment. The value is expressed in point units per second. - -### `focalX` - -Position expressed in points along X axis of center anchor point of gesture - -### `focalY` - -Position expressed in points along Y axis of center anchor point of gesture - -## Example - -See the [scale and rotation example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from Gesture Handler Example App. - -```js -export class PinchableBox extends React.Component { - _baseScale = new Animated.Value(1); - _pinchScale = new Animated.Value(1); - _scale = Animated.multiply(this._baseScale, this._pinchScale); - _lastScale = 1; - _onPinchGestureEvent = Animated.event( - [{ nativeEvent: { scale: this._pinchScale } }], - { useNativeDriver: USE_NATIVE_DRIVER } - ); - - _onPinchHandlerStateChange = (event) => { - if (event.nativeEvent.oldState === State.ACTIVE) { - this._lastScale *= event.nativeEvent.scale; - this._baseScale.setValue(this._lastScale); - this._pinchScale.setValue(1); - } - }; - - render() { - return ( - - - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/tap-gh.md b/docs/versioned_docs/version-2.4.0/gesture-handlers/api/tap-gh.md deleted file mode 100644 index 74fa3ee114..0000000000 --- a/docs/versioned_docs/version-2.4.0/gesture-handlers/api/tap-gh.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -id: tap-gh -title: TapGestureHandler -sidebar_label: Tap ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A discrete gesture handler 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 handler to [activate](../basics/state.md#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](../basics/state.md#active), it will [END](../basics/state.md#end). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#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](../basics/state.md#active). Should be a positive integer. The default value is 1. - -### `maxDurationMs` - -Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch. The default value is 500. - -### `maxDelayMs` - -Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required. The default value is 500. - -### `numberOfTaps` - -Number of tap gestures required to [activate](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#active), it will fail to recognize the gesture. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to the `TapGestureHandler` component: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -## Example - -See the [multitap example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from GestureHandler Example App. - -```js -export class PressBox extends Component { - doubleTapRef = React.createRef(); - render() { - return ( - - - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.4.0/gesture-handlers/basics/about-handlers.md b/docs/versioned_docs/version-2.4.0/gesture-handlers/basics/about-handlers.md deleted file mode 100644 index 4c2062a24f..0000000000 --- a/docs/versioned_docs/version-2.4.0/gesture-handlers/basics/about-handlers.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -id: about-handlers -title: About Gesture Handlers -sidebar_label: About Gesture Handlers ---- - -Gesture handlers are the core building blocks of this library. -We use this term to describe elements of the native touch system that the library allows us to instantiate and control from Javascript using [React's Component](https://reactjs.org/docs/react-component.html) interface. - -Each handler type is capable of recognizing one type of gesture (pan, pinch, etc.) and provides gesture-specific information via events (translation, scale, 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](./state.md). -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](./state.md#active), it cancels all the other gestures (read more about how to influence this process in ["Cross handler interactions"](./interactions.md) 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. - -### Available gesture handlers - -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`](../api/pan-gh.md) -- [`TapGestureHandler`](../api/tap-gh.md) -- [`LongPressGestureHandler`](../api/longpress-gh.md) -- [`RotationGestureHandler`](../api/rotation-gh.md) -- [`FlingGestureHandler`](../api/fling-gh.md) -- [`PinchGestureHandler`](../api/pinch-gh.md) -- [`ForceTouchGestureHandler`](../api/force-gh.md) - -### Discrete vs continuous - -We distinguish between two types of gestures: discrete and continuous. - -Continuous gesture handlers can be [active](./state.md#active) for a long period of time and will generate a stream of [gesture events](../api/common-gh.md#ongestureevent) until the gesture is [over](./state.md#ended). -An example of a continuous handler is [`PanGestureHandler`](../api/pan-gh.md) that once [activated](./state.md#active), will start providing updates about [translation](../api/pan-gh.md#translationx) and other properties. - -On the other hand, discrete gesture handlers once [activated](./state.md#active) will not stay in the active state but will [end](./state.md#ended) immediately. -[`LongPressGestureHandler`](../api/longpress-gh.md) 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`](../api/pan-gh.md)). - -Keep in mind that `onGestureEvent` is only generated in continuous gesture handlers and shouldn't be used in the `TapGestureHandler` and other discrete handlers. - -### Nesting handlers - -Handler components can be nested. In any case it is recommended that the innermost handler renders a native view component. There are some limitations that apply when [using `useNativeDriver` flag](#events-with-usenativedriver). An example of nested handlers: - -```js -class Multitap extends Component { - render() { - return ( - - - - - - - - ); - } -} -``` - -### Using native components - -Gesture handler library exposes a set of components normally available in React Native that are wrapped in [`NativeViewGestureHandler`](../api/nativeview-gh.md). -Here is a list of exposed components: - -- `ScrollView` -- `FlatList` -- `Switch` -- `TextInput` -- `DrawerLayoutAndroid` (**Android only**) - -If you want to use other handlers or [buttons](../../api/components/buttons.mdx) nested in a `ScrollView`, use the [`waitFor`](../api/common-gh.md#waitfor) property to define interaction between a handler and `ScrollView` - -### Events with `useNativeDriver` - -Because handlers do not instantiate native views but instead hook up to their child views, directly nesting two gesture handlers using `Animated.event` is not currently supported. -To workaround this limitation we recommend placing an `` component in between the handlers. - -Instead of doing: - -```js -const PanAndRotate = () => ( - - - - - -); -``` - -Place an `` in between the handlers: - -```js -const PanAndRotate = () => ( - - - - - - - -); -``` - -Another consequence of handlers depending on their native child components is that when using a `useNativeDriver` flag with an `Animated.event`, the child component must be wrapped by an `Animated.API` e.g. `` instead of just a ``: - -```js -class Draggable extends Component { - render() { - return ( - - {/* <-- NEEDS TO BE Animated.View */} - - ); - } -}; -``` diff --git a/docs/versioned_docs/version-2.4.0/gesture-handlers/basics/state.md b/docs/versioned_docs/version-2.4.0/gesture-handlers/basics/state.md deleted file mode 100644 index 1f15f94f2f..0000000000 --- a/docs/versioned_docs/version-2.4.0/gesture-handlers/basics/state.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: state -title: Handler State -sidebar_label: Handler State ---- - -As described in ["About Gesture Handlers"](./about-handlers.md), 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: - -- [UNDETERMINED](#undetermined) -- [FAILED](#failed) -- [BEGAN](#began) -- [CANCELLED](#cancelled) -- [ACTIVE](#active) -- [END](#end) - -Each state has its own description below. - -## Accessing state - -We can monitor a handler's state changes by using the [`onHandlerStateChange`](../api/common-gh.md#onhandlerstatechange) callback and the destructured `nativeEvent` argument passed to it. -This can be done by comparing the `nativeEvent`'s [`state`](../api/common-gh.md#state) attribute to one of the constants exported under the `State` object (see example below). - -``` -import { State, LongPressGestureHandler } from 'react-native-gesture-handler'; - -class Demo extends Component { - _handleStateChange = ({ nativeEvent }) => { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert('Longpress'); - } - }; - render() { - return ( - - Longpress me - - ); - } -} -``` - -## State flows - -The most typical flow of state is when a gesture handler picks up on an initial touch event then recognizes it then acknowledges its ending then resets itself back to the initial state. - -The flow looks as follows (longer arrows represent that there are possibly more touch events received before the state changes): - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`END`](#end) -> [`UNDETERMINED`](#undetermined) - -Another possible flow is when a handler receives touches that cause a recognition failure: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`FAILED`](#failed) -> [`UNDETERMINED`](#undetermined) - -At last, when a handler does properly recognize the gesture but then is interrupted by the touch system. In that case, the gesture recognition is canceled and the flow looks as follows: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`CANCELLED`](#cancelled) -> [`UNDETERMINED`](#undetermined) - -## States - -The section below describes all possible handler states: - -### UNDETERMINED - -This is the initial state of each handler and it goes into this state after it's done recognizing a gesture. - -### FAILED - -A handler 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 handler won't become active but will fail instead. Afterwards, it's state will be reset to `UNDETERMINED`. - -### BEGAN - -Handler 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 - -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](about-handlers#discrete-vs-continuous) to understand how long a handler can be kept in the `ACTIVE` state. - -### END - -The gesture recognizer has received touches signalling the end of a gesture. Its state will become `END` until it is reset to `UNDETERMINED`. diff --git a/docs/versioned_docs/version-2.4.0/guides/migrating-off-rnghenabledroot.md b/docs/versioned_docs/version-2.4.0/guides/migrating-off-rnghenabledroot.md deleted file mode 100644 index b72293fa64..0000000000 --- a/docs/versioned_docs/version-2.4.0/guides/migrating-off-rnghenabledroot.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -id: migrating-off-rnghenabledroot -title: Migrating off RNGHEnabledRootView ---- - -## Update `MainActivity.java` - -Update your `MainActivity.java` file (or wherever you create an instance of `ReactActivityDelegate`), so that it no longer overrides the method responsible for creating `ReactRootView` instance, or modify it so that it no longer uses `RNGestureHandlerEnabledRootView`. Do not forget to remove import for `RNGestureHandlerEnabledRootView`: - -```java -package com.swmansion.gesturehandler.react.example; - -import com.facebook.react.ReactActivity; -- import com.swmansion.gesturehandler.react.RNGestureHandlerEnabledRootView; -public class MainActivity extends ReactActivity { - -- @Override -- protected ReactActivityDelegate createReactActivityDelegate() { -- return new ReactActivityDelegate(this, getMainComponentName()) { -- @Override -- protected ReactRootView createRootView() { -- return new RNGestureHandlerEnabledRootView(MainActivity.this); -- } -- }; -- } -} -``` - -## Check if your app works correctly - -Some libraries (for example React Navigation) already use `GestureHandlerRootView` as a wrapper to enable gesture interactions. In that case you don't have to add one yourself. If gestures in your app work as expected after removing `RNGestureHandlerEnabledRootView` you can skip the next step. - -## Update your JS code - -Instead of using `RNGestureHandlerEnabledRootView` wrap your entry point with `` or `gestureHandlerRootHOC`, for example: - -```jsx -export default function App() { - return {/* content */}; -} -``` - -:::info -Note that `GestureHandlerRootView` acts like a normal `View`. So if you want it to fill the screen, you will need to pass `{ flex: 1 }` like you'll need to do with a normal View. By default, it'll take the size of the content nested inside. -::: \ No newline at end of file diff --git a/docs/versioned_docs/version-2.4.0/guides/testing.md b/docs/versioned_docs/version-2.4.0/guides/testing.md deleted file mode 100644 index 980160bdbd..0000000000 --- a/docs/versioned_docs/version-2.4.0/guides/testing.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -id: testing -title: Testing with Jest ---- - -## Mocking native modules - -In order to load mocks provided by RNGH add following to your jest config in `package.json`: - -```json -"setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"] -``` - -Example: - -```json -"jest": { - "preset": "react-native", - "setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"] -} -``` - -## Testing Gestures' and Gesture handlers' callbacks - -RNGH provides an API for triggering selected handlers: - -- [`fireGestureHandler(gestureOrHandler, eventList)`](../api/test-api#firegesturehandlergestureorhandler-eventlist) -- [`getByGestureTestId(testID)`](../api/test-api#getbygesturetestidtestid) diff --git a/docs/versioned_docs/version-2.4.0/guides/upgrading-to-2.md b/docs/versioned_docs/version-2.4.0/guides/upgrading-to-2.md deleted file mode 100644 index 36ff261b6e..0000000000 --- a/docs/versioned_docs/version-2.4.0/guides/upgrading-to-2.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -id: upgrading-to-2 -title: Upgrading to the new API introduced in Gesture Handler 2 ---- - -## Make sure to migrate off the `RNGestureHandlerEnabledRootView` (Android only) - -Gesture Handler 1 required you to override `createRootView` to return an instance of `RNGestureHandlerEnabledRootView`. This class has been the cause of many hard to debug and fix crashed and was deprecated in version 2.0, and subsequently removed in version 2.4. If you are still using it, check out [migrating off RNGHEnabledRootView guide](./migrating-off-rnghenabledroot.md). - -## Upgrading to the new API - -The most important change brought by the Gesture Handler 2 is the new Gesture API, along with the `GestureDetector` component. It makes declaring gesture easier, as it handles much of the work under the hood and reduces the amount of necessary boilerplate code. Instead of a separate component for every type of gesture, the `GestureDetector` component is used to attach gestures to the underlying view based on the configuration object passed to it. The configuration objects are created using the `Gesture` object, here is a simple example: - -```jsx -const tapGesture = Gesture.Tap().onStart(() => { - console.log('Tap!'); -}); -... -return ( - - - -); -``` - -As you can see, there are no `onGestureEvent` and `onHandlerStateChange` callbacks, instead the state machine is handled under the hood and relevant callbacks are called for specific transitions or events: -- `onBegin` - called when the gesture transitions to the `BEGAN` state, which in most cases is when the gesture starts processing the touch stream - when the finger first touches the view -- `onStart` - called when the activation criteria for the gesture are met and it transitions from `BEGAN` to `ACTIVE` state -- `onUpdate` - replaces `onGestureEvent`, called every time the gesture sends a new event while it's in the `ACTIVE` state -- `onChange` - if defined, called just after `onUpdate`, the events passed to it are the same as the ones passed to `onUpdate` but they also contain `change` values which hold the change in value they represent since the last event (i.e. in case of the `Pan` gesture, the event will also contain `changeX` and `changeY` properties) -- `onEnd` - called when the gesture transitions from the `ACTIVE` state to either of `END`, `FAILED` or `CANCELLED` - you can tell whether the gesture finished due to user interaction or because of other reason (like getting cancelled by the system, or failure criteria) using the second value passed to the `onEnd` callback alongside the event -- `onFinalize` called when the gesture transitions into either of `END`, `FAILED` or `CANCELLED` state, if the gesture was `ACTIVE`, `onEnd` will be called first (similarily to `onEnd` you can determine the reason for finishing using the second argument) - -The difference between `onEnd` and `onFinalize` is that the `onEnd` will be called only if the gesture was `ACTIVE`, while `onFinalize` will be called if the gesture has `BEGAN`. This means that you can use `onEnd` to clean up after `onStart`, and `onFinalize` to clean up after `onBegin` (or both `onBegin` and `onStart`). - -### Configuring the gestures - -The new gesture objects are configured in the builder-like pattern. Instead of properties, each gesture provides methods that allow for its customization. In most cases the names of the methods are the same as the relevant props, ot at least very similar. For example: - -```jsx -return ( - { - if (nativeEvent.state === State.ACTIVE) { - console.log('Tap!'); - } - }}> - - -); -``` - -Would have the same effect as: - -```jsx -const tapGesture = Gesture.Tap() - .numberOfTaps(2) - .maxDuration(500) - .maxDelay(500) - .maxDistance(10) - .onStart(() => { - console.log('Tap!'); - }); - -return ( - - - -); -``` - -You can check the modifiers available to specific gestures in the API Reference under Gestures. - -### Using multiple gestures on the same view - -Using the gesture handler components, if you wanted to have multiple gestures on one view, you would have to stack them on top of each other and, in case you wanted to use animations, add an `Animated.View` after each handler, resulting in a deep component tree, for example: - -```jsx -return ( - - - - - - - - - - - -); -``` - -With the `GestureDetector` you can use the [Gesture Composition API](../gesture-composition.md) to stack the gestures onto one view: - -```jsx -const tapGesture = Gesture.Tap(); -const panGesture = Gesture.Pan(); -const pinchGesture = Gesture.Pinch(); - -return ( - - - -); -``` - -Similarily, you can use [`Gesture.Simultaneous`](../gesture-composition.md#simultaneous) to replace stacked gesture handlers that should be able to recognize gestures simultaneously, and [`Gesture.Exclusive`](../gesture-composition.md#exclusive) to replace stacked gesture handlers that require failure of others. - -### Replacing `waitFor` and `simultaneousHandlers` - -If you want to make relations between the gestures attached to the same view, you should use the [Gesture Composition API](../gesture-composition.md) described above. However, if you want to make a relation between gestures attached to different views, or between gesture and an old gesture handler, you should use `simultaneousWithExternalGesture` instead of `simultaneousHandlers`, and `requireExternalGestureToFail` instead of `waitFor`. In case you need a ref object to pass to an old gesture handler, you can set it to the gesture using `.withRef(refObject)` modifier. \ No newline at end of file diff --git a/docs/versioned_docs/version-2.4.0/installation.md b/docs/versioned_docs/version-2.4.0/installation.md deleted file mode 100644 index 229c1b5429..0000000000 --- a/docs/versioned_docs/version-2.4.0/installation.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -id: installation -title: Installation ---- - -## Requirements - -| version | `react-native` version | -| --------- | ---------------------- | -| 2.0.0+ | 0.63.0+ | -| 1.4.0+ | 0.60.0+ | -| 1.1.0+ | 0.57.2+ | -| <1.1.0 | 0.50.0+ | - -It may be possible to use newer versions of react-native-gesture-handler on React Native with version <= 0.59 by reverse Jetifying. -Read more on that here https://github.com/mikehardy/jetifier#to-reverse-jetify--convert-node_modules-dependencies-to-support-libraries - -Note that if you wish to use [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html) support for [interactions](./gesture-handlers/basics/interactions.md) you need to use v16.3 of [React](https://reactjs.org/) - -In order to fully utilize the [touch events](./api/gestures/touch-events.md) you also need to use `react-native-reanimated` 2.3.0-beta.4 or newer. - -## Expo - -### Managed [Expo](https://expo.io) - -To use the version of react-native-gesture-handler that is compatible with your managed Expo project, run `expo install react-native-gesture-handler`. - -The Expo SDK incorporates the latest version of react-native-gesture-handler available at the time of each SDK release, so managed Expo apps might not always support all our latest features as soon as they are available. - -### Bare [React Native](http://facebook.github.io/react-native/) - -Since the library uses native support for handling gestures, it requires an extended installation to the norm. If you are starting a new project, you may want to initialize it with [expo-cli](https://docs.expo.io/versions/latest/workflow/expo-cli/) and use a bare template, they come pre-installed with react-native-gesture-handler. - -## JS - -First, install the library using `yarn`: - -```bash -yarn add react-native-gesture-handler -``` - -or with `npm` if you prefer: - -```bash -npm install --save react-native-gesture-handler -``` - -After installation, wrap your entry point with `` or -`gestureHandlerRootHOC`. - -For example: - -```js -export default function App() { - return {/* content */}; -} -``` - -:::info -If you use props such as `shouldCancelWhenOutside`, `simultaneousHandlers`, `waitFor` etc. with gesture handlers, the handlers need to be mounted under a single `GestureHandlerRootView`. So it's important to keep the `GestureHandlerRootView` as close to the actual root view as possible. - -Note that `GestureHandlerRootView` acts like a normal `View`. So if you want it to fill the screen, you will need to pass `{ flex: 1 }` like you'll need to do with a normal `View`. By default, it'll take the size of the content nested inside. -::: - -:::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. -::: - -### Linking - -> **Important**: You only need to do this step if you're using React Native 0.59 or lower. Since v0.60, linking happens automatically. - -```bash -react-native link react-native-gesture-handler -``` - -## Fabric -Starting with version 2.3.0, Gesture Handler now supports [Fabric](https://reactnative.dev/docs/fabric-renderer)!. To use Gesture Handler in your Fabric application you have to: -#### on iOS: -Install pods using `RCT_NEW_ARCH_ENABLED=1 pod install` – this is the same command you run to prepare a Fabric build but you also need to run it after a new native library gets added. -#### on Android: -There are no additional steps required so long as your app is configured to build with Fabric – this is typically configured by setting `newArchEnabled=true` in `gradle.properties` file in your project. - -### 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` (you can do this using `gestureHandlerRootHOC` function). This can be done for example at the stage when you register your screens. Here's an example: - -```js -import { gestureHandlerRootHOC } from 'react-native-gesture-handler'; -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', - () => gestureHandlerRootHOC(FirstTabScreen), - () => FirstTabScreen - ); - Navigation.registerComponent('example.SecondTabScreen', - () => gestureHandlerRootHOC(SecondTabScreen), - () => SecondTabScreen - ); - Navigation.registerComponent('example.PushedScreen', - () => gestureHandlerRootHOC(PushedScreen), - () => 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` (you can do this using `gestureHandlerRootHOC` function) as with native navigation libraries each screen maps to a separate root view. It will not be enough to wrap the main screen only. - -## Android - -### Usage with modals on Android - -On Android RNGH does not work by default because modals are not located under React Native Root view in native hierarchy. -To fix that, components need to be wrapped with `gestureHandlerRootHOC` (it's no-op on iOS and web). - -For example: - -```js -const ExampleWithHoc = gestureHandlerRootHOC(() => ( - - - - ); -); - -export default function Example() { - return ( - - - - ); -} -``` - -### Kotlin - -Since version `2.0.0` RNGH has been rewritten with Kotlin. The default version of the Kotlin plugin used in this library is `1.5.20`. - -If you need to use a different Kotlin version, set the `kotlinVersion` ext property in `android/build.gradle` file and RNGH will use that version: - -``` -buildscript { - ext { - ... - kotlinVersion = "1.5.20" - } -} -``` - -The minimal version of the Kotlin plugin supported by RNGH is `1.4.10`. - -## iOS - -There is no additional configuration required on iOS except what follows in the next steps. - -If you're in a CocoaPods project (the default setup since React Native 0.60), -make sure to install pods before you run your app: - -```bash -cd ios && pod install -``` - -For React Native 0.61 or greater, add the library as the first import in your index.js file: - -```js -import 'react-native-gesture-handler'; -``` diff --git a/docs/versioned_docs/version-2.4.0/introduction.md b/docs/versioned_docs/version-2.4.0/introduction.md deleted file mode 100644 index 7f436751cc..0000000000 --- a/docs/versioned_docs/version-2.4.0/introduction.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -id: introduction -title: Introduction -sidebar_label: Introduction -slug: / ---- - -Gesture Handler aims to replace React Native's built in touch system called [Gesture Responder System](http://facebook.github.io/react-native/docs/gesture-responder-system). - -The motivation for building this library was to address the performance limitations of React Native's Gesture Responder System and to provide more control over the built-in native components that can handle gestures. -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. - -In a nutshell, the library provides: - -- A way to use a platform's native touch handling system for recognizing pinch, rotation and pan (besides a few other gestures). -- The ability to define relations between gesture handlers, e.g. when you have a pan handler in `ScrollView` you can make that `ScrollView` wait until it knows pan won't recognize. -- Mechanisms to use touchables 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. - -:::info -It is recommended to use Reanimated 2 for animations when using React Native Gesture Handler as its more advanced features rely heavily on the worklets provided by Reanimated. -::: - -## RNGH 2.0 - -RNGH2 introduces a new way of creating gestures. Instead of creating a gesture handler component for every gesture you want to create, you just need to create a `GestureDetector` component and assign to it all the gestures you want it to recognize. It is also designed to work seamlessly with `Reanimated 2` and it will automatically detect if it is installed, and start using it if it is. -You can create gestures using the `Gesture` object and methods it provides, and configure them in the builder-like pattern. If you want to specify behavior between the gestures instead of using `waitFor` and `simultaneousGestures` you can use the new system of [gesture composition](./gesture-composition). -Along the new API, version 2.0 brings one of the most requested features: [touch events and manual gestures](manual-gestures). Thanks to great work done by the Reanimated team, we were able to provide synchronous communication between gestures and their native implementation using worklets. This allows to manage gesture state from the JS without risking race-conditions. - -### Interoperability with gesture handlers - -The new API with gestures is somewhat compatible with the old gesture handlers. Unfortunately you cannot use the new gesture composing with gesture handlers, however you can still mark relations using refs. If you want to make a gesture handler wait for (or simultaneous with) a gesture, simply use withRef method on the gesture to set the ref object and pass it to the appropriate property on the gesture handler. - -Similarly, if you want to make a gesture simultaneous with (or wait for failure of) a gesture handler, set the ref prop of the gesture handler and pass the same ref to the simultaneousWithExternalGesture or requireExternalGestureToFail method on the gesture object. - -This should allow you to migrate your codebase from the gesture handlers to gestures smoothly and at your own pace. Just keep in mind that the gesture handlers cannot have the GestureDetector as their direct child, as it's a functional component. - -## Learning resources - -### Apps - -[Gesture Handler Example App](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example) – official gesture handler "showcase" app. - -[Gesture Handler Example on Expo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo) – the official app you can install and play with using [Expo](https://expo.io). - -### 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 Vetne](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 [me on Twitter](https://twitter.com/kzzzf)! - -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
-
- -
-
- -
-
Jakub Gonet
-
- -
-
- -
-
Krzysztof Magiera
- @kzzzf -
- -
- -### 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: - -
- -
- -
- -
-
Shopify
- -
- -
- -
- -
-
Expo
- -
- -
diff --git a/docs/versioned_docs/version-2.4.0/manual-gestures/manual-gestures.md b/docs/versioned_docs/version-2.4.0/manual-gestures/manual-gestures.md deleted file mode 100644 index eae7fffd2d..0000000000 --- a/docs/versioned_docs/version-2.4.0/manual-gestures/manual-gestures.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -id: manual-gestures -title: Manual gestures -sidebar_label: Manual gestures ---- - -import Step, { Divider } from '@site/src/theme/Step'; -import Step1 from './step1.md'; -import Step2 from './step2.md'; -import Step3 from './step3.md'; -import Step4 from './step4.md'; -import Step5 from './step5.md'; -import Step6 from './step6.md'; -import Step7 from './step7.md'; - -RNGH2 finally brings one of the most requested features: manual gestures and touch events. To demonstrate how to make a manual gesture we will make a simple one that tracks all pointers on the screen. - - - - - First, we need a way to store information about the pointer: whether it should be visible and its position. - - - - - - - We also need a component to mark where a pointer is. In order to accomplish that we will make a component that accepts two shared values: one holding information about the pointer using the interface we just created, the other holding a bool indicating whether the gesture has activated. - In this example when the gesture is not active, the ball representing it will be blue and when it is active the ball will be red and slightly bigger. - - - - - - - Now we have to make a component that will handle the gesture and draw all the pointer indicators. We will store data about pointers in an array of size 12 as that is the maximum number of touches that RNGH will track, and render them inside an Animated.View. - - - - - - - We have our components set up and we can finally get to making the gesture! We will start with onTouchesDown where we need to set position of the pointers and make them visible. We can get this information from the touches property of the event. In this case we will also check how many pointers are on the screen and activate the gesture if there are at least two. - - - - - - - Next, we will handle pointer movement. In onTouchesMove we will simply update the position of moved pointers. - - - - - - - We also need to handle lifting fingers from the screen, which corresponds to onTouchesUp. Here we will just hide the pointers that were lifted and end the gesture if there are no more pointers on the screen. - Note that we are not handling onTouchesCancelled as in this very basic case we don't expect it to happen, however you should clear data about cancelled pointers (most of the time all active ones) when it is called. - - - - - - - Now that our pointers are being tracked correctly and we have the state management, we can handle activation and ending of the gesture. In our case, we will simply set the active shared value either to true or false. - - - - - -And that's all! As you can see using manual gestures is really easy but as you can imagine, manual gestures are a powerful tool that makes it possible to accomplish things that were previously impossible with RNGH. - -## Modifying existing gestures - -While manual gestures open great possibilities we are aware that reimplementing pinch or rotation from scratch just because you need to activate in specific circumstances or require position of the fingers, would be a waste of time as those gestures are already there. Because of that you can use touch events with every gesture so that you can extract more informations about gesture than is sent to you in events. We also added a `manualActivation` modifier on all continous gestures, which prevents the gesture it is applied to from activating by itself thus giving you full control of its behavior. - -This functionality makes another highly requested feature possible: drag after long press. Simply set `manualActivation` to `true` on a `PanGesture` and use `StateManager` to fail the gesture if the user attempts to drag the component sooner than the duration of the long press. diff --git a/docs/versioned_docs/version-2.4.0/manual-gestures/step1.md b/docs/versioned_docs/version-2.4.0/manual-gestures/step1.md deleted file mode 100644 index 4c6331c1c8..0000000000 --- a/docs/versioned_docs/version-2.4.0/manual-gestures/step1.md +++ /dev/null @@ -1,7 +0,0 @@ -```jsx -interface Pointer { - visible: boolean; - x: number; - y: number; -} -``` diff --git a/docs/versioned_docs/version-2.4.0/manual-gestures/step2.md b/docs/versioned_docs/version-2.4.0/manual-gestures/step2.md deleted file mode 100644 index 3137d334ef..0000000000 --- a/docs/versioned_docs/version-2.4.0/manual-gestures/step2.md +++ /dev/null @@ -1,35 +0,0 @@ -```jsx -function PointerElement(props: { - pointer: Animated.SharedValue, - active: Animated.SharedValue, -}) { - const animatedStyle = useAnimatedStyle(() => ({ - transform: [ - { translateX: props.pointer.value.x }, - { translateY: props.pointer.value.y }, - { - scale: - (props.pointer.value.visible ? 1 : 0) * - (props.active.value ? 1.3 : 1), - }, - ], - backgroundColor: props.active.value ? 'red' : 'blue', - })); - - return ; -} - -... - -const styles = StyleSheet.create({ - pointer: { - width: 60, - height: 60, - borderRadius: 30, - backgroundColor: 'red', - position: 'absolute', - marginStart: -30, - marginTop: -30, - }, -}); -``` diff --git a/docs/versioned_docs/version-2.4.0/manual-gestures/step3.md b/docs/versioned_docs/version-2.4.0/manual-gestures/step3.md deleted file mode 100644 index c9b32e5c2a..0000000000 --- a/docs/versioned_docs/version-2.4.0/manual-gestures/step3.md +++ /dev/null @@ -1,29 +0,0 @@ -```jsx -export default function Example() { - const trackedPointers: Animated.SharedValue[] = []; - const active = useSharedValue(false); - - for (let i = 0; i < 12; i++) { - trackedPointers[i] = - useSharedValue < - Pointer > - { - visible: false, - x: 0, - y: 0, - }; - } - - const gesture = Gesture.Manual(); - - return ( - - - {trackedPointers.map((pointer, index) => ( - - ))} - - - ); -} -``` diff --git a/docs/versioned_docs/version-2.4.0/manual-gestures/step4.md b/docs/versioned_docs/version-2.4.0/manual-gestures/step4.md deleted file mode 100644 index 36ec2c34bd..0000000000 --- a/docs/versioned_docs/version-2.4.0/manual-gestures/step4.md +++ /dev/null @@ -1,15 +0,0 @@ -```jsx {2-15} -const gesture = Gesture.Manual().onTouchesDown((e, manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: true, - x: touch.x, - y: touch.y, - }; - } - - if (e.numberOfTouches >= 2) { - manager.activate(); - } -}); -``` diff --git a/docs/versioned_docs/version-2.4.0/manual-gestures/step5.md b/docs/versioned_docs/version-2.4.0/manual-gestures/step5.md deleted file mode 100644 index d2f9377cc8..0000000000 --- a/docs/versioned_docs/version-2.4.0/manual-gestures/step5.md +++ /dev/null @@ -1,13 +0,0 @@ -```jsx {3-12} -const gesture = Gesture.Manual() - ... - .onTouchesMove((e, _manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: true, - x: touch.x, - y: touch.y, - }; - } - }) -``` diff --git a/docs/versioned_docs/version-2.4.0/manual-gestures/step6.md b/docs/versioned_docs/version-2.4.0/manual-gestures/step6.md deleted file mode 100644 index 323f9516cb..0000000000 --- a/docs/versioned_docs/version-2.4.0/manual-gestures/step6.md +++ /dev/null @@ -1,17 +0,0 @@ -```jsx {3-16} -const gesture = Gesture.Manual() - ... - .onTouchesUp((e, manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: false, - x: touch.x, - y: touch.y, - }; - } - - if (e.numberOfTouches === 0) { - manager.end(); - } - }) -``` diff --git a/docs/versioned_docs/version-2.4.0/manual-gestures/step7.md b/docs/versioned_docs/version-2.4.0/manual-gestures/step7.md deleted file mode 100644 index 913e766ae8..0000000000 --- a/docs/versioned_docs/version-2.4.0/manual-gestures/step7.md +++ /dev/null @@ -1,10 +0,0 @@ -```jsx {3-10} -const gesture = Gesture.Manual() - ... - .onStart(() => { - active.value = true; - }) - .onEnd(() => { - active.value = false; - }); -``` diff --git a/docs/versioned_docs/version-2.4.0/quickstart/quickstart.md b/docs/versioned_docs/version-2.4.0/quickstart/quickstart.md deleted file mode 100644 index c1ba3d7219..0000000000 --- a/docs/versioned_docs/version-2.4.0/quickstart/quickstart.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -id: quickstart -title: Quick start -sidebar_label: Quick start ---- - -import Step, { Divider } from '@site/src/theme/Step'; -import Step1 from './step1.md'; -import Step2 from './step2.md'; -import Step3 from './step3.md'; -import Step4 from './step4.md'; -import Step5 from './step5.md'; - -RNGH2 provides much simpler way to add gestures to your app. All you need to do is wrap the view that you want your gesture to work on with [`GestureDetector`](../api/gestures/gesture-detector), define the gesture and pass it to detector. That's all! - -To demonstrate how you would use the new API, let's make a simple app where you can drag a ball around. You will need to add `react-native-gesture-handler` (for gestures) and `react-native-reanimated` (for animations) modules. - - - - -
First let's define styles we will need to make the app:
- - - - - - -
Then we can start writing our `Ball` component:
- - - - - - -
- We also need to define{' '} - - shared values - {' '} - to keep track of the ball position and create animated styles in order to be - able to position the ball on the screen: -
- - - - - - -
And add it to the ball's styles:
- - - - - - -
- The only thing left is to define the pan gesture and assign it to the - detector: -
- - - - - -Note the `start` shared value. We need it to store the position of the ball at the moment we grab it to be able to correctly position it later, because we only have access to translation relative to the starting point of the gesture. - -Now you can just add `Ball` component to some view in the app and see the results! (Or you can just check the code [here](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/new_api/reanimated/index.tsx) and see it in action in the Example app.) diff --git a/docs/versioned_docs/version-2.4.0/quickstart/step1.md b/docs/versioned_docs/version-2.4.0/quickstart/step1.md deleted file mode 100644 index 1995cd907c..0000000000 --- a/docs/versioned_docs/version-2.4.0/quickstart/step1.md +++ /dev/null @@ -1,11 +0,0 @@ -```jsx -const styles = StyleSheet.create({ - ball: { - width: 100, - height: 100, - borderRadius: 100, - backgroundColor: 'blue', - alignSelf: 'center', - }, -}); -``` diff --git a/docs/versioned_docs/version-2.4.0/quickstart/step2.md b/docs/versioned_docs/version-2.4.0/quickstart/step2.md deleted file mode 100644 index 34c528266b..0000000000 --- a/docs/versioned_docs/version-2.4.0/quickstart/step2.md +++ /dev/null @@ -1,9 +0,0 @@ -```jsx -function Ball() { - return ( - - - - ); -} -``` diff --git a/docs/versioned_docs/version-2.4.0/quickstart/step3.md b/docs/versioned_docs/version-2.4.0/quickstart/step3.md deleted file mode 100644 index ee7184ffc7..0000000000 --- a/docs/versioned_docs/version-2.4.0/quickstart/step3.md +++ /dev/null @@ -1,14 +0,0 @@ -```jsx -const isPressed = useSharedValue(false); -const offset = useSharedValue({ x: 0, y: 0 }); -const animatedStyles = useAnimatedStyle(() => { - return { - transform: [ - { translateX: offset.value.x }, - { translateY: offset.value.y }, - { scale: withSpring(isPressed.value ? 1.2 : 1) }, - ], - backgroundColor: isPressed.value ? 'yellow' : 'blue', - }; -}); -``` diff --git a/docs/versioned_docs/version-2.4.0/quickstart/step4.md b/docs/versioned_docs/version-2.4.0/quickstart/step4.md deleted file mode 100644 index 8e2112a3cd..0000000000 --- a/docs/versioned_docs/version-2.4.0/quickstart/step4.md +++ /dev/null @@ -1,9 +0,0 @@ -```jsx {4} -... -return ( - - - -); -... -``` diff --git a/docs/versioned_docs/version-2.4.0/quickstart/step5.md b/docs/versioned_docs/version-2.4.0/quickstart/step5.md deleted file mode 100644 index c7c2e07265..0000000000 --- a/docs/versioned_docs/version-2.4.0/quickstart/step5.md +++ /dev/null @@ -1,32 +0,0 @@ -```jsx -const start = useSharedValue({ x: 0, y: 0 }); -const gesture = Gesture.Pan() - .onBegin(() => { - isPressed.value = 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, - }; - }) - .onFinalize(() => { - isPressed.value = false; - }); -``` - -```jsx {3} -... -return ( - - - -); -... -``` diff --git a/docs/versioned_docs/version-2.4.0/troubleshooting.md b/docs/versioned_docs/version-2.4.0/troubleshooting.md deleted file mode 100644 index 3ce6df850c..0000000000 --- a/docs/versioned_docs/version-2.4.0/troubleshooting.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -id: troubleshooting -title: Troubleshooting ---- - -## Troubleshooting - -Thanks for giving this library a try! We are sorry that you might have encountered issues though. Here is how you can seek help: - -1. Search over the [issues on Github](https://github.com/software-mansion/react-native-gesture-handler/issues). There is a chance someone had this problem in the past and it has been resolved! -2. When sure your problem hasn't been reported or was reported but the proposed solution doesn't work for you please follow [our issue reporting guidelines](#reporting-issues). -3. You can try seeking help on [Expo Developers Discord](https://chat.expo.dev/) where we often hang out. -4. If you feel like reading the source code I highly recommend it, as this is by far the best resource and gives you the most up to date insights into how the library works and what might be causing the bug. -5. If you managed to find the solution consider [contributing](introduction.md#contributing) a fix or update our documentation to make this information easier to find for the others in the future. - -## Reporting issues - -This library is maintained by a very small team. -Please be mindful of that when reporting issue and when it happens that we can't get back to you as soon as you might expect. -We would love to fix all the problems as soon as possible, but often our time is constraint with other issues/features or projects. -To make it easier for us to understand your issue and to be able to approach it sooner you can help by: - -- Making sure the issue description is complete. Please include all the details about your environment (library version, RN version, device OS etc). -- It is the best to provide an example app that reproduces the issue you are having. Put it up on [gist](https://gist.github.com/), [snack](https://snack.expo.io) or create a repo on Github – it doesn't matter as long as we can easily pull it in, run and see the issue. -- Explain how you run your repro app and what steps to take to reproduce the issue. -- Isolate your issue from other dependencies you might be using and make the repro app as minimal as possible. -- If you have spent some time figuring out the root cause of the problem you can leave a note about your findings so far. -- **Do not comment on closed issues**. It is very unlikely that we are going to notice your comment in such a case. If the issue has been closed, but the proposed solution doesn't work for you, please open a new one providing all the information necessary and linking to the solution you have tried. - -## It's not a bug, it's a feature - -- Changing `enabled` prop during a gesture has no effect, only when a gesture starts (that is a finger touches the screen) the `enabled` prop is taken into consideration to decide whether to extract (or not) the gesture and provide it with stream of events to analyze. -- `Native` gesture may not conform to the standard state flow due to platform specific workarounds to incorporate native views into RNGH. -- Keep in mind that `Touchables` from RNGH are rendering two additional views that may need to be styled separately to achieve desired effect (`style` and `containerStyle` props). -- In order for the gesture composition to work, all composed gestures must be attached to the same `GestureHandlerRootView`. diff --git a/docs/versioned_docs/version-2.4.0/under-the-hood/how-does-it-work.md b/docs/versioned_docs/version-2.4.0/under-the-hood/how-does-it-work.md deleted file mode 100644 index aebed78316..0000000000 --- a/docs/versioned_docs/version-2.4.0/under-the-hood/how-does-it-work.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -id: how-does-it-work -title: How does it work? -sidebar_label: How does it work? ---- - -### Units - -All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". -These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://facebook.github.io/react-native/docs/flexbox.html)). -They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. - -## iOS - -All gestures are implemented using [UIGestureRecognizers](https://developer.apple.com/documentation/uikit/uigesturerecognizer?language=objc), some of them have been slightly modified to allow for more customization and to conform to the state flow of RNGH. When you assign a gesture configuration to the `GestureDetector`, it creates all the required recognizers and assigns them to the child view of the detector. From this point most of the heavy lifting is handled by the [UIKit](https://developer.apple.com/documentation/uikit?language=objc) (with our help to correctly implement interactions between gestures). - -## Android - -Unfortunately, Android doesn't provide an easy way of handling gestures hence most of them were implemented from scratch, including a system for managing how the gestures should interact with each other. Here's a quick overview of how it works: -When you wrap a component with `GestureHandlerRootView` it allows for the RNGH to intercept all touch events on that component and process them, deciding whether they should be handled by one of the gesture handlers or passed to the underlying view. Gesture handlers are created when you assign a gesture configuration to the `GestureDetector`, it initializes all of the necessary handlers natively. Every `GestureHandlerRootView` also has a specific handler to decide whether to pass the touch events or to consume them. It can never activate, only begin, end or be cancelled. When this handler is in the `UNDETERMINED` state it means that there is no touch in progress, however when the touch starts it transitions to the `BEGAN` state. As long as it stays in that state, no touch event is consumed, but as soon as it gets cancelled (meaning that some handler has activated) all incoming touch events get consumed, preventing underlying view from receiving them. - -When a pointer touches the screen the view tree is traversed in order to extract all handlers attached to the views below the finger (including the one attached to the `GestureHandlerRootView`) and all extracted handlers transition to the `BEGAN` state, signalling that the gesture may heve began. The touch events continue to be delivered to all extracted handlers until one of them recognizes the gesture and tries to activate. At this point the orchestrator checks whether this gesture should wait for any other of the extracted gestures to fail. If it does, it's put to the waiting list, if it doesn't, it gets activated and all other gestures (that are not simultaneous with it) get cancelled. When a gesture handlers transitions to a finished state (the gesture recognized by it stops, it fails or gets cancelled) the orchestrator check the waiting handlers. Every one of them that waited for the gesture that just failed tries to activate again (and again the orchestrator checks if it should wait for any of the extracted gestures...). diff --git a/docs/versioned_docs/version-2.4.0/under-the-hood/states-events.md b/docs/versioned_docs/version-2.4.0/under-the-hood/states-events.md deleted file mode 100644 index 600f16a5cc..0000000000 --- a/docs/versioned_docs/version-2.4.0/under-the-hood/states-events.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -id: states-events -title: Gesture states & events -sidebar_label: Gesture states & events ---- - -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 (longer arrows represent that there are possibly more touch events received before the state changes): - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`END`](#end) -> [`UNDETERMINED`](#undetermined) - -Another possible flow is when a handler receives touches that cause a recognition failure: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`FAILED`](#failed) -> [`UNDETERMINED`](#undetermined) - -At last, when a handler does properly recognize the gesture but then is interrupted by the touch system the gesture recognition is canceled and the flow looks as follows: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`CANCELLED`](#cancelled) -> [`UNDETERMINED`](#undetermined) - -## 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. - -### `onPointerChange` - -Is called before `onPointerDown`, `onPointerMove`, `onPointerUp` and `onPointerCancelled` with the same event, which may be useful in case you share logic between them. It may carry information about more than one pointer because the events are batched. diff --git a/docs/versioned_docs/version-2.6.0/api/components/buttons.mdx b/docs/versioned_docs/version-2.6.0/api/components/buttons.mdx deleted file mode 100644 index b69da43cc0..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/components/buttons.mdx +++ /dev/null @@ -1,178 +0,0 @@ ---- -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` -- `RectButton` -- `BorderlessButton` - -On top of that all the buttons are wrapped with `NativeViewGestureHandler` and therefore allow for all the [common gesture handler properties](#common-gesturehandler-properties) and `NativeViewGestureHandler`'s [extra properties](#nativeviewgesturehandler-extra-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`](#basebutton-component), 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`](#basebutton-component), 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/docs/versioned_docs/version-2.6.0/api/components/drawer-layout.mdx b/docs/versioned_docs/version-2.6.0/api/components/drawer-layout.mdx deleted file mode 100644 index 04abc42c72..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/components/drawer-layout.mdx +++ /dev/null @@ -1,147 +0,0 @@ ---- -id: drawer-layout -title: Drawer Layout -sidebar_label: DrawerLayout ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import GifGallery from '@site/components/GifGallery'; - -This is a cross-platform replacement for React Native's [DrawerLayoutAndroid](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) component. It provides a compatible API but allows for the component to be used on both Android and iOS. Please refer to [React Native docs](http://facebook.github.io/react-native/docs/drawerlayoutandroid.html) for the detailed usage for standard parameters. - -## Usage: - -`DrawerLayout` component isn't exported by default from the `react-native-gesture-handler` package. To use it, import it in the following way: - -```js -import DrawerLayout from 'react-native-gesture-handler/DrawerLayout'; -``` - -## Properties: - -On top of the standard list of parameters DrawerLayout has an additional set of attributes to customize its behavior. Please refer to the list below: - -### `drawerType` - -possible values are: `front`, `back` or `slide` (default is `front`). It specifies the way the drawer will be displayed. When set to `front` the drawer will slide in and out along with the gesture and will display on top of the content view. When `back` is used the drawer displays behind the content view and can be revealed with gesture of pulling the content view to the side. Finally `slide` option makes the drawer appear like it is attached to the side of the content view; when you pull both content view and drawer will follow the gesture. - -Type `slide`: - - - - - -Type `front`: - - - - - -Type `back`: - - - - - -### `edgeWidth` - -number, allows for defining how far from the edge of the content view the gesture should activate. - -### `hideStatusBar` - -boolean, when set to `true` Drawer component will use [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html) API to hide the OS status bar whenever the drawer is pulled or when its in an "open" state. - -### `statusBarAnimation` - -possible values are: `slide`, `none` or `fade` (defaults to `slide`). Can be used when `hideStatusBar` is set to `true` and will select the animation used for hiding/showing the status bar. See [StatusBar](http://facebook.github.io/react-native/docs/statusbar.html#statusbaranimation) documentation for more details. - -### `overlayColor` - -color (default to `"black"`) of a semi-transparent overlay to be displayed on top of the content view when drawer gets open. A solid color should be used as the opacity is added by the Drawer itself and the opacity of the overlay is animated (from 0% to 70%). - -### `renderNavigationView` - -function. This attribute is present in the standard implementation already and is one of the required params. Gesture handler version of DrawerLayout make it possible for the function passed as `renderNavigationView` to take an Animated value as a parameter that indicates the progress of drawer opening/closing animation (progress value is 0 when closed and 1 when opened). This can be used by the drawer component to animated its children while the drawer is opening or closing. - -### `onDrawerClose` - -function. This function is called when the drawer is closed. - -### `onDrawerOpen` - -function. This function is called when the drawer is opened. - -### `onDrawerSlide` - -function. This function is called as a drawer sliding open from touch events. The progress of the drawer opening/closing is passed back as 0 when closed and 1 when opened. - -### `onDrawerStateChanged` - -function. This function is called when the status of the drawer changes. Possible values that can be passed back are: 'Idle', 'Dragging', and 'Settling'. - -### `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` - -component or function. Children is a component which is rendered by default and is wrapped by drawer. However, it could be also a render function which takes an Animated value as a parameter that indicates the progress of drawer opening/closing animation (progress value is 0 when closed and 1 when opened) is the same way like `renderNavigationView` prop. - -## Methods - -### `openDrawer(options)` - -`openDrawer` can take an optional `options` parameter which is an object, enabling further customization of the open animation. - -`options` has two optional properties: - -`velocity`: number, the initial velocity of the object attached to the spring. Default 0 (object is at rest). -`speed`: number, controls speed of the animation. Default 12. - -### `closeDrawer(options)` - -`closeDrawer` can take an optional `options` parameter which is an object, enabling further customization of the close animation. - -`options` has two optional properties: - -`velocity`: number, the initial velocity of the object attached to the spring. Default 0 (object is at rest). -`speed`: number, controls speed of the animation. Default 12. - -## Example: - -See the [drawer example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/horizontalDrawer/index.tsx) from GestureHandler Example App or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -class Drawerable extends Component { - handleDrawerSlide = (status) => { - // outputs a value between 0 and 1 - console.log(status); - }; - - renderDrawer = () => { - return ( - - I am in the drawer! - - ); - }; - - render() { - return ( - - - - Hello, it's me - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.6.0/api/components/swipeable.md b/docs/versioned_docs/version-2.6.0/api/components/swipeable.md deleted file mode 100644 index 18fb7dfe78..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/components/swipeable.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -id: swipeable -title: Swipeable -sidebar_label: Swipeable ---- - -import useBaseUrl from '@docusaurus/useBaseUrl'; -import GifGallery from '@site/components/GifGallery' - - - - - -This component 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: - -Similarly to the `DrawerLayout`, `Swipeable` component isn't exported by default from the `react-native-gesture-handler` package. To use it, import it in the following way: - -```js -import Swipeable from 'react-native-gesture-handler/Swipeable'; -``` - -## 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. - -### `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 method 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 method 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. - -### `onSwipeableLeftOpen` - -:::caution -This callback is deprecated and will be removed in the next version. Please use `onSwipeableOpen(direction)` -::: - -method that is called when left action panel gets open. - -### `onSwipeableRightOpen` - -:::caution -This callback is deprecated and will be removed in the next version. Please use `onSwipeableOpen(direction)` -::: - -method that is called when right action panel gets open. - -### `onSwipeableOpen` - -method that is called when action panel gets open (either right or left). Takes swipe direction as -an argument. - -### `onSwipeableClose` - -method that is called when action panel is closed. Takes swipe direction as -an argument. - -### `onSwipeableLeftWillOpen` - -:::caution -This callback is deprecated and will be removed in the next version. Please use `onSwipeableWillOpen(direction)` -::: - -method that is called when left action panel starts animating on open. - -### `onSwipeableRightWillOpen` - -:::caution -This callback is deprecated and will be removed in the next version. Please use `onSwipeableWillOpen(direction)` -::: - -method that is called when right action panel starts animating on open. - -### `onSwipeableWillOpen` - -method that is called when action panel starts animating on open (either right or left). Takes swipe direction as -an argument. - -### `onSwipeableWillClose` - -method that is called when action panel starts animating on close. Takes swipe direction as -an argument. - -### `renderLeftActions` - -method that is expected to return an action panel that is going to be revealed from the left side when user swipes right. -This map describes the values to use as inputRange for extra interpolation: -AnimatedValue: [startValue, endValue] - -progressAnimatedValue: [0, 1] -dragAnimatedValue: [0, +] - -To support `rtl` flexbox layouts use `flexDirection` styling. - -### `renderRightActions` - -method that is expected to return an action panel that is going to be revealed from the right side when user swipes left. -This map describes the values to use as inputRange for extra interpolation: -AnimatedValue: [startValue, endValue] - -progressAnimatedValue: [0, 1] -dragAnimatedValue: [0, -] - -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`. - -### `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. - -## Methods - -Using reference to `Swipeable` it's possible to trigger some actions on it - -### `close` - -method that closes component. - -### `openLeft` - -method that opens component on left side. - -### `openRight` - -method that opens component on right side. - -### Example: - -See the [swipeable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/showcase/swipeable/index.tsx) from GestureHandler Example App or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -import React, { Component } from 'react'; -import { Animated, StyleSheet, View } from 'react-native'; -import { RectButton } from 'react-native-gesture-handler'; -import Swipeable from 'react-native-gesture-handler/Swipeable'; - -class AppleStyleSwipeableRow extends Component { - renderLeftActions = (progress, dragX) => { - const trans = dragX.interpolate({ - inputRange: [0, 50, 100, 101], - outputRange: [-20, 0, 0, 1], - }); - return ( - - - Archive - - - ); - }; - render() { - return ( - - "hello" - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.6.0/api/components/touchables.md b/docs/versioned_docs/version-2.6.0/api/components/touchables.md deleted file mode 100644 index 4b45292f72..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/components/touchables.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -id: touchables -title: Touchables -sidebar_label: Touchables ---- - -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://facebook.github.io/react-native/docs/touchablenativefeedback) -- [Touchable Highlight](https://facebook.github.io/react-native/docs/touchablehighlight) -- [Touchable Opacity](https://facebook.github.io/react-native/docs/touchableopacity) -- [Touchable Without Feedback](https://facebook.github.io/react-native/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/example/src/release_tests/touchables/index.tsx) diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/base-continous-gesture-callbacks.md b/docs/versioned_docs/version-2.6.0/api/gestures/base-continous-gesture-callbacks.md deleted file mode 100644 index 5504b2db8d..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/base-continous-gesture-callbacks.md +++ /dev/null @@ -1,9 +0,0 @@ -### Callbacks common to all continous gestures: - -### `onUpdate(callback)` - -Set the callback that is being called every time the gesture receives an update while it's active. - -### `onChange(callback)` - -Set the callback that is being called every time the gesture receives an update while it's active. This callback will receive information about change in value in relation to the last received event. diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/base-continous-gesture-config.md b/docs/versioned_docs/version-2.6.0/api/gestures/base-continous-gesture-config.md deleted file mode 100644 index a19473784e..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/base-continous-gesture-config.md +++ /dev/null @@ -1,5 +0,0 @@ -### Properties common to all continous gestures: - -### `manualActivation(value: boolead)` - -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](./state-manager.md). diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/base-gesture-callbacks.md b/docs/versioned_docs/version-2.6.0/api/gestures/base-gesture-callbacks.md deleted file mode 100644 index dff985b307..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/base-gesture-callbacks.md +++ /dev/null @@ -1,33 +0,0 @@ -### Callbacks common to all gestures: - -### `onBegin(callback)` - -Set the callback that is being called when given gesture handler starts receiving touches. At the moment of this callback the handler is not yet in an active state and we don't know yet if it will recognize the gesture at all. - -### `onStart(callback)` - -Set the callback that is being called when the gesture is recognized by the handler and it transitions to the active state. - -### `onEnd(callback)` - -Set the callback that is being called when the gesture that was recognized by the handler finishes. It will be called only if the handler was previously in the active state. - -### `onFinalize(callback)` - -Set the callback that is being called when the handler finalizes handling gesture - the gesture was recognized and has finished or it failed to recognize. - -### `onTouchesDown(callback)` - -Set the `onTouchesDown` callback which is called every time a finger is placed on the screen. - -### `onTouchesMove(callback)` - -Set the `onTouchesMove` callback which is called every time a finger is moved on the screen. - -### `onTouchesUp(callback)` - -Set the `onTouchesUp` callback which is called every time a finger is lifted from the screen. - -### `onTouchesCancelled(callback)` - -Set the `onTouchesCancelled` callback which is called every time a finger stops being tracked, for example when the gesture finishes. diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/base-gesture-config.md b/docs/versioned_docs/version-2.6.0/api/gestures/base-gesture-config.md deleted file mode 100644 index b096f17bb7..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/base-gesture-config.md +++ /dev/null @@ -1,59 +0,0 @@ -### 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`](../../under-the-hood/states-events.md#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`](../../under-the-hood/states-events.md#failed) or [`CANCELLED`](../../under-the-hood/states-events.md#cancelled) (depending on its current state). -Default value is `true`. - -### `shouldCancelWhenOutside(value: boolean)` - -When `true` the handler will [cancel](../../under-the-hood/states-events.md#cancelled) or [fail](../../under-the-hood/states-events.md#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`](./long-press-gesture.md) and [`TapGesture`](./tap-gesture.md) which default to `true`. - -### `hitSlop(settings)` - -This parameter enables control over what part of the connected view area can be used to [begin](../../under-the-hood/states-events.md#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://facebook.github.io/react-native/docs/view.html#props) 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`](../../under-the-hood/states-events.md#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](../../gesture-composition). [`GestureDetector`](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. - -**IMPORTANT:** Note that this method only marks the relation between gestures, without [composing them](../../gesture-composition).[`GestureDetector`](gesture-detector) will not recognize the `otherGestures` and it needs to be added to another detector in order to be recognized. diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/base-gesture-event-data.md b/docs/versioned_docs/version-2.6.0/api/gestures/base-gesture-event-data.md deleted file mode 100644 index 4d9056b1e5..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/base-gesture-event-data.md +++ /dev/null @@ -1,9 +0,0 @@ -### Event attributes common to all gestures: - -### `state` - -Current [state](.../../under-the-hood/states-events.md) 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. diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/composed-gestures.md b/docs/versioned_docs/version-2.6.0/api/gestures/composed-gestures.md deleted file mode 100644 index 84e2e451bd..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/composed-gestures.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -id: composed-gestures -title: Composed gestures -sidebar_label: Composed gestures ---- - -Composed gestures (`Race`, `Simultaneous`, `Exclusive`) provide a simple way of building relations between gestures. diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/fling-gesture.md b/docs/versioned_docs/version-2.6.0/api/gestures/fling-gesture.md deleted file mode 100644 index 09c2846276..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/fling-gesture.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -id: fling-gesture -title: Fling gesture -sidebar_label: Fling gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; - -A discrete gesture that activates when the movement is sufficiently long and fast. -Gesture gets [ACTIVE](../../under-the-hood/states-events.md#active) when movement is sufficiently long and it does not take too much time. -When gesture gets activated it will turn into [END](../../under-the-hood/states-events.md#end) state when finger is released. -The gesture will fail to recognize if the finger is lifted before being activated. - -## Config - -### Properties specific to `FlingGesture`: - -### `direction(value: Directions)` - -Expressed allowed direction of movement. Expected values are exported as constants in the `Directions` object. It's possible to pass one or many directions in one parameter: - -```js -fling.direction(Directions.RIGHT | Directions.LEFT); -``` - -or - -```js -fling.direction(Directions.DOWN); -``` - -### `numberOfPointers(value: number)` - -Determine exact number of points required to handle the fling gesture. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `FlingGesture`: - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - - - -## Example - -```jsx -const position = useSharedValue(0); - -const flingGesture = Gesture.Fling() - .direction(Directions.RIGHT) - .onStart((e) => { - position.value = withTiming(position.value + 10, { duration: 100 }); - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ translateX: position.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/force-touch-gesture.md b/docs/versioned_docs/version-2.6.0/api/gestures/force-touch-gesture.md deleted file mode 100644 index 8280f944b1..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/force-touch-gesture.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -id: force-touch-gesture -title: Force touch gesture (iOS only) -sidebar_label: Force touch gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-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](../../under-the-hood/states-events.md#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. - -There's no implementation provided on Android and it simply renders children without any wrappers. -Since this behaviour is only provided on some iOS devices, this gesture should not be used for defining any crucial behaviors. Use it only as an additional improvement and make all features to be accessed without this gesture as well. - -## Config - -### Properties specific to `ForceTouchGesture`: - -### `minForce(value: number)` - -A minimal pressure that is required before gesture can [activate](../../under-the-hood/states-events.md#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](../../under-the-hood/states-events.md#failed). Should be a value from range `[0.0, 1.0]`. - -### `feedbackOnActivation(value: boolean)` - -Value defining if haptic feedback has to be performed on activation. - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `ForceTouchGesture`: - -### `force` - -The pressure of a touch. - - diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/gesture-detector-functional1.md b/docs/versioned_docs/version-2.6.0/api/gestures/gesture-detector-functional1.md deleted file mode 100644 index 2397af9dfa..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/gesture-detector-functional1.md +++ /dev/null @@ -1,19 +0,0 @@ -```jsx -export default function Example() { - const tap = Gesture.Tap().onStart(() => { - console.log('tap'); - }); - - return ( - - - - - - ); -} - -function FunctionalComponent(props) { - return {props.children}; -} -``` diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/gesture-detector.md b/docs/versioned_docs/version-2.6.0/api/gestures/gesture-detector.md deleted file mode 100644 index fdb33ee40d..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/gesture-detector.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -id: gesture-detector -title: GestureDetector -sidebar_label: Gesture detector ---- - -import FunctionalComponents from './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.x/). - -:::caution -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. -::: - -## 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 synchrously. - -Starting with Reanimated-2.3.0-beta.4 Gesture Handler will provide a [StateManager](./state-manager.md) in the [touch events](./touch-events.md) 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"`. Defaults to `"none"`. **Available since version 2.8.0** diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/gesture.md b/docs/versioned_docs/version-2.6.0/api/gestures/gesture.md deleted file mode 100644 index b8131ffc58..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/gesture.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -id: gesture -title: Gesture -sidebar_label: Gesture ---- - -`Gesture` is the object that allows you to create and compose gestures. - -:::tip -Consider wrapping your gesture configurations with `useMemo`, as it will reduce the amount of work Gesture Handler has to do under the hood when updating gestures. For example: -```jsx -const gesture = useMemo( - () => - Gesture.Tap().onStart(() => { - console.log('Number of taps:', tapNumber + 1); - setTapNumber((value) => value + 1); - }), - [tapNumber, setTapNumber] -); -``` -::: - -### Gesture.Tap() - -Creates a new instance of [`TapGesture`](./tap-gesture.md) with its default config and no callbacks. - -### Gesture.Pan() - -Creates a new instance of [`PanGesture`](./pan-gesture.md) with its default config and no callbacks. - -### Gesture.LongPress() - -Creates a new instance of [`LongPressGesture`](./long-press-gesture.md) with its default config and no callbacks. - -### Gesture.Fling() - -Creates a new instance of [`FlingGesture`](./fling-gesture.md) with its default config and no callbacks. - -### Gesture.Pinch() - -Creates a new instance of [`PinchGesture`](./pinch-gesture.md) with its default config and no callbacks. - -### Gesture.Rotation() - -Creates a new instance of [`RotationGesture`](./rotation-gesture.md) with its default config and no callbacks. - -### Gesture.ForceTouch() - -Creates a new instance of [`ForceTouchGesture`](./force-touch-gesture.md) with its default config and no callbacks. - -### Gesture.Manual() - -Creates a new instance of [`ManualGesture`](./manual-gesture.md) with its default config and no callbacks. - -### Gesture.Native() - -Creates a new instance of [`NativeGesture`](./native-gesture.md) with its default config and no callbacks. - -### Gesture.Race(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. Only one of those can become active and there are no restrictions to the activation of the gesture. The first one to activate will cancel all the others. - -### Gesture.Simultaneous(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. All of them can become active without cancelling the others. - -### Gesture.Exclusive(gesture1, gesture2, gesture3, ...): ComposedGesture - -Creates a gesture composed of those provided as arguments. Only one of them can become active, but the first one has a higher priority than the second one, the second one has a higher priority than the third one, and so on. When all gestures are in the `BEGAN` state and the activation criteria for the second one is met, instead of activating it will wait until the first one fails (and only then it will activate) or until the first one activates (and then the second one will get cancelled). It is useful when you want to compose gestures with similar activation criteria (e.g. single and double tap at the same component, without Exclusive the single tap would activate every time user taps thus cancelling the double tap). diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/long-press-gesture.md b/docs/versioned_docs/version-2.6.0/api/gestures/long-press-gesture.md deleted file mode 100644 index 9f174d58e7..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/long-press-gesture.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -id: long-press-gesture -title: Long press gesture -sidebar_label: Long press gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './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](../../under-the-hood/states-events.md#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](#mindurationms) or if the finger is moved further than the [allowable distance](#maxdist). - -## Config - -### Properties specific to `LongPressGesture`: - -### `minDuration(value: number)` - -Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. - -### `maxDistance(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. The default value is 10. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `LongPressGesture`: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `duration` - -Duration of the long press (time since the start of the gesture), expressed in milliseconds. - - - -## Example - -```jsx -const longPressGesture = Gesture.LongPress().onEnd((e, success) => { - if (success) { - Alert.alert(`Long pressed for ${e.duration} ms!`); - } -}); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/manual-gesture.md b/docs/versioned_docs/version-2.6.0/api/gestures/manual-gesture.md deleted file mode 100644 index a92c6986ef..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/manual-gesture.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -id: manual-gesture -title: Manual gesture -sidebar_label: Manual gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A plain gesture that has no specific activation criteria nor event data set. Its state has to be controlled manually using a [state manager](./state-manager.md). It will not fail when all the pointers are lifted from the screen. - -## Config - - - -## Callbacks - - - - -## Event data - - diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/native-gesture.md b/docs/versioned_docs/version-2.6.0/api/gestures/native-gesture.md deleted file mode 100644 index 6fa7249eed..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/native-gesture.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -id: native-gesture -title: Native gesture -sidebar_label: Native gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A gesture that allows other touch handling components to participate in RNGH's gesture system. When used, the other component should be the direct child of a `GestureDetector`. - -## Config - -### Properties specific to `NativeGesture`: - -### `shouldActivateOnStart(value: boolean)` (**Android only**) - -When `true`, underlying handler will activate unconditionally when in `BEGAN` or `UNDETERMINED` state. - -### `disallowInterruption(value: boolean)` - -When `true`, cancels all other gesture handlers when this `NativeViewGestureHandler` receives an `ACTIVE` state event. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `NativeGesture`: - -### `pointerInside` - -True if gesture was performed inside of containing view, false otherwise. - - diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/pan-gesture.md b/docs/versioned_docs/version-2.6.0/api/gestures/pan-gesture.md deleted file mode 100644 index 6423e44411..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/pan-gesture.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -id: pan-gesture -title: Pan gesture -sidebar_label: Pan gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that can recognize a panning (dragging) gesture and track its movement. - -The gesture [activates](../../under-the-hood/states-events.md#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. - -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. - -## 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. - -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 [`avgTouches`](#avgtouches-android-only) flag. - -Note that on both Android and iOS when the additional finger is placed on the screen that translation prop is not affected even though the position of the pointer being tracked might have changed. -Therefore it is safe to rely on translation most of the time as it only reflects the movement that happens regardless of how many fingers are placed on the screen and if that number changes over time. -If you wish to track the "center of mass" virtual pointer and account for its changes when the number of finger changes you can use relative or absolute position provided in the event ([`x`](#x) and [`y`](#y) or [`absoluteX`](#absolutex) and [`absoluteY`](#absolutey)). - -## Config - -### Properties specific to `PanGesture`: - -### `minDistance(value: number)` - -Minimum distance the finger (or multiple finger) need to travel before the gesture [activates](../../under-the-hood/states-events.md#active). Expressed in points. - -### `minPointers(value: number)` - -A number of fingers that is required to be placed before gesture can [activate](../../under-the-hood/states-events.md#active). Should be a higher or equal to 0 integer. - -### `maxPointers(value: number)` - -When the given number of fingers is placed on the screen and gesture hasn't yet [activated](../../under-the-hood/states-events.md#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. - -### `activateAfterLongPress(duration: number)` - -Duration in milliseconds of the `LongPress` gesture before `Pan` is allowed to [activate](../../under-the-hood/states-events.md#active). If the finger is moved during that period, the gesture will [fail](../../under-the-hood/states-events.md#failed). Should be a higher or equal to 0 integer. Default value is 0, meaning no `LongPress` is required to [activate](../../under-the-hood/states-events.md#active) the `Pan`. - -### `activeOffsetX(value: number | number[])` - -Range along X axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `activeOffsetY(value: number | number[])` - -Range along Y axis (in points) where fingers travels without activation of gesture. Moving outside of this range implies activation of gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `failOffsetY(value: number | number[])` - -When the finger moves outside this range (in points) along Y axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `failOffsetX(value: number | number[])` - -When the finger moves outside this range (in points) along X axis and gesture hasn't yet activated it will fail recognizing the gesture. Range can be given as an array or a single number. -If range is set as an array, first value must be lower or equal to 0, a the second one higher or equal to 0. -If only one number `p` is given a range of `(-inf, p)` will be used if `p` is higher or equal to 0 and `(-p, inf)` otherwise. - -### `averageTouches(value: boolean)` (Android only) - -### `enableTrackpadTwoFingerGesture(value: boolean)` (iOS only) - -Enables two-finger gestures on supported devices, for example iPads with trackpads. If not enabled the gesture will require click + drag, with enableTrackpadTwoFingerGesture swiping with two fingers will also trigger the gesture. - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `PanGesture`: - -### `translationX` - -Translation of the pan gesture along X axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `translationY` - -Translation of the pan gesture along Y axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `velocityX` - -Velocity of the pan gesture along the X axis in the current moment. The value is expressed in point units per second. - -### `velocityY` - -Velocity of the pan gesture along the Y axis in the current moment. The value is expressed in point units per second. - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - - - -## Example - -```jsx -const END_POSITION = 200; -const onLeft = useSharedValue(true); -const position = useSharedValue(0); - -const panGesture = Gesture.Pan() - .onUpdate((e) => { - if (onLeft.value) { - position.value = e.translationX; - } else { - position.value = END_POSITION + e.translationX; - } - }) - .onEnd((e) => { - if (position.value > END_POSITION / 2) { - position.value = withTiming(END_POSITION, { duration: 100 }); - onLeft.value = false; - } else { - position.value = withTiming(0, { duration: 100 }); - onLeft.value = true; - } - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ translateX: position.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/pinch-gesture.md b/docs/versioned_docs/version-2.6.0/api/gestures/pinch-gesture.md deleted file mode 100644 index 5b56e7d043..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/pinch-gesture.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -id: pinch-gesture -title: Pinch gesture -sidebar_label: Pinch gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. -The gesture [activates](../../under-the-hood/states-events.md#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. - -## Config - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `PinchGesture`: - -### `scale` - -The scale factor relative to the points of the two touches in screen coordinates. - -### `velocity` - -Velocity of the pan gesture the current moment. The value is expressed in point units per second. - -### `focalX` - -Position expressed in points along X axis of center anchor point of gesture - -### `focalY` - -Position expressed in points along Y axis of center anchor point of gesture - - - -## Example - -```jsx -const scale = useSharedValue(1); -const savedScale = useSharedValue(1); - -const pinchGesture = Gesture.Pinch() - .onUpdate((e) => { - scale.value = savedScale.value * e.scale; - }) - .onEnd(() => { - savedScale.value = scale.value; - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ scale: scale.value }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/rotation-gesture.md b/docs/versioned_docs/version-2.6.0/api/gestures/rotation-gesture.md deleted file mode 100644 index 6550e0ea98..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/rotation-gesture.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -id: rotation-gesture -title: Rotation gesture -sidebar_label: Rotation gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseContinousEventConfig from './base-continous-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; -import BaseContinousEventCallbacks from './base-continous-gesture-callbacks.md'; - -A continuous gesture that can recognize a rotation gesture and track its movement. - -The gesture [activates](../../under-the-hood/states-events.md#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. - -## Config - - - - -## Callbacks - - - - -## Event data - -### Event attributes specific to `RotationGesture`: - -### `rotation` - -Amount rotated, expressed in radians, from the gesture's focal point (anchor). - -### `velocity` - -Instantaneous velocity, expressed in point units per second, of the gesture. - -### `anchorX` - -X coordinate, expressed in points, of the gesture's central focal point (anchor). - -### `anchorY` - -Y coordinate, expressed in points, of the gesture's central focal point (anchor). - - - -## Example - -```jsx -const rotation = useSharedValue(1); -const savedRotation = useSharedValue(1); - -const rotationGesture = Gesture.Rotation() - .onUpdate((e) => { - rotation.value = savedRotation.value + e.rotation; - }) - .onEnd(() => { - savedRotation.value = rotation.value; - }); - -const animatedStyle = useAnimatedStyle(() => ({ - transform: [{ rotateZ: `${(rotation.value / Math.PI) * 180}deg` }], -})); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/state-manager.md b/docs/versioned_docs/version-2.6.0/api/gestures/state-manager.md deleted file mode 100644 index cb50e8212b..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/state-manager.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: state-manager -title: Gesture state manager -sidebar_label: Gesture state manager ---- - -`GestureStateManager` allows to manually control the state of the gestures. Please note that `react-native-reanimated` is required to use it, since it allows for synchronously executing methods in worklets. - -## Methods - -### `begin()` - -Transition the gesture to the [`BEGAN`](../../under-the-hood/states-events.md#began) state. This method will have no effect if the gesture has already activated or finished. - -### `activate()` - -Transition the gesture to the [`ACTIVE`](../../under-the-hood/states-events.md#active) state. This method will have no effect if the handler is already active, or has finished. -If the gesture is [`exclusive`](../../gesture-composition) with another one, the activation will be delayed until the gesture with higher priority fails. - -### `end()` - -Transition the gesture to the [`END`](../../under-the-hood/states-events.md#end) state. This method will have no effect if the handler has already finished. - -### `fail()` - -Transition the gesture to the [`FAILED`](../../under-the-hood/states-events.md#failed) state. This method will have no effect if the handler has already finished. diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/tap-gesture.md b/docs/versioned_docs/version-2.6.0/api/gestures/tap-gesture.md deleted file mode 100644 index 6c6c0a0872..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/tap-gesture.md +++ /dev/null @@ -1,100 +0,0 @@ ---- -id: tap-gesture -title: Tap gesture -sidebar_label: Tap gesture ---- - -import BaseEventData from './base-gesture-event-data.md'; -import BaseEventConfig from './base-gesture-config.md'; -import BaseEventCallbacks from './base-gesture-callbacks.md'; - -A discrete gesture that recognizes one or many taps. - -Tap gestures detect one or more fingers briefly touching the screen. -The fingers involved in these gestures must not move significantly from their initial touch positions. -The required number of taps and allowed distance from initial position may be configured. -For example, you might configure tap gesture recognizers to detect single taps, double taps, or triple taps. - -In order for a gesture to [activate](../../under-the-hood/states-events.md#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDuration, and maxDelayMs (explained below) must be met. Immediately after the gesture [activates](../../under-the-hood/states-events.md#active), it will [end](../../under-the-hood/states-events.md#end). - -## Config - -### Properties specific to `TapGesture`: - -### `minPointers(value: number)` - -Minimum number of pointers (fingers) required to be placed before the gesture [activates](../../under-the-hood/states-events.md#active). Should be a positive integer. The default value is 1. - -### `maxDuration(value: number)` - -Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch. The default value is 500. - -### `maxDelay(value: number)` - -Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required. The default value is 500. - -### `numberOfTaps(value: number)` - -Number of tap gestures required to [activate](../../under-the-hood/states-events.md#active) the gesture. The default value is 1. - -### `maxDeltaX(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the X axis during a tap gesture. If the finger travels further than the defined distance along the X axis and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - -### `maxDeltaY(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the Y axis during a tap gesture. If the finger travels further than the defined distance along the Y axis and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - -### `maxDistance(value: number)` - -Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a tap gesture. If the finger travels further than the defined distance and the gesture hasn't yet [activated](../../under-the-hood/states-events.md#active), it will fail to recognize the gesture. - - - -## Callbacks - - - -## Event data - -### Event attributes specific to `TapGesture`: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the [`GestureDetector`](./gesture-detector.md). - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the [`GestureDetector`](./gesture-detector.md) can be transformed as an effect of the gesture. - - - -## Example - -```jsx -const singleTap = Gesture.Tap() - .maxDuration(250) - .onStart(() => { - Alert.alert('Single tap!'); - }); - -const doubleTap = Gesture.Tap() - .maxDuration(250) - .onStart(() => { - Alert.alert('Double tap!'); - }); - -return ( - - - -); -``` diff --git a/docs/versioned_docs/version-2.6.0/api/gestures/touch-events.md b/docs/versioned_docs/version-2.6.0/api/gestures/touch-events.md deleted file mode 100644 index 58103d7b25..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/gestures/touch-events.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -id: touch-events -title: Touch events -sidebar_label: Touch events ---- - -### Touch event attributes: - -### `eventType` - -Type of the current event - whether the finger was placed on the screen, moved, lifted or cancelled. - -### `changedTouches` - -An array of objects where every object represents a single touch. Contains information only about the touches that were affected by the event i.e. those that were placed down, moved, lifted or cancelled. - -### `allTouches` - -An array of objects where every object represents a single touch. Contains information about all active touches. - -### `numberOfTouches` - -Number representing the count of currently active touches. - -:::caution -Don't rely on the order of items in the `touches` as it may change during the gesture, instead use the `id` attribute to track individual touches across events. -::: - -### PointerData attributes: - -### `id` - -A number representing id of the touch. It may be used to track the touch between events as the id will not change while it is being tracked. - -### `x` - -X coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `y` - -Y coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](./gesture-detector.md). Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the touch relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the touch relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. diff --git a/docs/versioned_docs/version-2.6.0/api/test-api.md b/docs/versioned_docs/version-2.6.0/api/test-api.md deleted file mode 100644 index 2eacd0c711..0000000000 --- a/docs/versioned_docs/version-2.6.0/api/test-api.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -id: test-api -title: Testing ---- - -:::info -If you want to use `fireGestureHandler` and `getByGestureTestId`, you need to import them from `react-native-gesture-handler/jest-utils` package. -::: - -## fireGestureHandler(gestureOrHandler, eventList) - -Simulates one event stream (i.e. event sequence starting with `BEGIN` state and ending -with one of `END`/`FAIL`/`CANCEL` states), calling appropriate callbacks associated with given gesture handler. - -### Arguments - -#### `gestureOrHandler` - -Represents either: - -1. Gesture handler component found by Jest queries (e.g. `getByTestId`) -2. Gesture found by [`getByGestureTestId()`](#getbygestureidtestid) - -#### `eventList` - -Event data passed to appropriate callback. RNGH fills event list if required -data is missing using these rules: - -1. `oldState` is filled using state of the previous event. `BEGIN` events use - `UNDETERMINED` value as previous event. -2. Events after first `ACTIVE` state can omit `state` field. -3. Handler specific data is filled (e.g. `numberOfTouches`, `x` fields) with - defaults. -4. Missing `BEGIN` and `END` events are added with data copied from first and last - passed event, respectively. -5. If first event don't have `state` field, the `ACTIVE` state is assumed. - -Some examples: - -```jsx -const oldStateFilled = [ - { state: State.BEGAN }, - { state: State.ACTIVE }, - { state: State.END }, -]; // three events with specified state are fired. - -const implicitActiveState = [ - { state: State.BEGAN }, - { state: State.ACTIVE }, - { x: 5 }, - { state: State.END }, -]; // 4 events, including two ACTIVE events (second one has overriden additional data). - -const implicitBegin = [ - { x: 1, y: 11 }, - { x: 2, y: 12, state: State.FAILED }, -]; // 3 events, including implicit BEGAN, one ACTIVE, and one FAILED event with additional data. - -const implicitBeginAndEnd = [ - { x: 5, y: 15 }, - { x: 6, y: 16 }, - { x: 7, y: 17 }, -]; // 5 events, including 3 ACTIVE events and implicit BEGAN and END events. BEGAN uses first event's additional data, END uses last event's additional data. - -const allImplicits = []; // 3 events, one BEGIN, one ACTIVE, one END with defaults. -``` - -### Example - -Extracted from RNGH tests, check `Events.test.tsx` for full implementation. - -```tsx -it('sends events with additional data to handlers', () => { - const panHandlers = mockedEventHandlers(); - render(); - fireGestureHandler(getByGestureTestId('pan'), [ - { state: State.BEGAN, translationX: 0 }, - { state: State.ACTIVE, translationX: 10 }, - { translationX: 20 }, - { translationX: 20 }, - { state: State.END, translationX: 30 }, - ]); - - expect(panHandlers.active).toBeCalledTimes(3); - expect(panHandlers.active).toHaveBeenLastCalledWith( - expect.objectContaining({ translationX: 20 }) - ); -}); -``` - -## getByGestureTestId(testID) - -Returns opaque data type associated with gesture. Gesture is found via `testID` attribute in rendered -components (see [`withTestID` method](./gestures/base-gesture-config.md#withrefref)). - -### Arguments - -#### `testID` - -String identifying gesture. - -### Notes - -`testID` must be unique among components rendered in test. - -### Example - -See above example for `fireGestureHandler`. diff --git a/docs/versioned_docs/version-2.6.0/gesture-composition.md b/docs/versioned_docs/version-2.6.0/gesture-composition.md deleted file mode 100644 index e55e06fae6..0000000000 --- a/docs/versioned_docs/version-2.6.0/gesture-composition.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -id: gesture-composition -title: Composing gestures -sidebar_label: Composing gestures ---- - -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 -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 -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 -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 ( - - - -); -``` - -## Composition vs `simultaneousWithExternalGesture` and `requireExternalGestureToFail` - -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. If you want to make a relation between gestures that are attached to separate `GestureDetectors`, we have a separate mechanism for that: `simultaneousWithExternalGesture` and `requireExternalGestureToFail` methods that are available on every base gesture. They work exactly the same way as `simultaneousHandlers` and `waitFor` on gesture handlers, that is they just mark the relation between the gestures without joining them into single object. diff --git a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/common-gh.md b/docs/versioned_docs/version-2.6.0/gesture-handlers/api/common-gh.md deleted file mode 100644 index dc15e45607..0000000000 --- a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/common-gh.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -id: common-gh -title: Common handler properties -sidebar_label: Common handler properties ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -This page covers the common set of properties all gesture handler components expose. - -### Units - -All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". -These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://facebook.github.io/react-native/docs/flexbox.html)). -They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. - -## Properties - -This section describes properties that can be used with all gesture handler components: - -### `enabled` - -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`](../basics/state.md#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`](../basics/state.md#failed) or [`CANCELLED`](../basics/state.md#cancelled) (depending on its current state). -Default value is `true`. - -### `shouldCancelWhenOutside` - -Accepts a boolean value. -When `true` the handler will [cancel](../basics/state.md#cancelled) or [fail](../basics/state.md#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.md) and [`TapGestureHandler`](./tap-gh.md) 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`](../basics/state.md#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](../basics/state.md#active) even if one or more of the handlers provided by their refs are in an [`ACTIVE`](../basics/state.md#active) state. It will also prevent the provided handlers from [cancelling](../basics/state.md#cancelled) the current handler when they [activate](../basics/state.md#active). Read more in the [cross handler interaction](../basics/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](../basics/state.md#active) as long as the handlers provided by their refs are in the [`BEGAN`](../basics/state.md#began) state. Read more in the [cross handler interaction](../basics/interactions.md#awaiting-other-handlers) section. - -### `hitSlop` - -This parameter enables control over what part of the connected view area can be used to [begin](../basics/state.md#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://facebook.github.io/react-native/docs/view.html#props) property. - -### `userSelect` (**web only**) - -This parameter allows to specify which `userSelect` property should be applied to underlying view. Possible values are `"none" | "auto" | "text"`. Defaults to `"none"`. **Available since version 2.8.0** - -### `onGestureEvent` - -Takes a callback that is going to be triggered for each subsequent touch event while the handler is in an [ACTIVE](../basics/state.md#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.md#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://facebook.github.io/react-native/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](../basics/state.md) 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](../basics/state.md) of the handler right before the change. - -Instead of a callback [`Animated.event`](https://facebook.github.io/react-native/docs/animated.html#event) object can be used. Also Animated events with `useNativeDriver` flag enabled **are fully supported**. - -## Event data - -This section describes the attributes of event object being provided to [`onGestureEvent`](#ongestureevent) and [`onHandlerStateChange`](#onhandlerstatechange) callbacks: - -### `state` - -Current [state](../basics/state.md) of the handler. Expressed as one of the constants exported under `State` object by the library. Refer to the section about [handler state](../basics/state.md) to learn more about how to use it. - -### `numberOfPointers` - -Represents the number of pointers (fingers) currently placed on the screen. diff --git a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/create-native-wrapper.md b/docs/versioned_docs/version-2.6.0/gesture-handlers/api/create-native-wrapper.md deleted file mode 100644 index a33fd58d36..0000000000 --- a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/create-native-wrapper.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: create-native-wrapper -title: createNativeWrapper -sidebar_label: createNativeWrapper() ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -Creates provided component with NativeViewGestureHandler, allowing it to be part of RNGH's -gesture system. - -## Arguments - -### Component - -The component we want to wrap. - -### config - -Config is an object with properties that can be used on [`NativeViewGestureHandler`](./nativeview-gh.md) - -## Returns - -Wrapped component. diff --git a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/force-gh.md b/docs/versioned_docs/version-2.6.0/gesture-handlers/api/force-gh.md deleted file mode 100644 index ea3bb6835e..0000000000 --- a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/force-gh.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -id: force-gh -title: ForceTouchGestureHandler (iOS only) -sidebar_label: Force touch ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) 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](../basics/state.md#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. - -The handler is implemented using custom [UIGestureRecognizer](https://developer.apple.com/documentation/uikit/uigesturerecognizer) on iOS. There's no implementation provided on Android and it simply render children without any wrappers. -Since this behaviour is only provided on some iOS devices, this handler should not be used for defining any crucial behaviors. Use it only as an additional improvement and make all features to be accessed without this handler as well. - -# Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to `ForceTouchGestureHandler` component: - -### `minForce` - -A minimal pressure that is required before handler can [activate](../basics/state.md#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](../basics/state.md#failed). Should be a value from range `[0.0, 1.0]`. - -### `feedbackOnActivation` - -Boolean value defining if haptic feedback has to be performed on activation. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `ForceTouchGestureHandler`: - -### `force` - -The pressure of a touch. - -## Static method - -### `forceTouchAvailable` - -You may check if it's possible to use `ForceTouchGestureHandler` with `ForceTouchGestureHandler.forceTouchAvailable` - -## Example - -See the [force touch handler example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/forcetouch/index.tsx) from Gesture Handler Example App. - -```js - - - -``` diff --git a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/longpress-gh.md b/docs/versioned_docs/version-2.6.0/gesture-handlers/api/longpress-gh.md deleted file mode 100644 index 1402df76df..0000000000 --- a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/longpress-gh.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -id: longpress-gh -title: LongPressGestureHandler -sidebar_label: Long press ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) 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](../basics/state.md#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.java) on Android. - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to the `LongPressGestureHandler` component: - -### `minDurationMs` - -Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view. The default value is 500. - -### `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](../basics/state.md#active), it will fail to recognize the gesture. The default value is 10. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to the `LongPressGestureHandler` component: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `duration` - -Duration of the long press (time since the start of the event), expressed in milliseconds. - -## Example - -See the [multitap example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from GestureHandler Example App. - -```js -const LongPressButton = () => ( - { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert("I'm being pressed for so long"); - } - }} - minDurationMs={800}> - - -); -``` diff --git a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/nativeview-gh.md b/docs/versioned_docs/version-2.6.0/gesture-handlers/api/nativeview-gh.md deleted file mode 100644 index d515560d36..0000000000 --- a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/nativeview-gh.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: nativeview-gh -title: NativeViewGestureHandler -sidebar_label: NativeView ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A gesture handler that allows other touch handling components to participate in -RNGH's gesture system. - -Used by [`createNativeWrapper()`](./create-native-wrapper.md). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#properties). Below is a list of properties specific to `NativeViewGestureHandler` component: - -### `shouldActivateOnStart` (**Android only**) - -When `true`, underlying handler will activate unconditionally when in `BEGAN` or `UNDETERMINED` state. - -### `disallowInterruption` - -When `true`, cancels all other gesture handlers when this `NativeViewGestureHandler` receives an `ACTIVE` state event. diff --git a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/pan-gh.md b/docs/versioned_docs/version-2.6.0/gesture-handlers/api/pan-gh.md deleted file mode 100644 index 4b2daeaff0..0000000000 --- a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/pan-gh.md +++ /dev/null @@ -1,225 +0,0 @@ ---- -id: pan-gh -title: PanGestureHandler -sidebar_label: Pan ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A continuous gesture handler that can recognize a panning (dragging) gesture and track its movement. - -The handler [activates](../basics/state.md#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. - -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. - -The handler is implemented using [UIPanGestureRecognizer](https://developer.apple.com/documentation/uikit/uipangesturerecognizer) on iOS and [PanGestureHandler](https://github.com/software-mansion/react-native-gesture-handler/blob/main/android/lib/src/main/java/com/swmansion/gesturehandler/PanGestureHandler.java) on Android. - -## 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](../basics/state.md#active) or [fail](../basics/state.md#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. -Another example would be setting both [`maxDeltaX`](#maxdeltaX) and [`maxDeltaY`](#maxdeltay) to 20 and [`minDist`](#mindist) to 23. -In such a case, if we move a finger along the X-axis by 20 points and along the Y-axis by 0 points, the handler will fail even though the finger is still within the bounds of translation along Y-axis. - -## 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. - -The default behavior for native components like scroll view, pager views or drawers is different and hence gesture handler 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 [`avgTouches`](#avgtouches-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)). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#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](../basics/state.md#active). Expressed in points. - -### `minPointers` - -A number of fingers that is required to be placed before handler can [activate](../basics/state.md#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](../basics/state.md#active) it will fail recognizing the gesture. Should be a higher or equal to 0 integer. - -### `activeOffsetX` - -Range along X axis (in points) where fingers travels without activation of handler. Moving outside of this range implies activation of handler. 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` - -Range along Y axis (in points) where fingers travels without activation of handler. Moving outside of this range implies activation of handler. 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` - -When the finger moves outside this range (in points) along Y axis and handler 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` - -When the finger moves outside this range (in points) along X axis and handler 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. - -### `maxDeltaX` - -> 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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#active) for the movement in one particular direction use [`minOffsetY`](#minoffsety) instead. - -### `avgTouches` (Android only) - -### `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. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `PanGestureHandler`: - -### `translationX` - -Translation of the pan gesture along X axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `translationY` - -Translation of the pan gesture along Y axis accumulated over the time of the gesture. The value is expressed in the point units. - -### `velocityX` - -Velocity of the pan gesture along the X axis in the current moment. The value is expressed in point units per second. - -### `velocityY` - -Velocity of the pan gesture along the Y axis in the current moment. The value is expressed in point units per second. - -### `x` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `y` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. Expressed in point units. - -### `absoluteX` - -X coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`x`](#x) in cases when the original view can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. The value is expressed in point units. It is recommended to use it instead of [`y`](#y) in cases when the original view can be transformed as an effect of the gesture. - -## Example - -See the [draggable example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/draggable/index.tsx) from Gesture Handler Example App. - -```js -import React, { Component } from 'react'; -import { Animated, Dimensions } from 'react-native'; -import { - GestureHandlerRootView, - PanGestureHandler, -} from 'react-native-gesture-handler'; - -const { width } = Dimensions.get('screen'); -const circleRadius = 30; - -class Circle extends Component { - _touchX = new Animated.Value(width / 2 - circleRadius); - - _onPanGestureEvent = Animated.event([{ nativeEvent: { x: this._touchX } }], { - useNativeDriver: true, - }); - - render() { - return ( - - - - - - - - ); - } -} - -export default function App() { - return ; -} -``` diff --git a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/rotation-gh.md b/docs/versioned_docs/version-2.6.0/gesture-handlers/api/rotation-gh.md deleted file mode 100644 index 862e703afe..0000000000 --- a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/rotation-gh.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -id: rotation-gh -title: RotationGestureHandler -sidebar_label: Rotation ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A continuous gesture handler that can recognize a rotation gesture and track its movement. - -The handler [activates](../basics/state.md#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. - -The handler is implemented using [UIRotationGestureRecognizer](https://developer.apple.com/documentation/uikit/uirotationgesturerecognizer) on iOS and from scratch on Android. - -## Properties - -Properties provided to `RotationGestureHandler` do not extend [common set of properties from base handler class](./common-gh.md#properties). - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to `RotationGestureHandler`: - -### `rotation` - -Amount rotated, expressed in radians, from the gesture's focal point (anchor). - -### `velocity` - -Instantaneous velocity, expressed in point units per second, of the gesture. - -### `anchorX` - -X coordinate, expressed in points, of the gesture's central focal point (anchor). - -### `anchorY` - -Y coordinate, expressed in points, of the gesture's central focal point (anchor). - -## Example - -See the [scale and rotation example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from Gesture Handler Example App. - -```js -class RotableBox extends React.Component { - _rotate = new Animated.Value(0); - _rotateStr = this._rotate.interpolate({ - inputRange: [-100, 100], - outputRange: ['-100rad', '100rad'], - }); - _lastRotate = 0; - _onRotateGestureEvent = Animated.event( - [{ nativeEvent: { rotation: this._rotate } }], - { useNativeDriver: USE_NATIVE_DRIVER } - ); - _onRotateHandlerStateChange = (event) => { - if (event.nativeEvent.oldState === State.ACTIVE) { - this._lastRotate += event.nativeEvent.rotation; - this._rotate.setOffset(this._lastRotate); - this._rotate.setValue(0); - } - }; - render() { - return ( - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/tap-gh.md b/docs/versioned_docs/version-2.6.0/gesture-handlers/api/tap-gh.md deleted file mode 100644 index 74fa3ee114..0000000000 --- a/docs/versioned_docs/version-2.6.0/gesture-handlers/api/tap-gh.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -id: tap-gh -title: TapGestureHandler -sidebar_label: Tap ---- - -:::warning -Consider using the new [gestures API](../../api/gestures/gesture.md) instead. The old API is not actively supported and is not receiving the new features. Check out [RNGH 2.0 section in Introduction](../../introduction.md#rngh-20) for more information. -::: - -A discrete gesture handler 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 handler to [activate](../basics/state.md#active), specified gesture requirements such as minPointers, numberOfTaps, maxDist, maxDurationMs, and maxDelayMs (explained below) must be met. Immediately after the handler [activates](../basics/state.md#active), it will [END](../basics/state.md#end). - -## Properties - -See [set of properties inherited from base handler class](./common-gh.md#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](../basics/state.md#active). Should be a positive integer. The default value is 1. - -### `maxDurationMs` - -Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch. The default value is 500. - -### `maxDelayMs` - -Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required. The default value is 500. - -### `numberOfTaps` - -Number of tap gestures required to [activate](../basics/state.md#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](../basics/state.md#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](../basics/state.md#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](../basics/state.md#active), it will fail to recognize the gesture. - -## Event data - -See [set of event attributes from base handler class](./common-gh.md#event-data). Below is a list of gesture event attributes specific to the `TapGestureHandler` component: - -### `x` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `y` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the view attached to the handler. - -### `absoluteX` - -X coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteX` instead of [`x`](#x) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -### `absoluteY` - -Y coordinate, expressed in points, of the current position of the pointer (finger or a leading pointer when there are multiple fingers placed) relative to the window. It is recommended to use `absoluteY` instead of [`y`](#y) in cases when the view attached to the handler can be transformed as an effect of the gesture. - -## Example - -See the [multitap example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from GestureHandler Example App. - -```js -export class PressBox extends Component { - doubleTapRef = React.createRef(); - render() { - return ( - - - - - - ); - } -} -``` diff --git a/docs/versioned_docs/version-2.6.0/gesture-handlers/basics/about-handlers.md b/docs/versioned_docs/version-2.6.0/gesture-handlers/basics/about-handlers.md deleted file mode 100644 index 4c2062a24f..0000000000 --- a/docs/versioned_docs/version-2.6.0/gesture-handlers/basics/about-handlers.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -id: about-handlers -title: About Gesture Handlers -sidebar_label: About Gesture Handlers ---- - -Gesture handlers are the core building blocks of this library. -We use this term to describe elements of the native touch system that the library allows us to instantiate and control from Javascript using [React's Component](https://reactjs.org/docs/react-component.html) interface. - -Each handler type is capable of recognizing one type of gesture (pan, pinch, etc.) and provides gesture-specific information via events (translation, scale, 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](./state.md). -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](./state.md#active), it cancels all the other gestures (read more about how to influence this process in ["Cross handler interactions"](./interactions.md) 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. - -### Available gesture handlers - -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`](../api/pan-gh.md) -- [`TapGestureHandler`](../api/tap-gh.md) -- [`LongPressGestureHandler`](../api/longpress-gh.md) -- [`RotationGestureHandler`](../api/rotation-gh.md) -- [`FlingGestureHandler`](../api/fling-gh.md) -- [`PinchGestureHandler`](../api/pinch-gh.md) -- [`ForceTouchGestureHandler`](../api/force-gh.md) - -### Discrete vs continuous - -We distinguish between two types of gestures: discrete and continuous. - -Continuous gesture handlers can be [active](./state.md#active) for a long period of time and will generate a stream of [gesture events](../api/common-gh.md#ongestureevent) until the gesture is [over](./state.md#ended). -An example of a continuous handler is [`PanGestureHandler`](../api/pan-gh.md) that once [activated](./state.md#active), will start providing updates about [translation](../api/pan-gh.md#translationx) and other properties. - -On the other hand, discrete gesture handlers once [activated](./state.md#active) will not stay in the active state but will [end](./state.md#ended) immediately. -[`LongPressGestureHandler`](../api/longpress-gh.md) 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`](../api/pan-gh.md)). - -Keep in mind that `onGestureEvent` is only generated in continuous gesture handlers and shouldn't be used in the `TapGestureHandler` and other discrete handlers. - -### Nesting handlers - -Handler components can be nested. In any case it is recommended that the innermost handler renders a native view component. There are some limitations that apply when [using `useNativeDriver` flag](#events-with-usenativedriver). An example of nested handlers: - -```js -class Multitap extends Component { - render() { - return ( - - - - - - - - ); - } -} -``` - -### Using native components - -Gesture handler library exposes a set of components normally available in React Native that are wrapped in [`NativeViewGestureHandler`](../api/nativeview-gh.md). -Here is a list of exposed components: - -- `ScrollView` -- `FlatList` -- `Switch` -- `TextInput` -- `DrawerLayoutAndroid` (**Android only**) - -If you want to use other handlers or [buttons](../../api/components/buttons.mdx) nested in a `ScrollView`, use the [`waitFor`](../api/common-gh.md#waitfor) property to define interaction between a handler and `ScrollView` - -### Events with `useNativeDriver` - -Because handlers do not instantiate native views but instead hook up to their child views, directly nesting two gesture handlers using `Animated.event` is not currently supported. -To workaround this limitation we recommend placing an `` component in between the handlers. - -Instead of doing: - -```js -const PanAndRotate = () => ( - - - - - -); -``` - -Place an `` in between the handlers: - -```js -const PanAndRotate = () => ( - - - - - - - -); -``` - -Another consequence of handlers depending on their native child components is that when using a `useNativeDriver` flag with an `Animated.event`, the child component must be wrapped by an `Animated.API` e.g. `` instead of just a ``: - -```js -class Draggable extends Component { - render() { - return ( - - {/* <-- NEEDS TO BE Animated.View */} - - ); - } -}; -``` diff --git a/docs/versioned_docs/version-2.6.0/gesture-handlers/basics/interactions.md b/docs/versioned_docs/version-2.6.0/gesture-handlers/basics/interactions.md deleted file mode 100644 index 5b7408cf5f..0000000000 --- a/docs/versioned_docs/version-2.6.0/gesture-handlers/basics/interactions.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -id: interactions -title: Cross handler interactions -sidebar_label: Cross handler interactions ---- - -Gesture handlers can "communicate" with each other to support complex gestures and control how they _[activate](./state.md#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. -Gesture handler relies on ref objects created using [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html) and introduced in [React 16.3](https://reactjs.org/blog/2018/03/29/react-v-16-3.html#createref-api). - -## Simultaneous recognition - -By default, only one gesture handler is allowed to be in the [`ACTIVE`](./state.md#active) state. -So when a gesture handler recognizes a gesture it [cancels](./state.md#cancelled) all other handlers in the [`BEGAN`](./state.md#began) state and prevents any new handlers from receiving a stream of touch events as long as it remains [`ACTIVE`](./state.md#active). - -This behavior can be altered using the [`simultaneousHandlers`](../api/common-gh.md#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`](./state.md#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`](../api/pinch-gh.md), [`RotationGestureHandler`](../api/rotation-gh.md) and [`PanGestureHandler`](../api/pan-gh.md) that would have to simultaneously recognize gestures. - -### Example - -See the ["Scale, rotate & tilt" example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/recipes/scaleAndRotate/index.tsx) from the GestureHandler Example App or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -class PinchableBox extends React.Component { - // ...take a look on full implementation in an Example app - render() { - const imagePinch = React.createRef(); - const imageRotation = React.createRef(); - return ( - - - - - - - - - - ); - } -} -``` - -## Awaiting other handlers - -### Use cases - -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](./state.md#cancelled) the double tap handler. - -### Example - -See the ["Multitap" example](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/basic/multitap/index.tsx) from GestureHandler Example App or view it directly on your phone by visiting [our expo demo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo). - -```js -const doubleTap = React.createRef(); -const PressBox = () => ( - - nativeEvent.state === State.ACTIVE && Alert.alert('Single tap!') - } - waitFor={doubleTap}> - - nativeEvent.state === State.ACTIVE && Alert.alert("You're so fast") - } - numberOfTaps={2}> - - - -); -``` diff --git a/docs/versioned_docs/version-2.6.0/gesture-handlers/basics/state.md b/docs/versioned_docs/version-2.6.0/gesture-handlers/basics/state.md deleted file mode 100644 index 1f15f94f2f..0000000000 --- a/docs/versioned_docs/version-2.6.0/gesture-handlers/basics/state.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: state -title: Handler State -sidebar_label: Handler State ---- - -As described in ["About Gesture Handlers"](./about-handlers.md), 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: - -- [UNDETERMINED](#undetermined) -- [FAILED](#failed) -- [BEGAN](#began) -- [CANCELLED](#cancelled) -- [ACTIVE](#active) -- [END](#end) - -Each state has its own description below. - -## Accessing state - -We can monitor a handler's state changes by using the [`onHandlerStateChange`](../api/common-gh.md#onhandlerstatechange) callback and the destructured `nativeEvent` argument passed to it. -This can be done by comparing the `nativeEvent`'s [`state`](../api/common-gh.md#state) attribute to one of the constants exported under the `State` object (see example below). - -``` -import { State, LongPressGestureHandler } from 'react-native-gesture-handler'; - -class Demo extends Component { - _handleStateChange = ({ nativeEvent }) => { - if (nativeEvent.state === State.ACTIVE) { - Alert.alert('Longpress'); - } - }; - render() { - return ( - - Longpress me - - ); - } -} -``` - -## State flows - -The most typical flow of state is when a gesture handler picks up on an initial touch event then recognizes it then acknowledges its ending then resets itself back to the initial state. - -The flow looks as follows (longer arrows represent that there are possibly more touch events received before the state changes): - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`END`](#end) -> [`UNDETERMINED`](#undetermined) - -Another possible flow is when a handler receives touches that cause a recognition failure: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`FAILED`](#failed) -> [`UNDETERMINED`](#undetermined) - -At last, when a handler does properly recognize the gesture but then is interrupted by the touch system. In that case, the gesture recognition is canceled and the flow looks as follows: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`CANCELLED`](#cancelled) -> [`UNDETERMINED`](#undetermined) - -## States - -The section below describes all possible handler states: - -### UNDETERMINED - -This is the initial state of each handler and it goes into this state after it's done recognizing a gesture. - -### FAILED - -A handler 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 handler won't become active but will fail instead. Afterwards, it's state will be reset to `UNDETERMINED`. - -### BEGAN - -Handler 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 - -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](about-handlers#discrete-vs-continuous) to understand how long a handler can be kept in the `ACTIVE` state. - -### END - -The gesture recognizer has received touches signalling the end of a gesture. Its state will become `END` until it is reset to `UNDETERMINED`. diff --git a/docs/versioned_docs/version-2.6.0/guides/migrating-off-rnghenabledroot.md b/docs/versioned_docs/version-2.6.0/guides/migrating-off-rnghenabledroot.md deleted file mode 100644 index b72293fa64..0000000000 --- a/docs/versioned_docs/version-2.6.0/guides/migrating-off-rnghenabledroot.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -id: migrating-off-rnghenabledroot -title: Migrating off RNGHEnabledRootView ---- - -## Update `MainActivity.java` - -Update your `MainActivity.java` file (or wherever you create an instance of `ReactActivityDelegate`), so that it no longer overrides the method responsible for creating `ReactRootView` instance, or modify it so that it no longer uses `RNGestureHandlerEnabledRootView`. Do not forget to remove import for `RNGestureHandlerEnabledRootView`: - -```java -package com.swmansion.gesturehandler.react.example; - -import com.facebook.react.ReactActivity; -- import com.swmansion.gesturehandler.react.RNGestureHandlerEnabledRootView; -public class MainActivity extends ReactActivity { - -- @Override -- protected ReactActivityDelegate createReactActivityDelegate() { -- return new ReactActivityDelegate(this, getMainComponentName()) { -- @Override -- protected ReactRootView createRootView() { -- return new RNGestureHandlerEnabledRootView(MainActivity.this); -- } -- }; -- } -} -``` - -## Check if your app works correctly - -Some libraries (for example React Navigation) already use `GestureHandlerRootView` as a wrapper to enable gesture interactions. In that case you don't have to add one yourself. If gestures in your app work as expected after removing `RNGestureHandlerEnabledRootView` you can skip the next step. - -## Update your JS code - -Instead of using `RNGestureHandlerEnabledRootView` wrap your entry point with `` or `gestureHandlerRootHOC`, for example: - -```jsx -export default function App() { - return {/* content */}; -} -``` - -:::info -Note that `GestureHandlerRootView` acts like a normal `View`. So if you want it to fill the screen, you will need to pass `{ flex: 1 }` like you'll need to do with a normal View. By default, it'll take the size of the content nested inside. -::: \ No newline at end of file diff --git a/docs/versioned_docs/version-2.6.0/guides/testing.md b/docs/versioned_docs/version-2.6.0/guides/testing.md deleted file mode 100644 index 980160bdbd..0000000000 --- a/docs/versioned_docs/version-2.6.0/guides/testing.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -id: testing -title: Testing with Jest ---- - -## Mocking native modules - -In order to load mocks provided by RNGH add following to your jest config in `package.json`: - -```json -"setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"] -``` - -Example: - -```json -"jest": { - "preset": "react-native", - "setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"] -} -``` - -## Testing Gestures' and Gesture handlers' callbacks - -RNGH provides an API for triggering selected handlers: - -- [`fireGestureHandler(gestureOrHandler, eventList)`](../api/test-api#firegesturehandlergestureorhandler-eventlist) -- [`getByGestureTestId(testID)`](../api/test-api#getbygesturetestidtestid) diff --git a/docs/versioned_docs/version-2.6.0/guides/upgrading-to-2.md b/docs/versioned_docs/version-2.6.0/guides/upgrading-to-2.md deleted file mode 100644 index 36ff261b6e..0000000000 --- a/docs/versioned_docs/version-2.6.0/guides/upgrading-to-2.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -id: upgrading-to-2 -title: Upgrading to the new API introduced in Gesture Handler 2 ---- - -## Make sure to migrate off the `RNGestureHandlerEnabledRootView` (Android only) - -Gesture Handler 1 required you to override `createRootView` to return an instance of `RNGestureHandlerEnabledRootView`. This class has been the cause of many hard to debug and fix crashed and was deprecated in version 2.0, and subsequently removed in version 2.4. If you are still using it, check out [migrating off RNGHEnabledRootView guide](./migrating-off-rnghenabledroot.md). - -## Upgrading to the new API - -The most important change brought by the Gesture Handler 2 is the new Gesture API, along with the `GestureDetector` component. It makes declaring gesture easier, as it handles much of the work under the hood and reduces the amount of necessary boilerplate code. Instead of a separate component for every type of gesture, the `GestureDetector` component is used to attach gestures to the underlying view based on the configuration object passed to it. The configuration objects are created using the `Gesture` object, here is a simple example: - -```jsx -const tapGesture = Gesture.Tap().onStart(() => { - console.log('Tap!'); -}); -... -return ( - - - -); -``` - -As you can see, there are no `onGestureEvent` and `onHandlerStateChange` callbacks, instead the state machine is handled under the hood and relevant callbacks are called for specific transitions or events: -- `onBegin` - called when the gesture transitions to the `BEGAN` state, which in most cases is when the gesture starts processing the touch stream - when the finger first touches the view -- `onStart` - called when the activation criteria for the gesture are met and it transitions from `BEGAN` to `ACTIVE` state -- `onUpdate` - replaces `onGestureEvent`, called every time the gesture sends a new event while it's in the `ACTIVE` state -- `onChange` - if defined, called just after `onUpdate`, the events passed to it are the same as the ones passed to `onUpdate` but they also contain `change` values which hold the change in value they represent since the last event (i.e. in case of the `Pan` gesture, the event will also contain `changeX` and `changeY` properties) -- `onEnd` - called when the gesture transitions from the `ACTIVE` state to either of `END`, `FAILED` or `CANCELLED` - you can tell whether the gesture finished due to user interaction or because of other reason (like getting cancelled by the system, or failure criteria) using the second value passed to the `onEnd` callback alongside the event -- `onFinalize` called when the gesture transitions into either of `END`, `FAILED` or `CANCELLED` state, if the gesture was `ACTIVE`, `onEnd` will be called first (similarily to `onEnd` you can determine the reason for finishing using the second argument) - -The difference between `onEnd` and `onFinalize` is that the `onEnd` will be called only if the gesture was `ACTIVE`, while `onFinalize` will be called if the gesture has `BEGAN`. This means that you can use `onEnd` to clean up after `onStart`, and `onFinalize` to clean up after `onBegin` (or both `onBegin` and `onStart`). - -### Configuring the gestures - -The new gesture objects are configured in the builder-like pattern. Instead of properties, each gesture provides methods that allow for its customization. In most cases the names of the methods are the same as the relevant props, ot at least very similar. For example: - -```jsx -return ( - { - if (nativeEvent.state === State.ACTIVE) { - console.log('Tap!'); - } - }}> - - -); -``` - -Would have the same effect as: - -```jsx -const tapGesture = Gesture.Tap() - .numberOfTaps(2) - .maxDuration(500) - .maxDelay(500) - .maxDistance(10) - .onStart(() => { - console.log('Tap!'); - }); - -return ( - - - -); -``` - -You can check the modifiers available to specific gestures in the API Reference under Gestures. - -### Using multiple gestures on the same view - -Using the gesture handler components, if you wanted to have multiple gestures on one view, you would have to stack them on top of each other and, in case you wanted to use animations, add an `Animated.View` after each handler, resulting in a deep component tree, for example: - -```jsx -return ( - - - - - - - - - - - -); -``` - -With the `GestureDetector` you can use the [Gesture Composition API](../gesture-composition.md) to stack the gestures onto one view: - -```jsx -const tapGesture = Gesture.Tap(); -const panGesture = Gesture.Pan(); -const pinchGesture = Gesture.Pinch(); - -return ( - - - -); -``` - -Similarily, you can use [`Gesture.Simultaneous`](../gesture-composition.md#simultaneous) to replace stacked gesture handlers that should be able to recognize gestures simultaneously, and [`Gesture.Exclusive`](../gesture-composition.md#exclusive) to replace stacked gesture handlers that require failure of others. - -### Replacing `waitFor` and `simultaneousHandlers` - -If you want to make relations between the gestures attached to the same view, you should use the [Gesture Composition API](../gesture-composition.md) described above. However, if you want to make a relation between gestures attached to different views, or between gesture and an old gesture handler, you should use `simultaneousWithExternalGesture` instead of `simultaneousHandlers`, and `requireExternalGestureToFail` instead of `waitFor`. In case you need a ref object to pass to an old gesture handler, you can set it to the gesture using `.withRef(refObject)` modifier. \ No newline at end of file diff --git a/docs/versioned_docs/version-2.6.0/installation.md b/docs/versioned_docs/version-2.6.0/installation.md deleted file mode 100644 index caeae6f56b..0000000000 --- a/docs/versioned_docs/version-2.6.0/installation.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -id: installation -title: Installation ---- - -## Requirements - -| version | `react-native` version | -| --------- | ---------------------- | -| 2.0.0+ | 0.63.0+ | -| 1.4.0+ | 0.60.0+ | -| 1.1.0+ | 0.57.2+ | -| <1.1.0 | 0.50.0+ | - -It may be possible to use newer versions of react-native-gesture-handler on React Native with version <= 0.59 by reverse Jetifying. -Read more on that here https://github.com/mikehardy/jetifier#to-reverse-jetify--convert-node_modules-dependencies-to-support-libraries - -Note that if you wish to use [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html) support for [interactions](./gesture-handlers/basics/interactions.md) you need to use v16.3 of [React](https://reactjs.org/) - -In order to fully utilize the [touch events](./api/gestures/touch-events.md) you also need to use `react-native-reanimated` 2.3.0-beta.4 or newer. - -## Expo - -### Managed [Expo](https://expo.io) - -To use the version of react-native-gesture-handler that is compatible with your managed Expo project, run `expo install react-native-gesture-handler`. - -The Expo SDK incorporates the latest version of react-native-gesture-handler available at the time of each SDK release, so managed Expo apps might not always support all our latest features as soon as they are available. - -### Bare [React Native](http://facebook.github.io/react-native/) - -Since the library uses native support for handling gestures, it requires an extended installation to the norm. If you are starting a new project, you may want to initialize it with [expo-cli](https://docs.expo.io/versions/latest/workflow/expo-cli/) and use a bare template, they come pre-installed with react-native-gesture-handler. - -## JS - -First, install the library using `yarn`: - -```bash -yarn add react-native-gesture-handler -``` - -or with `npm` if you prefer: - -```bash -npm install --save react-native-gesture-handler -``` - -After installation, wrap your entry point with `` or -`gestureHandlerRootHOC`. - -For example: - -```js -export default function App() { - return {/* content */}; -} -``` - -:::info -If you use props such as `shouldCancelWhenOutside`, `simultaneousHandlers`, `waitFor` etc. with gesture handlers, the handlers need to be mounted under a single `GestureHandlerRootView`. So it's important to keep the `GestureHandlerRootView` as close to the actual root view as possible. - -Note that `GestureHandlerRootView` acts like a normal `View`. So if you want it to fill the screen, you will need to pass `{ flex: 1 }` like you'll need to do with a normal `View`. By default, it'll take the size of the content nested inside. -::: - -:::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. -::: - -### Linking - -> **Important**: You only need to do this step if you're using React Native 0.59 or lower. Since v0.60, linking happens automatically. - -```bash -react-native link react-native-gesture-handler -``` - -## Fabric -Starting with version 2.3.0, Gesture Handler now supports [Fabric](https://reactnative.dev/docs/fabric-renderer)!. To use Gesture Handler in your Fabric application you have to: -#### on iOS: -Install pods using `RCT_NEW_ARCH_ENABLED=1 pod install` – this is the same command you run to prepare a Fabric build but you also need to run it after a new native library gets added. -#### on Android: -There are no additional steps required so long as your app is configured to build with Fabric – this is typically configured by setting `newArchEnabled=true` in `gradle.properties` file in your project. - -### 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` (you can do this using `gestureHandlerRootHOC` function). This can be done for example at the stage when you register your screens. Here's an example: - -```js -import { gestureHandlerRootHOC } from 'react-native-gesture-handler'; -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', - () => gestureHandlerRootHOC(FirstTabScreen), - () => FirstTabScreen - ); - Navigation.registerComponent('example.SecondTabScreen', - () => gestureHandlerRootHOC(SecondTabScreen), - () => SecondTabScreen - ); - Navigation.registerComponent('example.PushedScreen', - () => gestureHandlerRootHOC(PushedScreen), - () => 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` (you can do this using `gestureHandlerRootHOC` function) as with native navigation libraries each screen maps to a separate root view. It will not be enough to wrap the main screen only. - -## Android - -### Usage with modals on Android - -On Android RNGH does not work by default because modals are not located under React Native Root view in native hierarchy. -To fix that, components need to be wrapped with `gestureHandlerRootHOC` (it's no-op on iOS and web). - -For example: - -```js -const ExampleWithHoc = gestureHandlerRootHOC(() => ( - - - - ); -); - -export default function Example() { - return ( - - - - ); -} -``` - -### Kotlin - -Since version `2.0.0` RNGH has been rewritten with Kotlin. The default version of the Kotlin plugin used in this library is `1.5.20`. - -If you need to use a different Kotlin version, set the `kotlinVersion` ext property in `android/build.gradle` file and RNGH will use that version: - -``` -buildscript { - ext { - ... - kotlinVersion = "1.5.20" - } -} -``` - -The minimal version of the Kotlin plugin supported by RNGH is `1.4.10`. - -## iOS - -There is no additional configuration required on iOS except what follows in the next steps. - -If you're in a CocoaPods project (the default setup since React Native 0.60), -make sure to install pods before you run your app: - -```bash -cd ios && pod install -``` - -For React Native 0.61 or greater, add the library as the first import in your index.js file: - -```js -import 'react-native-gesture-handler'; -``` - -## Web - -There is no additional configuration required for the web, however, since the Gesture Handler 2.10.0 the new web implementation is enabled by default. It is recommended to check if the gestures in your app are working as expected since their behavior should now resemble the native platforms. If you don't want to use the new implementation, you can still revert back to the legacy one by enabling it at the beginning of your `index.js` file: - -```js -import { enableLegacyWebImplementation } from 'react-native-gesture-handler'; - -enableLegacyWebImplementation(true); -``` - -Nonetheless, it's recommended to adapt to the new implementation, as the legacy one will be dropped at some point in the future. - -If you want to start using the new implementation but don't want to upgrade Gesture Handler, you can enable it (starting with Gesture Handler 2.6.0) at the beginning of your `index.js` file: - -```js -import { enableExperimentalWebImplementation } from 'react-native-gesture-handler'; - -enableExperimentalWebImplementation(true); -``` diff --git a/docs/versioned_docs/version-2.6.0/introduction.md b/docs/versioned_docs/version-2.6.0/introduction.md deleted file mode 100644 index e07201d413..0000000000 --- a/docs/versioned_docs/version-2.6.0/introduction.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -id: introduction -title: Introduction -sidebar_label: Introduction -slug: / ---- - -Gesture Handler aims to replace React Native's built in touch system called [Gesture Responder System](http://facebook.github.io/react-native/docs/gesture-responder-system). - -The motivation for building this library was to address the performance limitations of React Native's Gesture Responder System and to provide more control over the built-in native components that can handle gestures. -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. - -In a nutshell, the library provides: - -- A way to use a platform's native touch handling system for recognizing pinch, rotation and pan (besides a few other gestures). -- The ability to define relations between gesture handlers, e.g. when you have a pan handler in `ScrollView` you can make that `ScrollView` wait until it knows pan won't recognize. -- Mechanisms to use touchables 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. - -:::info -It is recommended to use Reanimated 2 for animations when using React Native Gesture Handler as its more advanced features rely heavily on the worklets provided by Reanimated. -::: - -## RNGH 2.0 - -RNGH2 introduces a new way of creating gestures. Instead of creating a gesture handler component for every gesture you want to create, you just need to create a `GestureDetector` component and assign to it all the gestures you want it to recognize. It is also designed to work seamlessly with `Reanimated 2` and it will automatically detect if it is installed, and start using it if it is. -You can create gestures using the `Gesture` object and methods it provides, and configure them in the builder-like pattern. If you want to specify behavior between the gestures instead of using `waitFor` and `simultaneousGestures` you can use the new system of [gesture composition](./gesture-composition). -Along the new API, version 2.0 brings one of the most requested features: [touch events and manual gestures](manual-gestures). Thanks to great work done by the Reanimated team, we were able to provide synchronous communication between gestures and their native implementation using worklets. This allows to manage gesture state from the JS without risking race-conditions. - -### Interoperability with gesture handlers - -The new API with gestures is somewhat compatible with the old gesture handlers. Unfortunately you cannot use the new gesture composing with gesture handlers, however you can still mark relations using refs. If you want to make a gesture handler wait for (or simultaneous with) a gesture, simply use withRef method on the gesture to set the ref object and pass it to the appropriate property on the gesture handler. - -Similarly, if you want to make a gesture simultaneous with (or wait for failure of) a gesture handler, set the ref prop of the gesture handler and pass the same ref to the simultaneousWithExternalGesture or requireExternalGestureToFail method on the gesture object. - -This should allow you to migrate your codebase from the gesture handlers to gestures smoothly and at your own pace. Just keep in mind that the gesture handlers cannot have the GestureDetector as their direct child, as it's a functional component. - -### Automatic workletization of gesture callbacks - -Reanimated's Babel plugin is setup in a way that automatically marks callbacks passed to gestures in the configuration chain as worklets. This means that as long as all your callbacks are defined in a single chain, you don't need to add a `'worklet';` directive at the beginning of the functions. Here is an example that will be automatically workletized: -```jsx -const gesture = Gesture.Tap().onBegin(() => { - console.log(_WORKLET); -}); -``` -And here are some examples that won't: -```jsx -const gesture = Gesture.Tap(); -gesture.onBegin(() => { - console.log(_WORKLET); -}); -``` - -```jsx -const callback = () => { - console.log(_WORKLET); -}; -const gesture = Gesture.Tap().onBegin(callback); -``` - -```jsx -const callback = () => { - console.log(_WORKLET); -}; -const gesture = Gesture.Tap(); -gesture.onBegin(callback); -``` - -## Learning resources - -### Apps - -[Gesture Handler Example App](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example) – official gesture handler "showcase" app. - -[Gesture Handler Example on Expo](https://snack.expo.io/@adamgrzybowski/react-native-gesture-handler-demo) – the official app you can install and play with using [Expo](https://expo.io). - -### 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 Vetne](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 [me on Twitter](https://twitter.com/kzzzf)! - -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
-
- -
-
- -
-
Jakub Gonet
-
- -
-
- -
-
Krzysztof Magiera
- @kzzzf -
- -
- -### 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: - -
- -
- -
- -
-
Shopify
- -
- -
- -
- -
-
Expo
- -
- -
diff --git a/docs/versioned_docs/version-2.6.0/manual-gestures/manual-gestures.md b/docs/versioned_docs/version-2.6.0/manual-gestures/manual-gestures.md deleted file mode 100644 index eae7fffd2d..0000000000 --- a/docs/versioned_docs/version-2.6.0/manual-gestures/manual-gestures.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -id: manual-gestures -title: Manual gestures -sidebar_label: Manual gestures ---- - -import Step, { Divider } from '@site/src/theme/Step'; -import Step1 from './step1.md'; -import Step2 from './step2.md'; -import Step3 from './step3.md'; -import Step4 from './step4.md'; -import Step5 from './step5.md'; -import Step6 from './step6.md'; -import Step7 from './step7.md'; - -RNGH2 finally brings one of the most requested features: manual gestures and touch events. To demonstrate how to make a manual gesture we will make a simple one that tracks all pointers on the screen. - - - - - First, we need a way to store information about the pointer: whether it should be visible and its position. - - - - - - - We also need a component to mark where a pointer is. In order to accomplish that we will make a component that accepts two shared values: one holding information about the pointer using the interface we just created, the other holding a bool indicating whether the gesture has activated. - In this example when the gesture is not active, the ball representing it will be blue and when it is active the ball will be red and slightly bigger. - - - - - - - Now we have to make a component that will handle the gesture and draw all the pointer indicators. We will store data about pointers in an array of size 12 as that is the maximum number of touches that RNGH will track, and render them inside an Animated.View. - - - - - - - We have our components set up and we can finally get to making the gesture! We will start with onTouchesDown where we need to set position of the pointers and make them visible. We can get this information from the touches property of the event. In this case we will also check how many pointers are on the screen and activate the gesture if there are at least two. - - - - - - - Next, we will handle pointer movement. In onTouchesMove we will simply update the position of moved pointers. - - - - - - - We also need to handle lifting fingers from the screen, which corresponds to onTouchesUp. Here we will just hide the pointers that were lifted and end the gesture if there are no more pointers on the screen. - Note that we are not handling onTouchesCancelled as in this very basic case we don't expect it to happen, however you should clear data about cancelled pointers (most of the time all active ones) when it is called. - - - - - - - Now that our pointers are being tracked correctly and we have the state management, we can handle activation and ending of the gesture. In our case, we will simply set the active shared value either to true or false. - - - - - -And that's all! As you can see using manual gestures is really easy but as you can imagine, manual gestures are a powerful tool that makes it possible to accomplish things that were previously impossible with RNGH. - -## Modifying existing gestures - -While manual gestures open great possibilities we are aware that reimplementing pinch or rotation from scratch just because you need to activate in specific circumstances or require position of the fingers, would be a waste of time as those gestures are already there. Because of that you can use touch events with every gesture so that you can extract more informations about gesture than is sent to you in events. We also added a `manualActivation` modifier on all continous gestures, which prevents the gesture it is applied to from activating by itself thus giving you full control of its behavior. - -This functionality makes another highly requested feature possible: drag after long press. Simply set `manualActivation` to `true` on a `PanGesture` and use `StateManager` to fail the gesture if the user attempts to drag the component sooner than the duration of the long press. diff --git a/docs/versioned_docs/version-2.6.0/manual-gestures/step1.md b/docs/versioned_docs/version-2.6.0/manual-gestures/step1.md deleted file mode 100644 index 4c6331c1c8..0000000000 --- a/docs/versioned_docs/version-2.6.0/manual-gestures/step1.md +++ /dev/null @@ -1,7 +0,0 @@ -```jsx -interface Pointer { - visible: boolean; - x: number; - y: number; -} -``` diff --git a/docs/versioned_docs/version-2.6.0/manual-gestures/step2.md b/docs/versioned_docs/version-2.6.0/manual-gestures/step2.md deleted file mode 100644 index 3137d334ef..0000000000 --- a/docs/versioned_docs/version-2.6.0/manual-gestures/step2.md +++ /dev/null @@ -1,35 +0,0 @@ -```jsx -function PointerElement(props: { - pointer: Animated.SharedValue, - active: Animated.SharedValue, -}) { - const animatedStyle = useAnimatedStyle(() => ({ - transform: [ - { translateX: props.pointer.value.x }, - { translateY: props.pointer.value.y }, - { - scale: - (props.pointer.value.visible ? 1 : 0) * - (props.active.value ? 1.3 : 1), - }, - ], - backgroundColor: props.active.value ? 'red' : 'blue', - })); - - return ; -} - -... - -const styles = StyleSheet.create({ - pointer: { - width: 60, - height: 60, - borderRadius: 30, - backgroundColor: 'red', - position: 'absolute', - marginStart: -30, - marginTop: -30, - }, -}); -``` diff --git a/docs/versioned_docs/version-2.6.0/manual-gestures/step3.md b/docs/versioned_docs/version-2.6.0/manual-gestures/step3.md deleted file mode 100644 index c9b32e5c2a..0000000000 --- a/docs/versioned_docs/version-2.6.0/manual-gestures/step3.md +++ /dev/null @@ -1,29 +0,0 @@ -```jsx -export default function Example() { - const trackedPointers: Animated.SharedValue[] = []; - const active = useSharedValue(false); - - for (let i = 0; i < 12; i++) { - trackedPointers[i] = - useSharedValue < - Pointer > - { - visible: false, - x: 0, - y: 0, - }; - } - - const gesture = Gesture.Manual(); - - return ( - - - {trackedPointers.map((pointer, index) => ( - - ))} - - - ); -} -``` diff --git a/docs/versioned_docs/version-2.6.0/manual-gestures/step4.md b/docs/versioned_docs/version-2.6.0/manual-gestures/step4.md deleted file mode 100644 index 36ec2c34bd..0000000000 --- a/docs/versioned_docs/version-2.6.0/manual-gestures/step4.md +++ /dev/null @@ -1,15 +0,0 @@ -```jsx {2-15} -const gesture = Gesture.Manual().onTouchesDown((e, manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: true, - x: touch.x, - y: touch.y, - }; - } - - if (e.numberOfTouches >= 2) { - manager.activate(); - } -}); -``` diff --git a/docs/versioned_docs/version-2.6.0/manual-gestures/step5.md b/docs/versioned_docs/version-2.6.0/manual-gestures/step5.md deleted file mode 100644 index d2f9377cc8..0000000000 --- a/docs/versioned_docs/version-2.6.0/manual-gestures/step5.md +++ /dev/null @@ -1,13 +0,0 @@ -```jsx {3-12} -const gesture = Gesture.Manual() - ... - .onTouchesMove((e, _manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: true, - x: touch.x, - y: touch.y, - }; - } - }) -``` diff --git a/docs/versioned_docs/version-2.6.0/manual-gestures/step6.md b/docs/versioned_docs/version-2.6.0/manual-gestures/step6.md deleted file mode 100644 index 323f9516cb..0000000000 --- a/docs/versioned_docs/version-2.6.0/manual-gestures/step6.md +++ /dev/null @@ -1,17 +0,0 @@ -```jsx {3-16} -const gesture = Gesture.Manual() - ... - .onTouchesUp((e, manager) => { - for (const touch of e.changedTouches) { - trackedPointers[touch.id].value = { - visible: false, - x: touch.x, - y: touch.y, - }; - } - - if (e.numberOfTouches === 0) { - manager.end(); - } - }) -``` diff --git a/docs/versioned_docs/version-2.6.0/manual-gestures/step7.md b/docs/versioned_docs/version-2.6.0/manual-gestures/step7.md deleted file mode 100644 index 913e766ae8..0000000000 --- a/docs/versioned_docs/version-2.6.0/manual-gestures/step7.md +++ /dev/null @@ -1,10 +0,0 @@ -```jsx {3-10} -const gesture = Gesture.Manual() - ... - .onStart(() => { - active.value = true; - }) - .onEnd(() => { - active.value = false; - }); -``` diff --git a/docs/versioned_docs/version-2.6.0/quickstart/quickstart.md b/docs/versioned_docs/version-2.6.0/quickstart/quickstart.md deleted file mode 100644 index c1ba3d7219..0000000000 --- a/docs/versioned_docs/version-2.6.0/quickstart/quickstart.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -id: quickstart -title: Quick start -sidebar_label: Quick start ---- - -import Step, { Divider } from '@site/src/theme/Step'; -import Step1 from './step1.md'; -import Step2 from './step2.md'; -import Step3 from './step3.md'; -import Step4 from './step4.md'; -import Step5 from './step5.md'; - -RNGH2 provides much simpler way to add gestures to your app. All you need to do is wrap the view that you want your gesture to work on with [`GestureDetector`](../api/gestures/gesture-detector), define the gesture and pass it to detector. That's all! - -To demonstrate how you would use the new API, let's make a simple app where you can drag a ball around. You will need to add `react-native-gesture-handler` (for gestures) and `react-native-reanimated` (for animations) modules. - - - - -
First let's define styles we will need to make the app:
- - - - - - -
Then we can start writing our `Ball` component:
- - - - - - -
- We also need to define{' '} - - shared values - {' '} - to keep track of the ball position and create animated styles in order to be - able to position the ball on the screen: -
- - - - - - -
And add it to the ball's styles:
- - - - - - -
- The only thing left is to define the pan gesture and assign it to the - detector: -
- - - - - -Note the `start` shared value. We need it to store the position of the ball at the moment we grab it to be able to correctly position it later, because we only have access to translation relative to the starting point of the gesture. - -Now you can just add `Ball` component to some view in the app and see the results! (Or you can just check the code [here](https://github.com/software-mansion/react-native-gesture-handler/blob/main/example/src/new_api/reanimated/index.tsx) and see it in action in the Example app.) diff --git a/docs/versioned_docs/version-2.6.0/quickstart/step1.md b/docs/versioned_docs/version-2.6.0/quickstart/step1.md deleted file mode 100644 index 1995cd907c..0000000000 --- a/docs/versioned_docs/version-2.6.0/quickstart/step1.md +++ /dev/null @@ -1,11 +0,0 @@ -```jsx -const styles = StyleSheet.create({ - ball: { - width: 100, - height: 100, - borderRadius: 100, - backgroundColor: 'blue', - alignSelf: 'center', - }, -}); -``` diff --git a/docs/versioned_docs/version-2.6.0/quickstart/step2.md b/docs/versioned_docs/version-2.6.0/quickstart/step2.md deleted file mode 100644 index 34c528266b..0000000000 --- a/docs/versioned_docs/version-2.6.0/quickstart/step2.md +++ /dev/null @@ -1,9 +0,0 @@ -```jsx -function Ball() { - return ( - - - - ); -} -``` diff --git a/docs/versioned_docs/version-2.6.0/quickstart/step3.md b/docs/versioned_docs/version-2.6.0/quickstart/step3.md deleted file mode 100644 index ee7184ffc7..0000000000 --- a/docs/versioned_docs/version-2.6.0/quickstart/step3.md +++ /dev/null @@ -1,14 +0,0 @@ -```jsx -const isPressed = useSharedValue(false); -const offset = useSharedValue({ x: 0, y: 0 }); -const animatedStyles = useAnimatedStyle(() => { - return { - transform: [ - { translateX: offset.value.x }, - { translateY: offset.value.y }, - { scale: withSpring(isPressed.value ? 1.2 : 1) }, - ], - backgroundColor: isPressed.value ? 'yellow' : 'blue', - }; -}); -``` diff --git a/docs/versioned_docs/version-2.6.0/quickstart/step4.md b/docs/versioned_docs/version-2.6.0/quickstart/step4.md deleted file mode 100644 index 8e2112a3cd..0000000000 --- a/docs/versioned_docs/version-2.6.0/quickstart/step4.md +++ /dev/null @@ -1,9 +0,0 @@ -```jsx {4} -... -return ( - - - -); -... -``` diff --git a/docs/versioned_docs/version-2.6.0/quickstart/step5.md b/docs/versioned_docs/version-2.6.0/quickstart/step5.md deleted file mode 100644 index c7c2e07265..0000000000 --- a/docs/versioned_docs/version-2.6.0/quickstart/step5.md +++ /dev/null @@ -1,32 +0,0 @@ -```jsx -const start = useSharedValue({ x: 0, y: 0 }); -const gesture = Gesture.Pan() - .onBegin(() => { - isPressed.value = 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, - }; - }) - .onFinalize(() => { - isPressed.value = false; - }); -``` - -```jsx {3} -... -return ( - - - -); -... -``` diff --git a/docs/versioned_docs/version-2.6.0/troubleshooting.md b/docs/versioned_docs/version-2.6.0/troubleshooting.md deleted file mode 100644 index 0eae67e070..0000000000 --- a/docs/versioned_docs/version-2.6.0/troubleshooting.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -id: troubleshooting -title: Troubleshooting ---- - -## Troubleshooting - -Thanks for giving this library a try! We are sorry that you might have encountered issues though. Here is how you can seek help: - -1. Search over the [issues on Github](https://github.com/software-mansion/react-native-gesture-handler/issues). There is a chance someone had this problem in the past and it has been resolved! -2. When sure your problem hasn't been reported or was reported but the proposed solution doesn't work for you please follow [our issue reporting guidelines](#reporting-issues). -3. You can try seeking help on [Expo Developers Discord](https://chat.expo.dev/) where we often hang out. -4. If you feel like reading the source code I highly recommend it, as this is by far the best resource and gives you the most up to date insights into how the library works and what might be causing the bug. -5. If you managed to find the solution consider [contributing](introduction.md#contributing) a fix or update our documentation to make this information easier to find for the others in the future. - -## Reporting issues - -This library is maintained by a very small team. -Please be mindful of that when reporting issue and when it happens that we can't get back to you as soon as you might expect. -We would love to fix all the problems as soon as possible, but often our time is constraint with other issues/features or projects. -To make it easier for us to understand your issue and to be able to approach it sooner you can help by: - -- Making sure the issue description is complete. Please include all the details about your environment (library version, RN version, device OS etc). -- It is the best to provide an example app that reproduces the issue you are having. Put it up on [gist](https://gist.github.com/), [snack](https://snack.expo.io) or create a repo on Github – it doesn't matter as long as we can easily pull it in, run and see the issue. -- Explain how you run your repro app and what steps to take to reproduce the issue. -- Isolate your issue from other dependencies you might be using and make the repro app as minimal as possible. -- If you have spent some time figuring out the root cause of the problem you can leave a note about your findings so far. -- **Do not comment on closed issues**. It is very unlikely that we are going to notice your comment in such a case. If the issue has been closed, but the proposed solution doesn't work for you, please open a new one providing all the information necessary and linking to the solution you have tried. - -## It's not a bug, it's a feature - -- Changing `enabled` prop during a gesture has no effect, only when a gesture starts (that is a finger touches the screen) the `enabled` prop is taken into consideration to decide whether to extract (or not) the gesture and provide it with stream of events to analyze. -- `Native` gesture may not conform to the standard state flow due to platform specific workarounds to incorporate native views into RNGH. -- Keep in mind that `Touchables` from RNGH are rendering two additional views that may need to be styled separately to achieve desired effect (`style` and `containerStyle` props). -- In order for the gesture composition to work, all composed gestures must be attached to the same `GestureHandlerRootView`. - -### Multiple versions of Gesture Handler were detected - -This error usually happens when in your project there exists more than one instance of Gesture Handler. It can occur when some of your dependencies have installed Gesture Handler inside their own `node_modules` instead of using it as a peer dependency. In this case two different versions of Gesture Handler JS module try to install the same Native Module. You can resolve this problem manually by modifying your `package.json` file. - -You can check which libraries are using Gesture Handler, for example, with the command: -```bash -npm why react-native-gesture-handler -``` - -If you use `yarn` you should add [`resolution` property](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/). -```json -"resolutions": { - "react-native-gesture-handler": -} -``` - -If you use `npm` you should add [`overrides` property](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides). -```json -"overrides": { - "react-native-gesture-handler": -} -``` - -After that you need to run your package manager again -```bash -yarn -``` -or -```bash -npm install -``` diff --git a/docs/versioned_docs/version-2.6.0/under-the-hood/how-does-it-work.md b/docs/versioned_docs/version-2.6.0/under-the-hood/how-does-it-work.md deleted file mode 100644 index aebed78316..0000000000 --- a/docs/versioned_docs/version-2.6.0/under-the-hood/how-does-it-work.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -id: how-does-it-work -title: How does it work? -sidebar_label: How does it work? ---- - -### Units - -All handler component properties and event attributes that represent onscreen dimensions are expressed in screen density independent units we refer to as "points". -These are the units commonly used in React Native ecosystem (e.g. in the [layout system](http://facebook.github.io/react-native/docs/flexbox.html)). -They do not map directly to physical pixels but instead to [iOS's points](https://developer.apple.com/library/content/documentation/2DDrawing/Conceptual/DrawingPrintingiOS/GraphicsDrawingOverview/GraphicsDrawingOverview.html#//apple_ref/doc/uid/TP40010156-CH14-SW7) and to [dp](https://developer.android.com/guide/topics/resources/more-resources#Dimension) units on Android. - -## iOS - -All gestures are implemented using [UIGestureRecognizers](https://developer.apple.com/documentation/uikit/uigesturerecognizer?language=objc), some of them have been slightly modified to allow for more customization and to conform to the state flow of RNGH. When you assign a gesture configuration to the `GestureDetector`, it creates all the required recognizers and assigns them to the child view of the detector. From this point most of the heavy lifting is handled by the [UIKit](https://developer.apple.com/documentation/uikit?language=objc) (with our help to correctly implement interactions between gestures). - -## Android - -Unfortunately, Android doesn't provide an easy way of handling gestures hence most of them were implemented from scratch, including a system for managing how the gestures should interact with each other. Here's a quick overview of how it works: -When you wrap a component with `GestureHandlerRootView` it allows for the RNGH to intercept all touch events on that component and process them, deciding whether they should be handled by one of the gesture handlers or passed to the underlying view. Gesture handlers are created when you assign a gesture configuration to the `GestureDetector`, it initializes all of the necessary handlers natively. Every `GestureHandlerRootView` also has a specific handler to decide whether to pass the touch events or to consume them. It can never activate, only begin, end or be cancelled. When this handler is in the `UNDETERMINED` state it means that there is no touch in progress, however when the touch starts it transitions to the `BEGAN` state. As long as it stays in that state, no touch event is consumed, but as soon as it gets cancelled (meaning that some handler has activated) all incoming touch events get consumed, preventing underlying view from receiving them. - -When a pointer touches the screen the view tree is traversed in order to extract all handlers attached to the views below the finger (including the one attached to the `GestureHandlerRootView`) and all extracted handlers transition to the `BEGAN` state, signalling that the gesture may heve began. The touch events continue to be delivered to all extracted handlers until one of them recognizes the gesture and tries to activate. At this point the orchestrator checks whether this gesture should wait for any other of the extracted gestures to fail. If it does, it's put to the waiting list, if it doesn't, it gets activated and all other gestures (that are not simultaneous with it) get cancelled. When a gesture handlers transitions to a finished state (the gesture recognized by it stops, it fails or gets cancelled) the orchestrator check the waiting handlers. Every one of them that waited for the gesture that just failed tries to activate again (and again the orchestrator checks if it should wait for any of the extracted gestures...). diff --git a/docs/versioned_docs/version-2.6.0/under-the-hood/states-events.md b/docs/versioned_docs/version-2.6.0/under-the-hood/states-events.md deleted file mode 100644 index 600f16a5cc..0000000000 --- a/docs/versioned_docs/version-2.6.0/under-the-hood/states-events.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -id: states-events -title: Gesture states & events -sidebar_label: Gesture states & events ---- - -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 (longer arrows represent that there are possibly more touch events received before the state changes): - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`END`](#end) -> [`UNDETERMINED`](#undetermined) - -Another possible flow is when a handler receives touches that cause a recognition failure: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`FAILED`](#failed) -> [`UNDETERMINED`](#undetermined) - -At last, when a handler does properly recognize the gesture but then is interrupted by the touch system the gesture recognition is canceled and the flow looks as follows: - -[`UNDETERMINED`](#undetermined) -> [`BEGAN`](#began) ------> [`ACTIVE`](#active) ------> [`CANCELLED`](#cancelled) -> [`UNDETERMINED`](#undetermined) - -## 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. - -### `onPointerChange` - -Is called before `onPointerDown`, `onPointerMove`, `onPointerUp` and `onPointerCancelled` with the same event, which may be useful in case you share logic between them. It may carry information about more than one pointer because the events are batched. diff --git a/docs/versioned_sidebars/version-1.10.3-sidebars.json b/docs/versioned_sidebars/version-1.x-sidebars.json similarity index 57% rename from docs/versioned_sidebars/version-1.10.3-sidebars.json rename to docs/versioned_sidebars/version-1.x-sidebars.json index 73f8a536ab..0f2c928b8b 100644 --- a/docs/versioned_sidebars/version-1.10.3-sidebars.json +++ b/docs/versioned_sidebars/version-1.x-sidebars.json @@ -1,5 +1,5 @@ { - "version-1.10.3/docs": [ + "version-1.x/docs": [ { "collapsed": true, "type": "category", @@ -7,23 +7,23 @@ "items": [ { "type": "doc", - "id": "version-1.10.3/getting-started" + "id": "version-1.x/getting-started" }, { "type": "doc", - "id": "version-1.10.3/about-handlers" + "id": "version-1.x/about-handlers" }, { "type": "doc", - "id": "version-1.10.3/state" + "id": "version-1.x/state" }, { "type": "doc", - "id": "version-1.10.3/interactions" + "id": "version-1.x/interactions" }, { "type": "doc", - "id": "version-1.10.3/example" + "id": "version-1.x/example" } ] }, @@ -39,43 +39,43 @@ "items": [ { "type": "doc", - "id": "version-1.10.3/api/gesture-handlers/common-gh" + "id": "version-1.x/api/gesture-handlers/common-gh" }, { "type": "doc", - "id": "version-1.10.3/api/gesture-handlers/pan-gh" + "id": "version-1.x/api/gesture-handlers/pan-gh" }, { "type": "doc", - "id": "version-1.10.3/api/gesture-handlers/tap-gh" + "id": "version-1.x/api/gesture-handlers/tap-gh" }, { "type": "doc", - "id": "version-1.10.3/api/gesture-handlers/longpress-gh" + "id": "version-1.x/api/gesture-handlers/longpress-gh" }, { "type": "doc", - "id": "version-1.10.3/api/gesture-handlers/rotation-gh" + "id": "version-1.x/api/gesture-handlers/rotation-gh" }, { "type": "doc", - "id": "version-1.10.3/api/gesture-handlers/fling-gh" + "id": "version-1.x/api/gesture-handlers/fling-gh" }, { "type": "doc", - "id": "version-1.10.3/api/gesture-handlers/pinch-gh" + "id": "version-1.x/api/gesture-handlers/pinch-gh" }, { "type": "doc", - "id": "version-1.10.3/api/gesture-handlers/force-gh" + "id": "version-1.x/api/gesture-handlers/force-gh" }, { "type": "doc", - "id": "version-1.10.3/api/gesture-handlers/nativeview-gh" + "id": "version-1.x/api/gesture-handlers/nativeview-gh" }, { "type": "doc", - "id": "version-1.10.3/api/gesture-handlers/create-native-wrapper" + "id": "version-1.x/api/gesture-handlers/create-native-wrapper" } ] }, @@ -86,19 +86,19 @@ "items": [ { "type": "doc", - "id": "version-1.10.3/api/components/buttons" + "id": "version-1.x/api/components/buttons" }, { "type": "doc", - "id": "version-1.10.3/api/components/swipeable" + "id": "version-1.x/api/components/swipeable" }, { "type": "doc", - "id": "version-1.10.3/api/components/touchables" + "id": "version-1.x/api/components/touchables" }, { "type": "doc", - "id": "version-1.10.3/api/components/drawer-layout" + "id": "version-1.x/api/components/drawer-layout" } ] } @@ -111,21 +111,21 @@ "items": [ { "type": "doc", - "id": "version-1.10.3/contributing" + "id": "version-1.x/contributing" }, { "type": "doc", - "id": "version-1.10.3/troubleshooting" + "id": "version-1.x/troubleshooting" }, { "type": "doc", - "id": "version-1.10.3/resources" + "id": "version-1.x/resources" }, { "type": "doc", - "id": "version-1.10.3/credits" + "id": "version-1.x/credits" } ] } ] -} +} \ No newline at end of file diff --git a/docs/versioned_sidebars/version-2.0.0-sidebars.json b/docs/versioned_sidebars/version-2.0.0-sidebars.json deleted file mode 100644 index 5372efebfe..0000000000 --- a/docs/versioned_sidebars/version-2.0.0-sidebars.json +++ /dev/null @@ -1,232 +0,0 @@ -{ - "version-2.0.0/docs": [ - { - "collapsed": true, - "type": "category", - "label": "Guides", - "items": [ - { - "type": "doc", - "id": "version-2.0.0/introduction" - }, - { - "type": "doc", - "id": "version-2.0.0/quickstart/quickstart" - }, - { - "type": "doc", - "id": "version-2.0.0/gesture-composition" - }, - { - "type": "doc", - "id": "version-2.0.0/manual-gestures/manual-gestures" - }, - { - "type": "doc", - "id": "version-2.0.0/whats-new" - }, - { - "type": "doc", - "id": "version-2.0.0/example" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "API reference", - "items": [ - { - "collapsed": true, - "type": "category", - "label": "Gestures", - "items": [ - { - "type": "doc", - "id": "version-2.0.0/api/gestures/gesture-detector" - }, - { - "type": "doc", - "id": "version-2.0.0/api/gestures/gesture" - }, - { - "type": "doc", - "id": "version-2.0.0/api/gestures/pan-gesture" - }, - { - "type": "doc", - "id": "version-2.0.0/api/gestures/tap-gesture" - }, - { - "type": "doc", - "id": "version-2.0.0/api/gestures/long-press-gesture" - }, - { - "type": "doc", - "id": "version-2.0.0/api/gestures/rotation-gesture" - }, - { - "type": "doc", - "id": "version-2.0.0/api/gestures/pinch-gesture" - }, - { - "type": "doc", - "id": "version-2.0.0/api/gestures/fling-gesture" - }, - { - "type": "doc", - "id": "version-2.0.0/api/gestures/force-touch-gesture" - }, - { - "type": "doc", - "id": "version-2.0.0/api/gestures/native-gesture" - }, - { - "type": "doc", - "id": "version-2.0.0/api/gestures/manual-gesture" - }, - { - "type": "doc", - "id": "version-2.0.0/api/gestures/composed-gestures" - }, - { - "type": "doc", - "id": "version-2.0.0/api/gestures/touch-events" - }, - { - "type": "doc", - "id": "version-2.0.0/api/gestures/state-manager" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Components", - "items": [ - { - "type": "doc", - "id": "version-2.0.0/api/components/buttons" - }, - { - "type": "doc", - "id": "version-2.0.0/api/components/swipeable" - }, - { - "type": "doc", - "id": "version-2.0.0/api/components/touchables" - }, - { - "type": "doc", - "id": "version-2.0.0/api/components/drawer-layout" - } - ] - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Under the hood", - "items": [ - { - "type": "doc", - "id": "version-2.0.0/under-the-hood/states-events" - }, - { - "type": "doc", - "id": "version-2.0.0/under-the-hood/how-does-it-work" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Gesture handlers", - "items": [ - { - "collapsed": true, - "type": "category", - "label": "Basics", - "items": [ - { - "type": "doc", - "id": "version-2.0.0/gesture-handlers/basics/about-handlers" - }, - { - "type": "doc", - "id": "version-2.0.0/gesture-handlers/basics/state" - }, - { - "type": "doc", - "id": "version-2.0.0/gesture-handlers/basics/interactions" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "API reference", - "items": [ - { - "type": "doc", - "id": "version-2.0.0/gesture-handlers/api/common-gh" - }, - { - "type": "doc", - "id": "version-2.0.0/gesture-handlers/api/pan-gh" - }, - { - "type": "doc", - "id": "version-2.0.0/gesture-handlers/api/tap-gh" - }, - { - "type": "doc", - "id": "version-2.0.0/gesture-handlers/api/longpress-gh" - }, - { - "type": "doc", - "id": "version-2.0.0/gesture-handlers/api/rotation-gh" - }, - { - "type": "doc", - "id": "version-2.0.0/gesture-handlers/api/fling-gh" - }, - { - "type": "doc", - "id": "version-2.0.0/gesture-handlers/api/pinch-gh" - }, - { - "type": "doc", - "id": "version-2.0.0/gesture-handlers/api/force-gh" - }, - { - "type": "doc", - "id": "version-2.0.0/gesture-handlers/api/nativeview-gh" - }, - { - "type": "doc", - "id": "version-2.0.0/gesture-handlers/api/create-native-wrapper" - } - ] - } - ] - }, - { - "type": "doc", - "id": "version-2.0.0/contributing" - }, - { - "type": "doc", - "id": "version-2.0.0/troubleshooting" - }, - { - "type": "doc", - "id": "version-2.0.0/resources" - }, - { - "type": "doc", - "id": "version-2.0.0/community" - } - ] -} diff --git a/docs/versioned_sidebars/version-2.1.1-sidebars.json b/docs/versioned_sidebars/version-2.1.1-sidebars.json deleted file mode 100644 index 15a6f2d32c..0000000000 --- a/docs/versioned_sidebars/version-2.1.1-sidebars.json +++ /dev/null @@ -1,232 +0,0 @@ -{ - "version-2.1.1/docs": [ - { - "collapsed": true, - "type": "category", - "label": "Guides", - "items": [ - { - "type": "doc", - "id": "version-2.1.1/introduction" - }, - { - "type": "doc", - "id": "version-2.1.1/quickstart/quickstart" - }, - { - "type": "doc", - "id": "version-2.1.1/gesture-composition" - }, - { - "type": "doc", - "id": "version-2.1.1/manual-gestures/manual-gestures" - }, - { - "type": "doc", - "id": "version-2.1.1/whats-new" - }, - { - "type": "doc", - "id": "version-2.1.1/example" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "API reference", - "items": [ - { - "collapsed": true, - "type": "category", - "label": "Gestures", - "items": [ - { - "type": "doc", - "id": "version-2.1.1/api/gestures/gesture-detector" - }, - { - "type": "doc", - "id": "version-2.1.1/api/gestures/gesture" - }, - { - "type": "doc", - "id": "version-2.1.1/api/gestures/pan-gesture" - }, - { - "type": "doc", - "id": "version-2.1.1/api/gestures/tap-gesture" - }, - { - "type": "doc", - "id": "version-2.1.1/api/gestures/long-press-gesture" - }, - { - "type": "doc", - "id": "version-2.1.1/api/gestures/rotation-gesture" - }, - { - "type": "doc", - "id": "version-2.1.1/api/gestures/pinch-gesture" - }, - { - "type": "doc", - "id": "version-2.1.1/api/gestures/fling-gesture" - }, - { - "type": "doc", - "id": "version-2.1.1/api/gestures/force-touch-gesture" - }, - { - "type": "doc", - "id": "version-2.1.1/api/gestures/native-gesture" - }, - { - "type": "doc", - "id": "version-2.1.1/api/gestures/manual-gesture" - }, - { - "type": "doc", - "id": "version-2.1.1/api/gestures/composed-gestures" - }, - { - "type": "doc", - "id": "version-2.1.1/api/gestures/touch-events" - }, - { - "type": "doc", - "id": "version-2.1.1/api/gestures/state-manager" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Components", - "items": [ - { - "type": "doc", - "id": "version-2.1.1/api/components/buttons" - }, - { - "type": "doc", - "id": "version-2.1.1/api/components/swipeable" - }, - { - "type": "doc", - "id": "version-2.1.1/api/components/touchables" - }, - { - "type": "doc", - "id": "version-2.1.1/api/components/drawer-layout" - } - ] - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Under the hood", - "items": [ - { - "type": "doc", - "id": "version-2.1.1/under-the-hood/states-events" - }, - { - "type": "doc", - "id": "version-2.1.1/under-the-hood/how-does-it-work" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Gesture handlers", - "items": [ - { - "collapsed": true, - "type": "category", - "label": "Basics", - "items": [ - { - "type": "doc", - "id": "version-2.1.1/gesture-handlers/basics/about-handlers" - }, - { - "type": "doc", - "id": "version-2.1.1/gesture-handlers/basics/state" - }, - { - "type": "doc", - "id": "version-2.1.1/gesture-handlers/basics/interactions" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "API reference", - "items": [ - { - "type": "doc", - "id": "version-2.1.1/gesture-handlers/api/common-gh" - }, - { - "type": "doc", - "id": "version-2.1.1/gesture-handlers/api/pan-gh" - }, - { - "type": "doc", - "id": "version-2.1.1/gesture-handlers/api/tap-gh" - }, - { - "type": "doc", - "id": "version-2.1.1/gesture-handlers/api/longpress-gh" - }, - { - "type": "doc", - "id": "version-2.1.1/gesture-handlers/api/rotation-gh" - }, - { - "type": "doc", - "id": "version-2.1.1/gesture-handlers/api/fling-gh" - }, - { - "type": "doc", - "id": "version-2.1.1/gesture-handlers/api/pinch-gh" - }, - { - "type": "doc", - "id": "version-2.1.1/gesture-handlers/api/force-gh" - }, - { - "type": "doc", - "id": "version-2.1.1/gesture-handlers/api/nativeview-gh" - }, - { - "type": "doc", - "id": "version-2.1.1/gesture-handlers/api/create-native-wrapper" - } - ] - } - ] - }, - { - "type": "doc", - "id": "version-2.1.1/contributing" - }, - { - "type": "doc", - "id": "version-2.1.1/troubleshooting" - }, - { - "type": "doc", - "id": "version-2.1.1/resources" - }, - { - "type": "doc", - "id": "version-2.1.1/community" - } - ] -} diff --git a/docs/versioned_sidebars/version-2.3.0-sidebars.json b/docs/versioned_sidebars/version-2.3.0-sidebars.json deleted file mode 100644 index ff3af04bce..0000000000 --- a/docs/versioned_sidebars/version-2.3.0-sidebars.json +++ /dev/null @@ -1,210 +0,0 @@ -{ - "version-2.3.0/docs": [ - { - "type": "doc", - "id": "version-2.3.0/introduction" - }, - { - "type": "doc", - "id": "version-2.3.0/installation" - }, - { - "type": "doc", - "id": "version-2.3.0/troubleshooting" - }, - { - "collapsed": true, - "type": "category", - "label": "Guides", - "items": [ - { - "type": "doc", - "id": "version-2.3.0/quickstart/quickstart" - }, - { - "type": "doc", - "id": "version-2.3.0/gesture-composition" - }, - { - "type": "doc", - "id": "version-2.3.0/manual-gestures/manual-gestures" - }, - { - "type": "doc", - "id": "version-2.3.0/under-the-hood/states-events" - }, - { - "type": "doc", - "id": "version-2.3.0/gesture-handlers/basics/about-handlers" - }, - { - "type": "doc", - "id": "version-2.3.0/gesture-handlers/basics/interactions" - }, - { - "type": "doc", - "id": "version-2.3.0/guides/testing" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "API reference", - "items": [ - { - "collapsed": true, - "type": "category", - "label": "Gestures", - "items": [ - { - "type": "doc", - "id": "version-2.3.0/api/gestures/gesture-detector" - }, - { - "type": "doc", - "id": "version-2.3.0/api/gestures/gesture" - }, - { - "type": "doc", - "id": "version-2.3.0/api/gestures/pan-gesture" - }, - { - "type": "doc", - "id": "version-2.3.0/api/gestures/tap-gesture" - }, - { - "type": "doc", - "id": "version-2.3.0/api/gestures/long-press-gesture" - }, - { - "type": "doc", - "id": "version-2.3.0/api/gestures/rotation-gesture" - }, - { - "type": "doc", - "id": "version-2.3.0/api/gestures/pinch-gesture" - }, - { - "type": "doc", - "id": "version-2.3.0/api/gestures/fling-gesture" - }, - { - "type": "doc", - "id": "version-2.3.0/api/gestures/force-touch-gesture" - }, - { - "type": "doc", - "id": "version-2.3.0/api/gestures/native-gesture" - }, - { - "type": "doc", - "id": "version-2.3.0/api/gestures/manual-gesture" - }, - { - "type": "doc", - "id": "version-2.3.0/api/gestures/composed-gestures" - }, - { - "type": "doc", - "id": "version-2.3.0/api/gestures/touch-events" - }, - { - "type": "doc", - "id": "version-2.3.0/api/gestures/state-manager" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Components", - "items": [ - { - "type": "doc", - "id": "version-2.3.0/api/components/buttons" - }, - { - "type": "doc", - "id": "version-2.3.0/api/components/swipeable" - }, - { - "type": "doc", - "id": "version-2.3.0/api/components/touchables" - }, - { - "type": "doc", - "id": "version-2.3.0/api/components/drawer-layout" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Gesture Handlers", - "items": [ - { - "type": "doc", - "id": "version-2.3.0/gesture-handlers/api/common-gh" - }, - { - "type": "doc", - "id": "version-2.3.0/gesture-handlers/api/pan-gh" - }, - { - "type": "doc", - "id": "version-2.3.0/gesture-handlers/api/tap-gh" - }, - { - "type": "doc", - "id": "version-2.3.0/gesture-handlers/api/longpress-gh" - }, - { - "type": "doc", - "id": "version-2.3.0/gesture-handlers/api/rotation-gh" - }, - { - "type": "doc", - "id": "version-2.3.0/gesture-handlers/api/fling-gh" - }, - { - "type": "doc", - "id": "version-2.3.0/gesture-handlers/api/pinch-gh" - }, - { - "type": "doc", - "id": "version-2.3.0/gesture-handlers/api/force-gh" - }, - { - "type": "doc", - "id": "version-2.3.0/gesture-handlers/api/nativeview-gh" - }, - { - "type": "doc", - "id": "version-2.3.0/gesture-handlers/api/create-native-wrapper" - } - ] - }, - { - "type": "doc", - "id": "version-2.3.0/api/test-api" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Under the hood", - "items": [ - { - "type": "doc", - "id": "version-2.3.0/under-the-hood/how-does-it-work" - }, - { - "type": "doc", - "id": "version-2.3.0/gesture-handlers/basics/state" - } - ] - } - ] -} diff --git a/docs/versioned_sidebars/version-2.4.0-sidebars.json b/docs/versioned_sidebars/version-2.4.0-sidebars.json deleted file mode 100644 index 12b933a6a8..0000000000 --- a/docs/versioned_sidebars/version-2.4.0-sidebars.json +++ /dev/null @@ -1,218 +0,0 @@ -{ - "version-2.4.0/docs": [ - { - "type": "doc", - "id": "version-2.4.0/introduction" - }, - { - "type": "doc", - "id": "version-2.4.0/installation" - }, - { - "type": "doc", - "id": "version-2.4.0/troubleshooting" - }, - { - "collapsed": true, - "type": "category", - "label": "Guides", - "items": [ - { - "type": "doc", - "id": "version-2.4.0/quickstart/quickstart" - }, - { - "type": "doc", - "id": "version-2.4.0/gesture-composition" - }, - { - "type": "doc", - "id": "version-2.4.0/manual-gestures/manual-gestures" - }, - { - "type": "doc", - "id": "version-2.4.0/under-the-hood/states-events" - }, - { - "type": "doc", - "id": "version-2.4.0/gesture-handlers/basics/about-handlers" - }, - { - "type": "doc", - "id": "version-2.4.0/gesture-handlers/basics/interactions" - }, - { - "type": "doc", - "id": "version-2.4.0/guides/testing" - }, - { - "type": "doc", - "id": "version-2.4.0/guides/migrating-off-rnghenabledroot" - }, - { - "type": "doc", - "id": "version-2.4.0/guides/upgrading-to-2" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "API reference", - "items": [ - { - "collapsed": true, - "type": "category", - "label": "Gestures", - "items": [ - { - "type": "doc", - "id": "version-2.4.0/api/gestures/gesture-detector" - }, - { - "type": "doc", - "id": "version-2.4.0/api/gestures/gesture" - }, - { - "type": "doc", - "id": "version-2.4.0/api/gestures/pan-gesture" - }, - { - "type": "doc", - "id": "version-2.4.0/api/gestures/tap-gesture" - }, - { - "type": "doc", - "id": "version-2.4.0/api/gestures/long-press-gesture" - }, - { - "type": "doc", - "id": "version-2.4.0/api/gestures/rotation-gesture" - }, - { - "type": "doc", - "id": "version-2.4.0/api/gestures/pinch-gesture" - }, - { - "type": "doc", - "id": "version-2.4.0/api/gestures/fling-gesture" - }, - { - "type": "doc", - "id": "version-2.4.0/api/gestures/force-touch-gesture" - }, - { - "type": "doc", - "id": "version-2.4.0/api/gestures/native-gesture" - }, - { - "type": "doc", - "id": "version-2.4.0/api/gestures/manual-gesture" - }, - { - "type": "doc", - "id": "version-2.4.0/api/gestures/composed-gestures" - }, - { - "type": "doc", - "id": "version-2.4.0/api/gestures/touch-events" - }, - { - "type": "doc", - "id": "version-2.4.0/api/gestures/state-manager" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Components", - "items": [ - { - "type": "doc", - "id": "version-2.4.0/api/components/buttons" - }, - { - "type": "doc", - "id": "version-2.4.0/api/components/swipeable" - }, - { - "type": "doc", - "id": "version-2.4.0/api/components/touchables" - }, - { - "type": "doc", - "id": "version-2.4.0/api/components/drawer-layout" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Gesture Handlers", - "items": [ - { - "type": "doc", - "id": "version-2.4.0/gesture-handlers/api/common-gh" - }, - { - "type": "doc", - "id": "version-2.4.0/gesture-handlers/api/pan-gh" - }, - { - "type": "doc", - "id": "version-2.4.0/gesture-handlers/api/tap-gh" - }, - { - "type": "doc", - "id": "version-2.4.0/gesture-handlers/api/longpress-gh" - }, - { - "type": "doc", - "id": "version-2.4.0/gesture-handlers/api/rotation-gh" - }, - { - "type": "doc", - "id": "version-2.4.0/gesture-handlers/api/fling-gh" - }, - { - "type": "doc", - "id": "version-2.4.0/gesture-handlers/api/pinch-gh" - }, - { - "type": "doc", - "id": "version-2.4.0/gesture-handlers/api/force-gh" - }, - { - "type": "doc", - "id": "version-2.4.0/gesture-handlers/api/nativeview-gh" - }, - { - "type": "doc", - "id": "version-2.4.0/gesture-handlers/api/create-native-wrapper" - } - ] - }, - { - "type": "doc", - "id": "version-2.4.0/api/test-api" - } - ] - }, - { - "collapsed": true, - "type": "category", - "label": "Under the hood", - "items": [ - { - "type": "doc", - "id": "version-2.4.0/under-the-hood/how-does-it-work" - }, - { - "type": "doc", - "id": "version-2.4.0/gesture-handlers/basics/state" - } - ] - } - ] -} diff --git a/docs/versioned_sidebars/version-2.6.0-sidebars.json b/docs/versioned_sidebars/version-2.6.0-sidebars.json deleted file mode 100644 index a7245ed75a..0000000000 --- a/docs/versioned_sidebars/version-2.6.0-sidebars.json +++ /dev/null @@ -1,95 +0,0 @@ -{ - "docs": [ - { - "type": "doc", - "id": "introduction" - }, - { - "type": "doc", - "id": "installation" - }, - { - "type": "doc", - "id": "troubleshooting" - }, - { - "type": "category", - "label": "Guides", - "items": [ - "quickstart/quickstart", - "gesture-composition", - "manual-gestures/manual-gestures", - "under-the-hood/states-events", - "gesture-handlers/basics/about-handlers", - "gesture-handlers/basics/interactions", - "guides/testing", - "guides/migrating-off-rnghenabledroot", - "guides/upgrading-to-2" - ] - }, - { - "type": "category", - "label": "API reference", - "items": [ - { - "type": "category", - "label": "Gestures", - "items": [ - "api/gestures/gesture-detector", - "api/gestures/gesture", - "api/gestures/pan-gesture", - "api/gestures/tap-gesture", - "api/gestures/long-press-gesture", - "api/gestures/rotation-gesture", - "api/gestures/pinch-gesture", - "api/gestures/fling-gesture", - "api/gestures/force-touch-gesture", - "api/gestures/native-gesture", - "api/gestures/manual-gesture", - "api/gestures/composed-gestures", - "api/gestures/touch-events", - "api/gestures/state-manager" - ] - }, - { - "type": "category", - "label": "Components", - "items": [ - "api/components/buttons", - "api/components/swipeable", - "api/components/touchables", - "api/components/drawer-layout" - ] - }, - { - "type": "category", - "label": "Gesture Handlers", - "items": [ - "gesture-handlers/api/common-gh", - "gesture-handlers/api/pan-gh", - "gesture-handlers/api/tap-gh", - "gesture-handlers/api/longpress-gh", - "gesture-handlers/api/rotation-gh", - "gesture-handlers/api/fling-gh", - "gesture-handlers/api/pinch-gh", - "gesture-handlers/api/force-gh", - "gesture-handlers/api/nativeview-gh", - "gesture-handlers/api/create-native-wrapper" - ] - }, - { - "type": "doc", - "id": "api/test-api" - } - ] - }, - { - "type": "category", - "label": "Under the hood", - "items": [ - "under-the-hood/how-does-it-work", - "gesture-handlers/basics/state" - ] - } - ] -} diff --git a/docs/versions.json b/docs/versions.json index 08b080b159..056f6d5681 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,8 +1,3 @@ [ - "2.6.0", - "2.4.0", - "2.3.0", - "2.1.1", - "2.0.0", - "1.10.3" + "1.x" ] diff --git a/docs/yarn.lock b/docs/yarn.lock index 660308027f..24f7cd9636 100644 --- a/docs/yarn.lock +++ b/docs/yarn.lock @@ -1519,10 +1519,10 @@ "@docsearch/css" "3.1.1" algoliasearch "^4.0.0" -"@docusaurus/core@2.3.1", "@docusaurus/core@^2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/core/-/core-2.3.1.tgz#32849f2ffd2f086a4e55739af8c4195c5eb386f2" - integrity sha512-0Jd4jtizqnRAr7svWaBbbrCCN8mzBNd2xFLoT/IM7bGfFie5y58oz97KzXliwiLY3zWjqMXjQcuP1a5VgCv2JA== +"@docusaurus/core@2.4.3", "@docusaurus/core@^2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/core/-/core-2.4.3.tgz#d86624901386fd8164ce4bff9cc7f16fde57f523" + integrity sha512-dWH5P7cgeNSIg9ufReX6gaCl/TmrGKD38Orbwuz05WPhAQtFXHd5B8Qym1TiXfvUNvwoYKkAJOJuGe8ou0Z7PA== dependencies: "@babel/core" "^7.18.6" "@babel/generator" "^7.18.7" @@ -1534,13 +1534,13 @@ "@babel/runtime" "^7.18.6" "@babel/runtime-corejs3" "^7.18.6" "@babel/traverse" "^7.18.8" - "@docusaurus/cssnano-preset" "2.3.1" - "@docusaurus/logger" "2.3.1" - "@docusaurus/mdx-loader" "2.3.1" + "@docusaurus/cssnano-preset" "2.4.3" + "@docusaurus/logger" "2.4.3" + "@docusaurus/mdx-loader" "2.4.3" "@docusaurus/react-loadable" "5.5.2" - "@docusaurus/utils" "2.3.1" - "@docusaurus/utils-common" "2.3.1" - "@docusaurus/utils-validation" "2.3.1" + "@docusaurus/utils" "2.4.3" + "@docusaurus/utils-common" "2.4.3" + "@docusaurus/utils-validation" "2.4.3" "@slorber/static-site-generator-webpack-plugin" "^4.0.7" "@svgr/webpack" "^6.2.1" autoprefixer "^10.4.7" @@ -1596,33 +1596,33 @@ webpack-merge "^5.8.0" webpackbar "^5.0.2" -"@docusaurus/cssnano-preset@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/cssnano-preset/-/cssnano-preset-2.3.1.tgz#e042487655e3e062417855e12edb3f6eee8f5ecb" - integrity sha512-7mIhAROES6CY1GmCjR4CZkUfjTL6B3u6rKHK0ChQl2d1IevYXq/k/vFgvOrJfcKxiObpMnE9+X6R2Wt1KqxC6w== +"@docusaurus/cssnano-preset@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/cssnano-preset/-/cssnano-preset-2.4.3.tgz#1d7e833c41ce240fcc2812a2ac27f7b862f32de0" + integrity sha512-ZvGSRCi7z9wLnZrXNPG6DmVPHdKGd8dIn9pYbEOFiYihfv4uDR3UtxogmKf+rT8ZlKFf5Lqne8E8nt08zNM8CA== dependencies: cssnano-preset-advanced "^5.3.8" postcss "^8.4.14" postcss-sort-media-queries "^4.2.1" tslib "^2.4.0" -"@docusaurus/logger@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/logger/-/logger-2.3.1.tgz#d76aefb452e3734b4e0e645efc6cbfc0aae52869" - integrity sha512-2lAV/olKKVr9qJhfHFCaqBIl8FgYjbUFwgUnX76+cULwQYss+42ZQ3grHGFvI0ocN2X55WcYe64ellQXz7suqg== +"@docusaurus/logger@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/logger/-/logger-2.4.3.tgz#518bbc965fb4ebe8f1d0b14e5f4161607552d34c" + integrity sha512-Zxws7r3yLufk9xM1zq9ged0YHs65mlRmtsobnFkdZTxWXdTYlWWLWdKyNKAsVC+D7zg+pv2fGbyabdOnyZOM3w== dependencies: chalk "^4.1.2" tslib "^2.4.0" -"@docusaurus/mdx-loader@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/mdx-loader/-/mdx-loader-2.3.1.tgz#7ec6acee5eff0a280e1b399ea4dd690b15a793f7" - integrity sha512-Gzga7OsxQRpt3392K9lv/bW4jGppdLFJh3luKRknCKSAaZrmVkOQv2gvCn8LAOSZ3uRg5No7AgYs/vpL8K94lA== +"@docusaurus/mdx-loader@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/mdx-loader/-/mdx-loader-2.4.3.tgz#e8ff37f30a060eaa97b8121c135f74cb531a4a3e" + integrity sha512-b1+fDnWtl3GiqkL0BRjYtc94FZrcDDBV1j8446+4tptB9BAOlePwG2p/pK6vGvfL53lkOsszXMghr2g67M0vCw== dependencies: "@babel/parser" "^7.18.8" "@babel/traverse" "^7.18.8" - "@docusaurus/logger" "2.3.1" - "@docusaurus/utils" "2.3.1" + "@docusaurus/logger" "2.4.3" + "@docusaurus/utils" "2.4.3" "@mdx-js/mdx" "^1.6.22" escape-html "^1.0.3" file-loader "^6.2.0" @@ -1637,13 +1637,13 @@ url-loader "^4.1.1" webpack "^5.73.0" -"@docusaurus/module-type-aliases@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/module-type-aliases/-/module-type-aliases-2.3.1.tgz#986186200818fed999be2e18d6c698eaf4683a33" - integrity sha512-6KkxfAVOJqIUynTRb/tphYCl+co3cP0PlHiMDbi+SzmYxMdgIrwYqH9yAnGSDoN6Jk2ZE/JY/Azs/8LPgKP48A== +"@docusaurus/module-type-aliases@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/module-type-aliases/-/module-type-aliases-2.4.3.tgz#d08ef67e4151e02f352a2836bcf9ecde3b9c56ac" + integrity sha512-cwkBkt1UCiduuvEAo7XZY01dJfRn7UR/75mBgOdb1hKknhrabJZ8YH+7savd/y9kLExPyrhe0QwdS9GuzsRRIA== dependencies: "@docusaurus/react-loadable" "5.5.2" - "@docusaurus/types" "2.3.1" + "@docusaurus/types" "2.4.3" "@types/history" "^4.7.11" "@types/react" "*" "@types/react-router-config" "*" @@ -1651,18 +1651,18 @@ react-helmet-async "*" react-loadable "npm:@docusaurus/react-loadable@5.5.2" -"@docusaurus/plugin-content-blog@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/plugin-content-blog/-/plugin-content-blog-2.3.1.tgz#236b8ee4f20f7047aa9c285ae77ae36683ad48a3" - integrity sha512-f5LjqX+9WkiLyGiQ41x/KGSJ/9bOjSD8lsVhPvYeUYHCtYpuiDKfhZE07O4EqpHkBx4NQdtQDbp+aptgHSTuiw== - dependencies: - "@docusaurus/core" "2.3.1" - "@docusaurus/logger" "2.3.1" - "@docusaurus/mdx-loader" "2.3.1" - "@docusaurus/types" "2.3.1" - "@docusaurus/utils" "2.3.1" - "@docusaurus/utils-common" "2.3.1" - "@docusaurus/utils-validation" "2.3.1" +"@docusaurus/plugin-content-blog@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/plugin-content-blog/-/plugin-content-blog-2.4.3.tgz#6473b974acab98e967414d8bbb0d37e0cedcea14" + integrity sha512-PVhypqaA0t98zVDpOeTqWUTvRqCEjJubtfFUQ7zJNYdbYTbS/E/ytq6zbLVsN/dImvemtO/5JQgjLxsh8XLo8Q== + dependencies: + "@docusaurus/core" "2.4.3" + "@docusaurus/logger" "2.4.3" + "@docusaurus/mdx-loader" "2.4.3" + "@docusaurus/types" "2.4.3" + "@docusaurus/utils" "2.4.3" + "@docusaurus/utils-common" "2.4.3" + "@docusaurus/utils-validation" "2.4.3" cheerio "^1.0.0-rc.12" feed "^4.2.2" fs-extra "^10.1.0" @@ -1673,18 +1673,18 @@ utility-types "^3.10.0" webpack "^5.73.0" -"@docusaurus/plugin-content-docs@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/plugin-content-docs/-/plugin-content-docs-2.3.1.tgz#feae1555479558a55182f22f8a07acc5e0d7444d" - integrity sha512-DxztTOBEruv7qFxqUtbsqXeNcHqcVEIEe+NQoI1oi2DBmKBhW/o0MIal8lt+9gvmpx3oYtlwmLOOGepxZgJGkw== - dependencies: - "@docusaurus/core" "2.3.1" - "@docusaurus/logger" "2.3.1" - "@docusaurus/mdx-loader" "2.3.1" - "@docusaurus/module-type-aliases" "2.3.1" - "@docusaurus/types" "2.3.1" - "@docusaurus/utils" "2.3.1" - "@docusaurus/utils-validation" "2.3.1" +"@docusaurus/plugin-content-docs@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/plugin-content-docs/-/plugin-content-docs-2.4.3.tgz#aa224c0512351e81807adf778ca59fd9cd136973" + integrity sha512-N7Po2LSH6UejQhzTCsvuX5NOzlC+HiXOVvofnEPj0WhMu1etpLEXE6a4aTxrtg95lQ5kf0xUIdjX9sh3d3G76A== + dependencies: + "@docusaurus/core" "2.4.3" + "@docusaurus/logger" "2.4.3" + "@docusaurus/mdx-loader" "2.4.3" + "@docusaurus/module-type-aliases" "2.4.3" + "@docusaurus/types" "2.4.3" + "@docusaurus/utils" "2.4.3" + "@docusaurus/utils-validation" "2.4.3" "@types/react-router-config" "^5.0.6" combine-promises "^1.1.0" fs-extra "^10.1.0" @@ -1695,95 +1695,95 @@ utility-types "^3.10.0" webpack "^5.73.0" -"@docusaurus/plugin-content-pages@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/plugin-content-pages/-/plugin-content-pages-2.3.1.tgz#f534a37862be5b3f2ba5b150458d7527646b6f39" - integrity sha512-E80UL6hvKm5VVw8Ka8YaVDtO6kWWDVUK4fffGvkpQ/AJQDOg99LwOXKujPoICC22nUFTsZ2Hp70XvpezCsFQaA== - dependencies: - "@docusaurus/core" "2.3.1" - "@docusaurus/mdx-loader" "2.3.1" - "@docusaurus/types" "2.3.1" - "@docusaurus/utils" "2.3.1" - "@docusaurus/utils-validation" "2.3.1" +"@docusaurus/plugin-content-pages@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/plugin-content-pages/-/plugin-content-pages-2.4.3.tgz#7f285e718b53da8c8d0101e70840c75b9c0a1ac0" + integrity sha512-txtDVz7y3zGk67q0HjG0gRttVPodkHqE0bpJ+7dOaTH40CQFLSh7+aBeGnPOTl+oCPG+hxkim4SndqPqXjQ8Bg== + dependencies: + "@docusaurus/core" "2.4.3" + "@docusaurus/mdx-loader" "2.4.3" + "@docusaurus/types" "2.4.3" + "@docusaurus/utils" "2.4.3" + "@docusaurus/utils-validation" "2.4.3" fs-extra "^10.1.0" tslib "^2.4.0" webpack "^5.73.0" -"@docusaurus/plugin-debug@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/plugin-debug/-/plugin-debug-2.3.1.tgz#26fef904713e148f6dee44957506280f8b7853bb" - integrity sha512-Ujpml1Ppg4geB/2hyu2diWnO49az9U2bxM9Shen7b6qVcyFisNJTkVG2ocvLC7wM1efTJcUhBO6zAku2vKJGMw== +"@docusaurus/plugin-debug@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/plugin-debug/-/plugin-debug-2.4.3.tgz#2f90eb0c9286a9f225444e3a88315676fe02c245" + integrity sha512-LkUbuq3zCmINlFb+gAd4ZvYr+bPAzMC0hwND4F7V9bZ852dCX8YoWyovVUBKq4er1XsOwSQaHmNGtObtn8Av8Q== dependencies: - "@docusaurus/core" "2.3.1" - "@docusaurus/types" "2.3.1" - "@docusaurus/utils" "2.3.1" + "@docusaurus/core" "2.4.3" + "@docusaurus/types" "2.4.3" + "@docusaurus/utils" "2.4.3" fs-extra "^10.1.0" react-json-view "^1.21.3" tslib "^2.4.0" -"@docusaurus/plugin-google-analytics@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/plugin-google-analytics/-/plugin-google-analytics-2.3.1.tgz#e2e7db4cf6a7063e8ba5e128d4e413f4d6a0c862" - integrity sha512-OHip0GQxKOFU8n7gkt3TM4HOYTXPCFDjqKbMClDD3KaDnyTuMp/Zvd9HSr770lLEscgPWIvzhJByRAClqsUWiQ== +"@docusaurus/plugin-google-analytics@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/plugin-google-analytics/-/plugin-google-analytics-2.4.3.tgz#0d19993136ade6f7a7741251b4f617400d92ab45" + integrity sha512-KzBV3k8lDkWOhg/oYGxlK5o9bOwX7KpPc/FTWoB+SfKhlHfhq7qcQdMi1elAaVEIop8tgK6gD1E58Q+XC6otSQ== dependencies: - "@docusaurus/core" "2.3.1" - "@docusaurus/types" "2.3.1" - "@docusaurus/utils-validation" "2.3.1" + "@docusaurus/core" "2.4.3" + "@docusaurus/types" "2.4.3" + "@docusaurus/utils-validation" "2.4.3" tslib "^2.4.0" -"@docusaurus/plugin-google-gtag@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/plugin-google-gtag/-/plugin-google-gtag-2.3.1.tgz#b8da54a60c0a50aca609c3643faef78cb4f247a0" - integrity sha512-uXtDhfu4+Hm+oqWUySr3DNI5cWC/rmP6XJyAk83Heor3dFjZqDwCbkX8yWPywkRiWev3Dk/rVF8lEn0vIGVocA== +"@docusaurus/plugin-google-gtag@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/plugin-google-gtag/-/plugin-google-gtag-2.4.3.tgz#e1a80b0696771b488562e5b60eff21c9932d9e1c" + integrity sha512-5FMg0rT7sDy4i9AGsvJC71MQrqQZwgLNdDetLEGDHLfSHLvJhQbTCUGbGXknUgWXQJckcV/AILYeJy+HhxeIFA== dependencies: - "@docusaurus/core" "2.3.1" - "@docusaurus/types" "2.3.1" - "@docusaurus/utils-validation" "2.3.1" + "@docusaurus/core" "2.4.3" + "@docusaurus/types" "2.4.3" + "@docusaurus/utils-validation" "2.4.3" tslib "^2.4.0" -"@docusaurus/plugin-google-tag-manager@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/plugin-google-tag-manager/-/plugin-google-tag-manager-2.3.1.tgz#f19bc01cc784fa4734187c5bc637f0574857e15d" - integrity sha512-Ww2BPEYSqg8q8tJdLYPFFM3FMDBCVhEM4UUqKzJaiRMx3NEoly3qqDRAoRDGdIhlC//Rf0iJV9cWAoq2m6k3sw== +"@docusaurus/plugin-google-tag-manager@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/plugin-google-tag-manager/-/plugin-google-tag-manager-2.4.3.tgz#e41fbf79b0ffc2de1cc4013eb77798cff0ad98e3" + integrity sha512-1jTzp71yDGuQiX9Bi0pVp3alArV0LSnHXempvQTxwCGAEzUWWaBg4d8pocAlTpbP9aULQQqhgzrs8hgTRPOM0A== dependencies: - "@docusaurus/core" "2.3.1" - "@docusaurus/types" "2.3.1" - "@docusaurus/utils-validation" "2.3.1" + "@docusaurus/core" "2.4.3" + "@docusaurus/types" "2.4.3" + "@docusaurus/utils-validation" "2.4.3" tslib "^2.4.0" -"@docusaurus/plugin-sitemap@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/plugin-sitemap/-/plugin-sitemap-2.3.1.tgz#f526ab517ca63b7a3460d585876f5952cb908aa0" - integrity sha512-8Yxile/v6QGYV9vgFiYL+8d2N4z4Er3pSHsrD08c5XI8bUXxTppMwjarDUTH/TRTfgAWotRbhJ6WZLyajLpozA== - dependencies: - "@docusaurus/core" "2.3.1" - "@docusaurus/logger" "2.3.1" - "@docusaurus/types" "2.3.1" - "@docusaurus/utils" "2.3.1" - "@docusaurus/utils-common" "2.3.1" - "@docusaurus/utils-validation" "2.3.1" +"@docusaurus/plugin-sitemap@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/plugin-sitemap/-/plugin-sitemap-2.4.3.tgz#1b3930900a8f89670ce7e8f83fb4730cd3298c32" + integrity sha512-LRQYrK1oH1rNfr4YvWBmRzTL0LN9UAPxBbghgeFRBm5yloF6P+zv1tm2pe2hQTX/QP5bSKdnajCvfnScgKXMZQ== + dependencies: + "@docusaurus/core" "2.4.3" + "@docusaurus/logger" "2.4.3" + "@docusaurus/types" "2.4.3" + "@docusaurus/utils" "2.4.3" + "@docusaurus/utils-common" "2.4.3" + "@docusaurus/utils-validation" "2.4.3" fs-extra "^10.1.0" sitemap "^7.1.1" tslib "^2.4.0" -"@docusaurus/preset-classic@^2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/preset-classic/-/preset-classic-2.3.1.tgz#f0193f06093eb55cafef66bd1ad9e0d33198bf95" - integrity sha512-OQ5W0AHyfdUk0IldwJ3BlnZ1EqoJuu2L2BMhqLbqwNWdkmzmSUvlFLH1Pe7CZSQgB2YUUC/DnmjbPKk/qQD0lQ== - dependencies: - "@docusaurus/core" "2.3.1" - "@docusaurus/plugin-content-blog" "2.3.1" - "@docusaurus/plugin-content-docs" "2.3.1" - "@docusaurus/plugin-content-pages" "2.3.1" - "@docusaurus/plugin-debug" "2.3.1" - "@docusaurus/plugin-google-analytics" "2.3.1" - "@docusaurus/plugin-google-gtag" "2.3.1" - "@docusaurus/plugin-google-tag-manager" "2.3.1" - "@docusaurus/plugin-sitemap" "2.3.1" - "@docusaurus/theme-classic" "2.3.1" - "@docusaurus/theme-common" "2.3.1" - "@docusaurus/theme-search-algolia" "2.3.1" - "@docusaurus/types" "2.3.1" +"@docusaurus/preset-classic@^2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/preset-classic/-/preset-classic-2.4.3.tgz#074c57ebf29fa43d23bd1c8ce691226f542bc262" + integrity sha512-tRyMliepY11Ym6hB1rAFSNGwQDpmszvWYJvlK1E+md4SW8i6ylNHtpZjaYFff9Mdk3i/Pg8ItQq9P0daOJAvQw== + dependencies: + "@docusaurus/core" "2.4.3" + "@docusaurus/plugin-content-blog" "2.4.3" + "@docusaurus/plugin-content-docs" "2.4.3" + "@docusaurus/plugin-content-pages" "2.4.3" + "@docusaurus/plugin-debug" "2.4.3" + "@docusaurus/plugin-google-analytics" "2.4.3" + "@docusaurus/plugin-google-gtag" "2.4.3" + "@docusaurus/plugin-google-tag-manager" "2.4.3" + "@docusaurus/plugin-sitemap" "2.4.3" + "@docusaurus/theme-classic" "2.4.3" + "@docusaurus/theme-common" "2.4.3" + "@docusaurus/theme-search-algolia" "2.4.3" + "@docusaurus/types" "2.4.3" "@docusaurus/react-loadable@5.5.2", "react-loadable@npm:@docusaurus/react-loadable@5.5.2": version "5.5.2" @@ -1793,27 +1793,27 @@ "@types/react" "*" prop-types "^15.6.2" -"@docusaurus/theme-classic@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/theme-classic/-/theme-classic-2.3.1.tgz#8e6e194236e702c0d4e8d7b7cbb6886ae456e598" - integrity sha512-SelSIDvyttb7ZYHj8vEUhqykhAqfOPKk+uP0z85jH72IMC58e7O8DIlcAeBv+CWsLbNIl9/Hcg71X0jazuxJug== - dependencies: - "@docusaurus/core" "2.3.1" - "@docusaurus/mdx-loader" "2.3.1" - "@docusaurus/module-type-aliases" "2.3.1" - "@docusaurus/plugin-content-blog" "2.3.1" - "@docusaurus/plugin-content-docs" "2.3.1" - "@docusaurus/plugin-content-pages" "2.3.1" - "@docusaurus/theme-common" "2.3.1" - "@docusaurus/theme-translations" "2.3.1" - "@docusaurus/types" "2.3.1" - "@docusaurus/utils" "2.3.1" - "@docusaurus/utils-common" "2.3.1" - "@docusaurus/utils-validation" "2.3.1" +"@docusaurus/theme-classic@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/theme-classic/-/theme-classic-2.4.3.tgz#29360f2eb03a0e1686eb19668633ef313970ee8f" + integrity sha512-QKRAJPSGPfDY2yCiPMIVyr+MqwZCIV2lxNzqbyUW0YkrlmdzzP3WuQJPMGLCjWgQp/5c9kpWMvMxjhpZx1R32Q== + dependencies: + "@docusaurus/core" "2.4.3" + "@docusaurus/mdx-loader" "2.4.3" + "@docusaurus/module-type-aliases" "2.4.3" + "@docusaurus/plugin-content-blog" "2.4.3" + "@docusaurus/plugin-content-docs" "2.4.3" + "@docusaurus/plugin-content-pages" "2.4.3" + "@docusaurus/theme-common" "2.4.3" + "@docusaurus/theme-translations" "2.4.3" + "@docusaurus/types" "2.4.3" + "@docusaurus/utils" "2.4.3" + "@docusaurus/utils-common" "2.4.3" + "@docusaurus/utils-validation" "2.4.3" "@mdx-js/react" "^1.6.22" clsx "^1.2.1" copy-text-to-clipboard "^3.0.1" - infima "0.2.0-alpha.42" + infima "0.2.0-alpha.43" lodash "^4.17.21" nprogress "^0.2.0" postcss "^8.4.14" @@ -1824,17 +1824,18 @@ tslib "^2.4.0" utility-types "^3.10.0" -"@docusaurus/theme-common@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/theme-common/-/theme-common-2.3.1.tgz#82f52d80226efef8c4418c4eacfc5051aa215f7f" - integrity sha512-RYmYl2OR2biO+yhmW1aS5FyEvnrItPINa+0U2dMxcHpah8reSCjQ9eJGRmAgkZFchV1+aIQzXOI1K7LCW38O0g== - dependencies: - "@docusaurus/mdx-loader" "2.3.1" - "@docusaurus/module-type-aliases" "2.3.1" - "@docusaurus/plugin-content-blog" "2.3.1" - "@docusaurus/plugin-content-docs" "2.3.1" - "@docusaurus/plugin-content-pages" "2.3.1" - "@docusaurus/utils" "2.3.1" +"@docusaurus/theme-common@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/theme-common/-/theme-common-2.4.3.tgz#bb31d70b6b67d0bdef9baa343192dcec49946a2e" + integrity sha512-7KaDJBXKBVGXw5WOVt84FtN8czGWhM0lbyWEZXGp8AFfL6sZQfRTluFp4QriR97qwzSyOfQb+nzcDZZU4tezUw== + dependencies: + "@docusaurus/mdx-loader" "2.4.3" + "@docusaurus/module-type-aliases" "2.4.3" + "@docusaurus/plugin-content-blog" "2.4.3" + "@docusaurus/plugin-content-docs" "2.4.3" + "@docusaurus/plugin-content-pages" "2.4.3" + "@docusaurus/utils" "2.4.3" + "@docusaurus/utils-common" "2.4.3" "@types/history" "^4.7.11" "@types/react" "*" "@types/react-router-config" "*" @@ -1845,19 +1846,19 @@ use-sync-external-store "^1.2.0" utility-types "^3.10.0" -"@docusaurus/theme-search-algolia@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/theme-search-algolia/-/theme-search-algolia-2.3.1.tgz#d587b40913119e9287d14670e277b933d8f453f0" - integrity sha512-JdHaRqRuH1X++g5fEMLnq7OtULSGQdrs9AbhcWRQ428ZB8/HOiaN6mj3hzHvcD3DFgu7koIVtWPQnvnN7iwzHA== +"@docusaurus/theme-search-algolia@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/theme-search-algolia/-/theme-search-algolia-2.4.3.tgz#32d4cbefc3deba4112068fbdb0bde11ac51ece53" + integrity sha512-jziq4f6YVUB5hZOB85ELATwnxBz/RmSLD3ksGQOLDPKVzat4pmI8tddNWtriPpxR04BNT+ZfpPUMFkNFetSW1Q== dependencies: "@docsearch/react" "^3.1.1" - "@docusaurus/core" "2.3.1" - "@docusaurus/logger" "2.3.1" - "@docusaurus/plugin-content-docs" "2.3.1" - "@docusaurus/theme-common" "2.3.1" - "@docusaurus/theme-translations" "2.3.1" - "@docusaurus/utils" "2.3.1" - "@docusaurus/utils-validation" "2.3.1" + "@docusaurus/core" "2.4.3" + "@docusaurus/logger" "2.4.3" + "@docusaurus/plugin-content-docs" "2.4.3" + "@docusaurus/theme-common" "2.4.3" + "@docusaurus/theme-translations" "2.4.3" + "@docusaurus/utils" "2.4.3" + "@docusaurus/utils-validation" "2.4.3" algoliasearch "^4.13.1" algoliasearch-helper "^3.10.0" clsx "^1.2.1" @@ -1867,18 +1868,18 @@ tslib "^2.4.0" utility-types "^3.10.0" -"@docusaurus/theme-translations@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/theme-translations/-/theme-translations-2.3.1.tgz#b2b1ecc00a737881b5bfabc19f90b20f0fe02bb3" - integrity sha512-BsBZzAewJabVhoGG1Ij2u4pMS3MPW6gZ6sS4pc+Y7czevRpzxoFNJXRtQDVGe7mOpv/MmRmqg4owDK+lcOTCVQ== +"@docusaurus/theme-translations@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/theme-translations/-/theme-translations-2.4.3.tgz#91ac73fc49b8c652b7a54e88b679af57d6ac6102" + integrity sha512-H4D+lbZbjbKNS/Zw1Lel64PioUAIT3cLYYJLUf3KkuO/oc9e0QCVhIYVtUI2SfBCF2NNdlyhBDQEEMygsCedIg== dependencies: fs-extra "^10.1.0" tslib "^2.4.0" -"@docusaurus/types@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/types/-/types-2.3.1.tgz#785ade2e0f4e35e1eb7fb0d04c27d11c3991a2e8" - integrity sha512-PREbIRhTaNNY042qmfSE372Jb7djZt+oVTZkoqHJ8eff8vOIc2zqqDqBVc5BhOfpZGPTrE078yy/torUEZy08A== +"@docusaurus/types@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/types/-/types-2.4.3.tgz#4aead281ca09f721b3c0a9b926818450cfa3db31" + integrity sha512-W6zNLGQqfrp/EoPD0bhb9n7OobP+RHpmvVzpA+Z/IuU3Q63njJM24hmT0GYboovWcDtFmnIJC9wcyx4RVPQscw== dependencies: "@types/history" "^4.7.11" "@types/react" "*" @@ -1889,30 +1890,30 @@ webpack "^5.73.0" webpack-merge "^5.8.0" -"@docusaurus/utils-common@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/utils-common/-/utils-common-2.3.1.tgz#1abe66846eb641547e4964d44f3011938e58e50b" - integrity sha512-pVlRpXkdNcxmKNxAaB1ya2hfCEvVsLDp2joeM6K6uv55Oc5nVIqgyYSgSNKZyMdw66NnvMfsu0RBylcwZQKo9A== +"@docusaurus/utils-common@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/utils-common/-/utils-common-2.4.3.tgz#30656c39ef1ce7e002af7ba39ea08330f58efcfb" + integrity sha512-/jascp4GbLQCPVmcGkPzEQjNaAk3ADVfMtudk49Ggb+131B1WDD6HqlSmDf8MxGdy7Dja2gc+StHf01kiWoTDQ== dependencies: tslib "^2.4.0" -"@docusaurus/utils-validation@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/utils-validation/-/utils-validation-2.3.1.tgz#b65c718ba9b84b7a891bccf5ac6d19b57ee7d887" - integrity sha512-7n0208IG3k1HVTByMHlZoIDjjOFC8sbViHVXJx0r3Q+3Ezrx+VQ1RZ/zjNn6lT+QBCRCXlnlaoJ8ug4HIVgQ3w== +"@docusaurus/utils-validation@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/utils-validation/-/utils-validation-2.4.3.tgz#8122c394feef3e96c73f6433987837ec206a63fb" + integrity sha512-G2+Vt3WR5E/9drAobP+hhZQMaswRwDlp6qOMi7o7ZypB+VO7N//DZWhZEwhcRGepMDJGQEwtPv7UxtYwPL9PBw== dependencies: - "@docusaurus/logger" "2.3.1" - "@docusaurus/utils" "2.3.1" + "@docusaurus/logger" "2.4.3" + "@docusaurus/utils" "2.4.3" joi "^17.6.0" js-yaml "^4.1.0" tslib "^2.4.0" -"@docusaurus/utils@2.3.1": - version "2.3.1" - resolved "https://registry.yarnpkg.com/@docusaurus/utils/-/utils-2.3.1.tgz#24b9cae3a23b1e6dc88f95c45722c7e82727b032" - integrity sha512-9WcQROCV0MmrpOQDXDGhtGMd52DHpSFbKLfkyaYumzbTstrbA5pPOtiGtxK1nqUHkiIv8UwexS54p0Vod2I1lg== +"@docusaurus/utils@2.4.3": + version "2.4.3" + resolved "https://registry.yarnpkg.com/@docusaurus/utils/-/utils-2.4.3.tgz#52b000d989380a2125831b84e3a7327bef471e89" + integrity sha512-fKcXsjrD86Smxv8Pt0TBFqYieZZCPh4cbf9oszUq/AMhZn3ujwpKaVYZACPX8mmjtYx0JOgNx52CREBfiGQB4A== dependencies: - "@docusaurus/logger" "2.3.1" + "@docusaurus/logger" "2.4.3" "@svgr/webpack" "^6.2.1" escape-string-regexp "^4.0.0" file-loader "^6.2.0" @@ -4938,10 +4939,10 @@ indexes-of@^1.0.1: resolved "https://registry.npmjs.org/indexes-of/-/indexes-of-1.0.1.tgz" integrity sha1-8w9xbI4r00bHtn0985FVZqfAVgc= -infima@0.2.0-alpha.42: - version "0.2.0-alpha.42" - resolved "https://registry.yarnpkg.com/infima/-/infima-0.2.0-alpha.42.tgz#f6e86a655ad40877c6b4d11b2ede681eb5470aa5" - integrity sha512-ift8OXNbQQwtbIt6z16KnSWP7uJ/SysSMFI4F87MNRTicypfl4Pv3E2OGVv6N3nSZFJvA8imYulCBS64iyHYww== +infima@0.2.0-alpha.43: + version "0.2.0-alpha.43" + resolved "https://registry.yarnpkg.com/infima/-/infima-0.2.0-alpha.43.tgz#f7aa1d7b30b6c08afef441c726bac6150228cbe0" + integrity sha512-2uw57LvUqW0rK/SWYnd/2rRfxNA5DDNOh33jxF7fy46VWoNhGxiUQyVZHbBMjQ33mQem0cjdDVwgWVAmlRfgyQ== inflight@^1.0.4: version "1.0.6"