From f6cc7b34b896c6e10c0f4e3ed454d03338f06024 Mon Sep 17 00:00:00 2001 From: sgny <28243224+sgny@users.noreply.github.com> Date: Thu, 30 May 2019 16:20:23 +0300 Subject: [PATCH] Add documentation for PanResponder API (#513) --- reason-react-native/src/apis/PanResponder.md | 310 ++++++++++++++++--- 1 file changed, 274 insertions(+), 36 deletions(-) diff --git a/reason-react-native/src/apis/PanResponder.md b/reason-react-native/src/apis/PanResponder.md index 3e2cf0a6231462..f7a3087002d74d 100644 --- a/reason-react-native/src/apis/PanResponder.md +++ b/reason-react-native/src/apis/PanResponder.md @@ -1,9 +1,42 @@ --- -id: apis/Packager -title: Packager -wip: true +id: apis/PanResponder +title: PanResponder +officialDoc: http://facebook.github.io/react-native/docs/panresponder --- +`PanResponder` allows more fine-grained control of the +[_Gesture Responder System_](http://facebook.github.io/react-native/docs/gesture-responder-system), +as the handlers can depend also on `gestureState`, in addition to the +`Event.pressEvent` which are passed to the _Gesture Responder System_ handlers. +In essence, by means of a custom `PanResponder`, _Gesture Responder System_ +handlers are extended to also depend upon the `gestureState`. + +## Types + +### `Event.pressEvent` +`Event.pressEvent` is `Event.syntheticEvent(pressEventPayload)` where the +`nativeEvent` key is recursively specified as: + +```reason +type pressEventPayload = { + . + "changedTouches": array(pressEventPayload), + "force": float, + "identifier": int, + "locationX": float, + "locationY": float, + "pageX": float, + "pageY": float, + "target": Js.Nullable.t(float), + "timestamp": float, + "touches": array(pressEventPayload), +} +``` + +### `gestureState` +`gestureState` contains additional information on the state of the \_Gesture +Responder System\_ + ```reason type gestureState = { . @@ -17,15 +50,19 @@ type gestureState = { "vx": float, "vy": float, "numberActiveTouches": int, -}; +} +``` + +### `t` +`t` is the abstract type for a `PanResponder`, which can be created by means +of the `create` method, given a `config` object -type t; -type config; -type panHandlers; -type callback('a) = Event.pressEvent => 'a; +### `config` +`config` is the abstract type for a custom `PanResponder` configuration; it +can be created by means of the `config` constructor -[@bs.obj] -external config: +```reason +config: ( ~onMoveShouldSetPanResponder: (Event.pressEvent, gestureState) => bool=?, ~onMoveShouldSetPanResponderCapture: (Event.pressEvent, gestureState) => @@ -46,32 +83,233 @@ external config: =?, ~onShouldBlockNativeResponder: (Event.pressEvent, gestureState) => bool=?, unit - ) => - config = - ""; - -[@bs.module "react-native"] [@bs.scope "PanResponder"] -external create: config => t = ""; - -[@bs.get] external panHandlers: t => panHandlers = ""; - -[@bs.get] -external onMoveShouldSetResponder: panHandlers => callback(bool) = ""; -[@bs.get] -external onMoveShouldSetResponderCapture: panHandlers => callback(bool) = ""; -[@bs.get] -external onStartShouldSetResponder: panHandlers => callback(bool) = ""; -[@bs.get] -external onStartShouldSetResponderCapture: panHandlers => callback(bool) = ""; -[@bs.get] external onResponderReject: panHandlers => callback(unit) = ""; -[@bs.get] external onResponderGrant: panHandlers => callback(unit) = ""; -[@bs.get] external onResponderRelease: panHandlers => callback(unit) = ""; -[@bs.get] external onResponderMove: panHandlers => callback(unit) = ""; -[@bs.get] external onResponderTerminate: panHandlers => callback(unit) = ""; -[@bs.get] -external onResponderTerminationRequest: panHandlers => callback(bool) = ""; -[@bs.get] external onResponderStart: panHandlers => callback(unit) = ""; -[@bs.get] external onResponderEnd: panHandlers => callback(unit) = ""; + ) +``` + +### `panHandlers` +`panHandlers` is the abstract type for `panHandlers` of a `PanResponder`, +which can be accessed by means of the getter method `panHandlers` + +### `callback('a)` +`callback('a)` is the type of the usual callback function specified for each +_Gesture Responder System_ handler defined as + +```reason +type callback('a) = Event.pressEvent => 'a +``` + +where `'a` is either `bool` or `unit` + +## Methods + +### `create` +`create` allows creation of a `PanResponder` given a `config` + +```reason +create(config) +``` + +### `panHandlers` +`panHandlers` is a getter method to access `panHandlers` within a + +`PanResponder` + +```reason +panHandlers(t) +``` + +### `onMoveShouldSetResponder` +`onMoveShouldSetResponder` is a getter method to access the +`onMoveShouldSetResponder` callback of a `panHandlers` object + +```reason +onMoveShouldSetResponder(panHandlers) +``` + +### `onMoveShouldSetResponderCapture` +`onMoveShouldSetResponderCapture` is a getter method to access the +`onMoveShouldSetResponderCapture` callback of a `panHandlers` object + +```reason +onMoveShouldSetResponderCapture(panHandlers) +``` + +### `onStartShouldSetResponder` +`onStartShouldSetResponder` is a getter method to access the +`onStartShouldSetResponder` callback of a `panHandlers` object + +```reason +onStartShouldSetResponder(panHandlers) +``` + +### `onStartShouldSetResponderCapture` +`onStartShouldSetResponderCapture` is a getter method to access the +`onStartShouldSetResponderCapture` callback of a `panHandlers` object + +```reason +onStartShouldSetResponderCapture(panHandlers) +``` + +### `onResponderReject` +`onResponderReject` is a getter method to access the `onResponderReject` +callback of a `panHandlers` object +```reason +onResponderReject(panHandlers) +``` + +### `onResponderGrant` +`onResponderGrant` is a getter method to access the `onResponderGrant` +callback of a `panHandlers` object + +```reason +onResponderGrant(panHandlers) +``` + +### `onResponderRelease` +`onResponderRelease` is a getter method to access the `onResponderRelease` +callback of a `panHandlers` object + +```reason +onResponderRelease(panHandlers) +``` + +### `onResponderMove` +`onResponderMove` is a getter method to access the `onResponderMove` callback +of a `panHandlers` object + +```reason +onResponderMove(panHandlers) +``` + +### `onResponderTerminate` +`onResponderTerminate` is a getter method to access the `onResponderTerminate` +callback of a `panHandlers` object + +```reason +onResponderTerminate(panHandlers) +``` + +### `onResponderStart` +`onResponderStart` is a getter method to access the `onResponderStart` +callback of a `panHandlers` object + +```reason +onResponderStart(panHandlers) +``` + +### `onResponderTerminationRequest` +`onResponderTerminationRequest` is a getter method to access the +`onResponderTerminationRequest` callback of a `panHandlers` object + +```reason +onResponderTerminationRequest(panHandlers) +``` + +### `onResponderEnd` +`onResponderEnd` is a getter method to access the `onResponderEnd` callback of +a `panHandlers` object + +```reason +onResponderEnd(panHandlers) +``` + +## Example + +As props spread is not possible with the ReasonML JSX 3 syntax, each _Gesture +Responder System_ callback needs to be separately specified, with the relevant +value obtained by means of the associated getter. + +While props spread may not be available, copy-paste is probably supported by +your editor... + +```reason +onMoveShouldSetResponder={ + panHandlers->PanResponder.onMoveShouldSetResponder +} +onMoveShouldSetResponderCapture={ + panHandlers->PanResponder.onMoveShouldSetResponderCapture +} +onStartShouldSetResponder={ + panHandlers->PanResponder.onStartShouldSetResponder +} +onStartShouldSetResponderCapture={ + panHandlers->PanResponder.onStartShouldSetResponderCapture +} +onResponderReject={panHandlers->PanResponder.onResponderReject} +onResponderGrant={panHandlers->PanResponder.onResponderGrant} +onResponderRelease={panHandlers->PanResponder.onResponderRelease} +onResponderMove={panHandlers->PanResponder.onResponderMove} +onResponderTerminate={panHandlers->PanResponder.onResponderTerminate} +onResponderStart={panHandlers->PanResponder.onResponderStart} +onResponderTerminationRequest={ + panHandlers->PanResponder.onResponderTerminationRequest +} +onResponderEnd={panHandlers->PanResponder.onResponderEnd} +``` + +Then, the custom `PanResponder` can be used as below: + +```reason +open ReactNative; + +let windowHeight = Dimensions.get(`window)##height->float_of_int; +let windowWidth = Dimensions.get(`window)##width->float_of_int; + +let containerStyle = + Style.( + style( + ~width=windowWidth->pt, + ~height=windowHeight->pt, + ~justifyContent=`center, + ~alignItems=`center, + (), + ) + ); + +let config = + PanResponder.config( + ~onMoveShouldSetPanResponder=(_e, _g) => true, + ~onPanResponderRelease= + (_e, g) => + g##dx > 0. + ? "You swiped right"->Js.Console.warn + : "You swiped left"->Js.Console.warn, + (), + ); + +let panResponder = PanResponder.create(config); + +let panHandlers = panResponder->PanResponder.panHandlers; + +[@react.component] +let make = () => { + PanResponder.onMoveShouldSetResponder + } + onMoveShouldSetResponderCapture={ + panHandlers->PanResponder.onMoveShouldSetResponderCapture + } + onStartShouldSetResponder={ + panHandlers->PanResponder.onStartShouldSetResponder + } + onStartShouldSetResponderCapture={ + panHandlers->PanResponder.onStartShouldSetResponderCapture + } + onResponderReject={panHandlers->PanResponder.onResponderReject} + onResponderGrant={panHandlers->PanResponder.onResponderGrant} + onResponderRelease={panHandlers->PanResponder.onResponderRelease} + onResponderMove={panHandlers->PanResponder.onResponderMove} + onResponderTerminate={panHandlers->PanResponder.onResponderTerminate} + onResponderStart={panHandlers->PanResponder.onResponderStart} + onResponderTerminationRequest={ + panHandlers->PanResponder.onResponderTerminationRequest + } + onResponderEnd={panHandlers->PanResponder.onResponderEnd}> + "Please swipe"->React.string + ; +}; ```