Skip to content

Commit f6cc7b3

Browse files
sgnyMoOx
sgny
authored and
MoOx
committed
Add documentation for PanResponder API (#513)
1 parent fff55d6 commit f6cc7b3

1 file changed

Lines changed: 274 additions & 36 deletions

File tree

‎reason-react-native/src/apis/PanResponder.md‎

Lines changed: 274 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,42 @@
11
---
2-
id: apis/Packager
3-
title: Packager
4-
wip: true
2+
id: apis/PanResponder
3+
title: PanResponder
4+
officialDoc: http://facebook.github.io/react-native/docs/panresponder
55
---
66

7+
`PanResponder` allows more fine-grained control of the
8+
[_Gesture Responder System_](http://facebook.github.io/react-native/docs/gesture-responder-system),
9+
as the handlers can depend also on `gestureState`, in addition to the
10+
`Event.pressEvent` which are passed to the _Gesture Responder System_ handlers.
11+
In essence, by means of a custom `PanResponder`, _Gesture Responder System_
12+
handlers are extended to also depend upon the `gestureState`.
13+
14+
## Types
15+
16+
### `Event.pressEvent`
17+
`Event.pressEvent` is `Event.syntheticEvent(pressEventPayload)` where the
18+
`nativeEvent` key is recursively specified as:
19+
20+
```reason
21+
type pressEventPayload = {
22+
.
23+
"changedTouches": array(pressEventPayload),
24+
"force": float,
25+
"identifier": int,
26+
"locationX": float,
27+
"locationY": float,
28+
"pageX": float,
29+
"pageY": float,
30+
"target": Js.Nullable.t(float),
31+
"timestamp": float,
32+
"touches": array(pressEventPayload),
33+
}
34+
```
35+
36+
### `gestureState`
37+
`gestureState` contains additional information on the state of the \_Gesture
38+
Responder System\_
39+
740
```reason
841
type gestureState = {
942
.
@@ -17,15 +50,19 @@ type gestureState = {
1750
"vx": float,
1851
"vy": float,
1952
"numberActiveTouches": int,
20-
};
53+
}
54+
```
55+
56+
### `t`
57+
`t` is the abstract type for a `PanResponder`, which can be created by means
58+
of the `create` method, given a `config` object
2159

22-
type t;
23-
type config;
24-
type panHandlers;
25-
type callback('a) = Event.pressEvent => 'a;
60+
### `config`
61+
`config` is the abstract type for a custom `PanResponder` configuration; it
62+
can be created by means of the `config` constructor
2663

27-
[@bs.obj]
28-
external config:
64+
```reason
65+
config:
2966
(
3067
~onMoveShouldSetPanResponder: (Event.pressEvent, gestureState) => bool=?,
3168
~onMoveShouldSetPanResponderCapture: (Event.pressEvent, gestureState) =>
@@ -46,32 +83,233 @@ external config:
4683
=?,
4784
~onShouldBlockNativeResponder: (Event.pressEvent, gestureState) => bool=?,
4885
unit
49-
) =>
50-
config =
51-
"";
52-
53-
[@bs.module "react-native"] [@bs.scope "PanResponder"]
54-
external create: config => t = "";
55-
56-
[@bs.get] external panHandlers: t => panHandlers = "";
57-
58-
[@bs.get]
59-
external onMoveShouldSetResponder: panHandlers => callback(bool) = "";
60-
[@bs.get]
61-
external onMoveShouldSetResponderCapture: panHandlers => callback(bool) = "";
62-
[@bs.get]
63-
external onStartShouldSetResponder: panHandlers => callback(bool) = "";
64-
[@bs.get]
65-
external onStartShouldSetResponderCapture: panHandlers => callback(bool) = "";
66-
[@bs.get] external onResponderReject: panHandlers => callback(unit) = "";
67-
[@bs.get] external onResponderGrant: panHandlers => callback(unit) = "";
68-
[@bs.get] external onResponderRelease: panHandlers => callback(unit) = "";
69-
[@bs.get] external onResponderMove: panHandlers => callback(unit) = "";
70-
[@bs.get] external onResponderTerminate: panHandlers => callback(unit) = "";
71-
[@bs.get]
72-
external onResponderTerminationRequest: panHandlers => callback(bool) = "";
73-
[@bs.get] external onResponderStart: panHandlers => callback(unit) = "";
74-
[@bs.get] external onResponderEnd: panHandlers => callback(unit) = "";
86+
)
87+
```
88+
89+
### `panHandlers`
90+
`panHandlers` is the abstract type for `panHandlers` of a `PanResponder`,
91+
which can be accessed by means of the getter method `panHandlers`
92+
93+
### `callback('a)`
94+
`callback('a)` is the type of the usual callback function specified for each
95+
_Gesture Responder System_ handler defined as
96+
97+
```reason
98+
type callback('a) = Event.pressEvent => 'a
99+
```
100+
101+
where `'a` is either `bool` or `unit`
102+
103+
## Methods
104+
105+
### `create`
106+
`create` allows creation of a `PanResponder` given a `config`
107+
108+
```reason
109+
create(config)
110+
```
111+
112+
### `panHandlers`
113+
`panHandlers` is a getter method to access `panHandlers` within a
114+
115+
`PanResponder`
116+
117+
```reason
118+
panHandlers(t)
119+
```
120+
121+
### `onMoveShouldSetResponder`
122+
`onMoveShouldSetResponder` is a getter method to access the
123+
`onMoveShouldSetResponder` callback of a `panHandlers` object
124+
125+
```reason
126+
onMoveShouldSetResponder(panHandlers)
127+
```
128+
129+
### `onMoveShouldSetResponderCapture`
130+
`onMoveShouldSetResponderCapture` is a getter method to access the
131+
`onMoveShouldSetResponderCapture` callback of a `panHandlers` object
132+
133+
```reason
134+
onMoveShouldSetResponderCapture(panHandlers)
135+
```
136+
137+
### `onStartShouldSetResponder`
138+
`onStartShouldSetResponder` is a getter method to access the
139+
`onStartShouldSetResponder` callback of a `panHandlers` object
140+
141+
```reason
142+
onStartShouldSetResponder(panHandlers)
143+
```
144+
145+
### `onStartShouldSetResponderCapture`
146+
`onStartShouldSetResponderCapture` is a getter method to access the
147+
`onStartShouldSetResponderCapture` callback of a `panHandlers` object
148+
149+
```reason
150+
onStartShouldSetResponderCapture(panHandlers)
151+
```
152+
153+
### `onResponderReject`
154+
`onResponderReject` is a getter method to access the `onResponderReject`
155+
callback of a `panHandlers` object
75156

157+
```reason
158+
onResponderReject(panHandlers)
159+
```
160+
161+
### `onResponderGrant`
162+
`onResponderGrant` is a getter method to access the `onResponderGrant`
163+
callback of a `panHandlers` object
164+
165+
```reason
166+
onResponderGrant(panHandlers)
167+
```
168+
169+
### `onResponderRelease`
170+
`onResponderRelease` is a getter method to access the `onResponderRelease`
171+
callback of a `panHandlers` object
172+
173+
```reason
174+
onResponderRelease(panHandlers)
175+
```
176+
177+
### `onResponderMove`
178+
`onResponderMove` is a getter method to access the `onResponderMove` callback
179+
of a `panHandlers` object
180+
181+
```reason
182+
onResponderMove(panHandlers)
183+
```
184+
185+
### `onResponderTerminate`
186+
`onResponderTerminate` is a getter method to access the `onResponderTerminate`
187+
callback of a `panHandlers` object
188+
189+
```reason
190+
onResponderTerminate(panHandlers)
191+
```
192+
193+
### `onResponderStart`
194+
`onResponderStart` is a getter method to access the `onResponderStart`
195+
callback of a `panHandlers` object
196+
197+
```reason
198+
onResponderStart(panHandlers)
199+
```
200+
201+
### `onResponderTerminationRequest`
202+
`onResponderTerminationRequest` is a getter method to access the
203+
`onResponderTerminationRequest` callback of a `panHandlers` object
204+
205+
```reason
206+
onResponderTerminationRequest(panHandlers)
207+
```
208+
209+
### `onResponderEnd`
210+
`onResponderEnd` is a getter method to access the `onResponderEnd` callback of
211+
a `panHandlers` object
212+
213+
```reason
214+
onResponderEnd(panHandlers)
215+
```
216+
217+
## Example
218+
219+
As props spread is not possible with the ReasonML JSX 3 syntax, each _Gesture
220+
Responder System_ callback needs to be separately specified, with the relevant
221+
value obtained by means of the associated getter.
222+
223+
While props spread may not be available, copy-paste is probably supported by
224+
your editor...
225+
226+
```reason
227+
onMoveShouldSetResponder={
228+
panHandlers->PanResponder.onMoveShouldSetResponder
229+
}
230+
onMoveShouldSetResponderCapture={
231+
panHandlers->PanResponder.onMoveShouldSetResponderCapture
232+
}
233+
onStartShouldSetResponder={
234+
panHandlers->PanResponder.onStartShouldSetResponder
235+
}
236+
onStartShouldSetResponderCapture={
237+
panHandlers->PanResponder.onStartShouldSetResponderCapture
238+
}
239+
onResponderReject={panHandlers->PanResponder.onResponderReject}
240+
onResponderGrant={panHandlers->PanResponder.onResponderGrant}
241+
onResponderRelease={panHandlers->PanResponder.onResponderRelease}
242+
onResponderMove={panHandlers->PanResponder.onResponderMove}
243+
onResponderTerminate={panHandlers->PanResponder.onResponderTerminate}
244+
onResponderStart={panHandlers->PanResponder.onResponderStart}
245+
onResponderTerminationRequest={
246+
panHandlers->PanResponder.onResponderTerminationRequest
247+
}
248+
onResponderEnd={panHandlers->PanResponder.onResponderEnd}
249+
```
250+
251+
Then, the custom `PanResponder` can be used as below:
252+
253+
```reason
254+
open ReactNative;
255+
256+
let windowHeight = Dimensions.get(`window)##height->float_of_int;
257+
let windowWidth = Dimensions.get(`window)##width->float_of_int;
258+
259+
let containerStyle =
260+
Style.(
261+
style(
262+
~width=windowWidth->pt,
263+
~height=windowHeight->pt,
264+
~justifyContent=`center,
265+
~alignItems=`center,
266+
(),
267+
)
268+
);
269+
270+
let config =
271+
PanResponder.config(
272+
~onMoveShouldSetPanResponder=(_e, _g) => true,
273+
~onPanResponderRelease=
274+
(_e, g) =>
275+
g##dx > 0.
276+
? "You swiped right"->Js.Console.warn
277+
: "You swiped left"->Js.Console.warn,
278+
(),
279+
);
280+
281+
let panResponder = PanResponder.create(config);
282+
283+
let panHandlers = panResponder->PanResponder.panHandlers;
284+
285+
[@react.component]
286+
let make = () => {
287+
<View
288+
style=containerStyle
289+
onMoveShouldSetResponder={
290+
panHandlers->PanResponder.onMoveShouldSetResponder
291+
}
292+
onMoveShouldSetResponderCapture={
293+
panHandlers->PanResponder.onMoveShouldSetResponderCapture
294+
}
295+
onStartShouldSetResponder={
296+
panHandlers->PanResponder.onStartShouldSetResponder
297+
}
298+
onStartShouldSetResponderCapture={
299+
panHandlers->PanResponder.onStartShouldSetResponderCapture
300+
}
301+
onResponderReject={panHandlers->PanResponder.onResponderReject}
302+
onResponderGrant={panHandlers->PanResponder.onResponderGrant}
303+
onResponderRelease={panHandlers->PanResponder.onResponderRelease}
304+
onResponderMove={panHandlers->PanResponder.onResponderMove}
305+
onResponderTerminate={panHandlers->PanResponder.onResponderTerminate}
306+
onResponderStart={panHandlers->PanResponder.onResponderStart}
307+
onResponderTerminationRequest={
308+
panHandlers->PanResponder.onResponderTerminationRequest
309+
}
310+
onResponderEnd={panHandlers->PanResponder.onResponderEnd}>
311+
<Text> "Please swipe"->React.string </Text>
312+
</View>;
313+
};
76314
77315
```

0 commit comments

Comments
 (0)