Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Deprecate RNGestureHandlerEnabledRootView #1605

Merged
merged 1 commit into from
Aug 27, 2021
Merged

Deprecate RNGestureHandlerEnabledRootView #1605

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
1 change: 1 addition & 0 deletions android/src/main/java/com/swmansion/gesturehandler/react/RNGestureHandlerEnabledRootView.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import android.view.MotionEvent
import com.facebook.react.ReactInstanceManager
import com.facebook.react.ReactRootView

@Deprecated(message = "Use <GestureHandlerRootView /> component instead. Check gesture handler installation instructions in documentation for more information.")
class RNGestureHandlerEnabledRootView : ReactRootView {
private lateinit var _reactInstanceManager: ReactInstanceManager
private var gestureRootHelper: RNGestureHandlerRootHelper? = null
Expand Down
139 changes: 70 additions & 69 deletions docs/docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,17 +19,7 @@ In a nutshell, the library provides:

## Installation

### 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.

#### Requirements
### Requirements

| version | `react-native` version |
| --------- | ---------------------- |
Expand All @@ -42,7 +32,19 @@ Read more on that here https://github.com/mikehardy/jetifier#to-reverse-jetify--

Note that if you wish to use [`React.createRef()`](https://reactjs.org/docs/refs-and-the-dom.html) support for [interactions](interactions.md) you need to use v16.3 of [React](https://reactjs.org/)

#### JS
### 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`:

Expand All @@ -56,6 +58,27 @@ or with `npm` if you prefer:
npm install --save react-native-gesture-handler
```

After installation, wrap your entry point with `<GestureHandlerRootView>` or
`gestureHandlerRootHOC`.

For example:

```js
export default function App() {
return <GestureHandlerRootView>{/* content */}</GestureHandlerRootView>;
}
```

:::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.
Expand All @@ -64,13 +87,22 @@ npm install --save react-native-gesture-handler
react-native link react-native-gesture-handler
```

#### Android
### Android

Follow the steps below:

If you use one of the _native navigation libraries_ (e.g. [wix/react-native-navigation](https://github.com/wix/react-native-navigation)), you should follow [this separate guide](#with-wixreact-native-navigation) to get gesture handler library set up on Android. Ignore the rest of this step – it only applies to RN apps that use a standard Android project layout.
If you use one of the _native navigation libraries_ (e.g.
[wix/react-native-navigation](https://github.com/wix/react-native-navigation)),
you should follow [this separate guide](#with-wixreact-native-navigation) to get
gesture handler library set up on Android. Ignore the rest of this step – it
only applies to RN apps that use a standard Android project layout.

##### Updating `MainActivity.java`
#### Updating `MainActivity.java`

:::caution
From version 2.0.0 this step isn't needed. You should use
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this reanimated v2?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nope, the not-yet-released RNGH 2.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But thanks for reminding us that we should version our docs.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

cool, is their rc candidate to test v2?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not yet, we don't know if we want to do rc release. You can pack master if you want to, though.

`<GestureHandlerRootView />` component instead.
:::

Update your `MainActivity.java` file (or wherever you create an instance of `ReactActivityDelegate`), so that it overrides the method responsible for creating `ReactRootView` instance and then use the root view wrapper provided by this library. Do not forget to import `ReactActivityDelegate`, `ReactRootView`, and `RNGestureHandlerEnabledRootView`:

Expand Down Expand Up @@ -101,33 +133,47 @@ public class MainActivity extends ReactActivity {
}
```

##### Running jetifier
#### Usage with modals on Android

> **Important:** You only need to do this step if you're on React Native 0.60 or greater.
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).

React Native 0.60 migrated from Support Library to AndroidX. React Native Gesture Handler is not yet compatible with AndroidX.
For example:

Make sure to [update the React Native CLI to the latest version](https://github.com/react-native-community/cli/tree/master#updating-the-cli) which runs [`jetifier`](https://www.npmjs.com/package/jetifier) – the AndroidX migration tool – during the `run-android` command.
```js
const ExampleWithHoc = gestureHandlerRootHOC(() => (
<View>
<DraggableBox />
</View>
);
);

export default function Example() {
return (
<Modal>
<ExampleWithHoc />
</Modal>
);
}
```

#### iOS
### 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:

```sh
```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';
```

Now you're all set. Run your app with `react-native run-android` or `react-native run-ios`.

### 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 follow a different setup for your Android app to work properly. The reason is that both native navigation libraries and Gesture Handler library need to use their own special subclasses of `ReactRootView`.
Expand Down Expand Up @@ -166,51 +212,6 @@ You can check out [this example project](https://github.com/henrikra/nativeNavig

Remember that you need to wrap each screen that you use in your app with `gestureHandlerRootHOC` as with native navigation libraries each screen maps to a separate root view. It will not be enough to wrap the main screen only.

### 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.
In order to make it workable, components need to be wrapped with `gestureHandlerRootHOC` (it's no-op on iOS and web).

E.g.

```js
const ExampleWithHoc = gestureHandlerRootHOC(function GestureExample() {
return (
<View>
<DraggableBox />
</View>
);
});

export default function Example() {
return (
<Modal animationType="slide" transparent={false}>
<ExampleWithHoc />
</Modal>
);
}
```

### For library authors

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 in `MainActivity.java` for the user.

```js
import { GestureHandlerRootView } from 'react-native-gesture-handler';

export default MyComponent() {
return (
<GestureHandlerRootView>
{/* content */}
</GestureHandlerRootView>
)
}
```

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.

### Testing

In order to load mocks provided by the library add following to your jest config in `package.json`:
Expand Down