Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions packages/docs-gesture-handler/docs/components/buttons.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ This type of button component is ideal for use with rectangular elements or cont
underlayColor?: string;
```

Background color that will be dimmed when button is in active state.
Background color that will be dimmed when the button is in an active state.

<HeaderWithBadges platforms={['iOS']}>
### activeOpacity
Expand All @@ -148,7 +148,7 @@ Background color that will be dimmed when button is in active state.
activeOpacity?: number;
```

Opacity applied to the underlay when button is in active state.
Opacity applied to the underlay when the button is in an active state.

## BorderlessButton

Expand Down Expand Up @@ -188,27 +188,27 @@ const AccessibleButton = () => (

## 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 design concepts.
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 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.
This library allows the use of native components with native feedback in adequate situations.

If you do not wish to implement custom design approach, [`RectButton`](#rectbutton) and [`BorderlessButton`](#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`](#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.
If you do not wish to implement a custom design approach, [`RectButton`](#rectbutton) and [`BorderlessButton`](#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`](#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`](#rectbutton). It changes opacity on click and additionally supports a [ripple effect](#ripplecolor-android-only) on Android.
If you have a list with clickable items or have an action button that needs to display as a separate UI block (vs being inlined in a text) you should use [`RectButton`](#rectbutton). It changes opacity on click and additionally supports a [ripple effect](#ripplecolor-android-only) on Android.

<GifGallery>
<img src={useBaseUrl('gifs/androidsettings.gif')} width="280" />
<img src={useBaseUrl('gifs/iossettings.gif')} width="280" />
</GifGallery>

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.
To determine the emphasis of a button, it's vital to use a 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.

<GifGallery>
<img src={useBaseUrl('gifs/androidbutton.gif')} width="280" />
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ export enum DrawerKeyboardDismissMode {
}
`}/>

Determines if system keyboard should be closed upon dragging the drawer.
Determines if the system keyboard should be closed upon dragging the drawer.

### animationSpeed

Expand Down Expand Up @@ -250,7 +250,7 @@ Either a component rendered in the content view or a function. If `children` is
enableContextMenu: boolean;
```

Specifies whether context menu should be enabled after clicking on underlying view with right mouse button. Default value is set to `false` if [`MouseButton.RIGHT`](#mousebutton-web--android-only) is specified.
Specifies whether the context menu should be enabled after clicking on the underlying view with the right mouse button. Default value is set to `false` if [`MouseButton.RIGHT`](#mousebutton-web--android-only) is specified.

<HeaderWithBadges platforms={['web']}>
### userSelect
Expand All @@ -260,7 +260,7 @@ Specifies whether context menu should be enabled after clicking on underlying vi
userSelect: 'none' | 'auto' | 'text';
```

This parameter allows to specify which `userSelect` property should be applied to underlying view. Default value is set to `"none"`.
This parameter allows specifying which `userSelect` property should be applied to the underlying view. Default value is set to `"none"`.

<HeaderWithBadges platforms={['web']}>
### activeCursor
Expand All @@ -270,7 +270,7 @@ This parameter allows to specify which `userSelect` property should be applied t
activeCursor: ActiveCursor;
```

This parameter allows to specify which cursor should be used when gesture activates. Supports all [CSS cursor values](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/cursor#keyword) (e.g. `"grab"`, `"zoom-in"`). Default value is set to `"auto"`.
This parameter allows specifying which cursor should be used when the gesture activates. Supports all [CSS cursor values](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/cursor#keyword) (e.g. `"grab"`, `"zoom-in"`). Default value is set to `"auto"`.

## Drawer ref methods

Expand All @@ -295,15 +295,15 @@ export type DrawerMovementOption = {
openDrawer: (options?: DrawerMovementOption) => void;
```

Allows to manually open the drawer.
Allows manually opening the drawer.

### closeDrawer

```ts
closeDrawer: (options?: DrawerMovementOption) => void;
```

Allows to manually close the drawer.
Allows manually closing the drawer.

## Example

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -258,7 +258,7 @@ Enables two-finger gestures on supported devices, for example iPads with trackpa
enabled: boolean;
```

Indicates whether `ReanimatedSwipeable` should be analyzing stream of touch events or not. Defaults to `true`.
Indicates whether `ReanimatedSwipeable` should be analyzing the stream of touch events or not. Defaults to `true`.

### testID

Expand Down Expand Up @@ -295,7 +295,7 @@ type HitSlop =
`}/>

This parameter enables control over what part of the connected view area can be used to begin 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.
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.
See [hitSlop section](/docs/gestures/use-pan-gesture#hitslop) in `Pan` gesture for more details.

## Swipeable ref methods
Expand Down
9 changes: 4 additions & 5 deletions packages/docs-gesture-handler/docs/components/touchables.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ sidebar_label: Touchables
Touchables will be removed in the future version of Gesture Handler. Use [`Pressable`](/docs/components/pressable) instead.
:::

Gesture Handler library provides an implementation of RN's touchable components that are based on [native buttons](buttons.mdx) and does not rely on JS responder system utilized by RN. Our touchable implementation follows the same API and aims to be a drop-in replacement for touchables available in React Native.
Gesture Handler library provides an implementation of RN's touchable components that are based on [native buttons](buttons.mdx) and do not rely on the 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:

Expand All @@ -17,15 +17,14 @@ React Native's touchables API can be found here:
- [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.
All major touchable properties (except for `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.
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 the 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.
Our intention was to make the 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 the library from which you import touchable components.

:::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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ Called when a handler begins to recognize gestures. If `onBegin` was called, it
onActivate: (event: GestureEvent<HandlerData>) => void
```

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

### onUpdate

Expand All @@ -59,15 +59,15 @@ Called each time a pointer tracked by the gesture changes state, typically due t
onDeactivate: (event: GestureEvent<HandlerData>, didSucceed: boolean) => void
```

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

### onFinalize

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

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

### onTouchesDown

Expand Down Expand Up @@ -190,7 +190,7 @@ export type TouchData = {

`TouchData` contains information about a single touch.

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

- `x` - X coordinate of the current position of the touch relative to the view attached to the [`GestureDetector`](/docs/fundamentals/gesture-detectors#gesture-detector). Expressed in point units.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ RNGH3 simplifies gesture interaction through dedicated composition hooks and con

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.

For example, lets say that you have a component that you want to make draggable but you also want to show additional options on long press. Presumably you would not want the component to move after the long press activates. You can accomplish this using `useCompetingGestures`:
For example, let's say that you have a component that you want to make draggable but you also want to show additional options on long press. Presumably you would not want the component to move after the long press activates. You can accomplish this using `useCompetingGestures`:

<CollapsibleCode
label="Show full example"
Expand All @@ -39,7 +39,7 @@ src={Competing}/>

All of the provided gestures can activate at the same time. Activation of one will not cancel the other.

For example, if you want to make a gallery app, you might want user to be able to zoom, rotate and pan around photos. You can do it with `useSimultaneousGestures`:
For example, if you want to make a gallery app, you might want the user to be able to zoom, rotate and pan around photos. You can do it with `useSimultaneousGestures`:

> Note: the `useSharedValue` and `useAnimatedStyle` are part of [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/).

Expand All @@ -51,7 +51,7 @@ src={Simultaneous}/>

### useExclusiveGestures

Only one of the provided gestures can become active. Priority is determined by the order of the aguments, where the first gesture has the highest priority, and the last has the lowest. A gesture can activate only after all higher-priority gestures before it have failed.
Only one of the provided gestures can become active. Priority is determined by the order of the arguments, where the first gesture has the highest priority, and the last has the lowest. A gesture can activate only after all higher-priority gestures before it have failed.

For example, if you want to make a component that responds to single tap as well as to a double tap, you can accomplish that using `useExclusiveGestures`:

Expand All @@ -66,7 +66,7 @@ src={Exclusive}/>

### requireToFail

`requireToFail` allows to delay activation of the handler until all handlers passed as arguments to this method fail (or don't begin at all).
`requireToFail` allows delaying activation of the handler until all handlers passed as arguments to this method fail (or don't begin at all).

For example, you may want to have two nested components, both of them can be tapped by the user to trigger different actions: outer view requires one tap, but the inner one requires 2 taps. If you don't want the first tap on the inner view to activate the outer handler, you must make the outer gesture wait until the inner one fails:

Expand All @@ -78,7 +78,7 @@ src={RequireToFail}/>

### block

`block` works similarly to `requireToFail` but the direction of the relation is reversed - instead of being one-to-many relation, it's many-to-one. It's especially useful for making lists where the `ScrollView` component needs to wait for every gesture underneath it. All that's required to do is to pass a ref, for example:
`block` works similarly to `requireToFail` but the direction of the relation is reversed - instead of being a one-to-many relation, it's many-to-one. It's especially useful for making lists where the `ScrollView` component needs to wait for every gesture underneath it. All that's required to do is to pass a ref, for example:

<CollapsibleCode
label="Show full example"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,7 @@ A gesture object containing the configuration and callbacks. Can be any of the b
userSelect: 'none' | 'auto' | 'text';
```

This parameter allows to specify which `userSelect` property should be applied to underlying view. Default value is set to `"none"`.
This parameter allows specifying which `userSelect` property should be applied to the underlying view. Default value is set to `"none"`.

<HeaderWithBadges platforms={['web']}>
### touchAction
Expand All @@ -208,7 +208,7 @@ This parameter allows to specify which `userSelect` property should be applied t
touchAction: TouchAction;
```

This parameter allows to specify which `touchAction` property should be applied to underlying view. Supports all CSS [touch-action](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/touch-action) values. Default value is set to `"none"`.
This parameter allows specifying which `touchAction` property should be applied to the underlying view. Supports all CSS [touch-action](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/touch-action) values. Default value is set to `"none"`.

<HeaderWithBadges platforms={['web']}>
### enableContextMenu
Expand All @@ -218,4 +218,4 @@ This parameter allows to specify which `touchAction` property should be applied
enableContextMenu: boolean;
```

Specifies whether context menu should be enabled after clicking on underlying view with right mouse button. Default value is set to `false`.
Specifies whether the context menu should be enabled after clicking on the underlying view with the right mouse button. Default value is set to `false`.
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ export function CustomModal({ children, ...rest }) {
}
```

Gesture Handler on Android is implemented in Kotlin. If you need to set a specific Kotlin version to be used by the library, set the `kotlinVersion` ext property in `android/build.gradle` file and RNGH will use that version:
Gesture Handler on Android is implemented in Kotlin. If you need to set a specific Kotlin version to be used by the library, set the `kotlinVersion` ext property in the `android/build.gradle` file and RNGH will use that version:

```groovy
buildscript {
Expand Down
Loading
Loading