From 64c8f22343dade4e619709f158e55f0195a4fabf Mon Sep 17 00:00:00 2001 From: James Isaac Date: Mon, 27 Feb 2017 01:49:36 -0800 Subject: [PATCH] Correct/consistent docs for Touchable components Summary: I ran into confusion (#12581) because the docs for TouchableOpacity stated that it doesn't change the view hierarchy, but in fact it does, and the docs are just out of date. - [20 Feb 2015](https://github.com/facebook/react-native/blob/efae175a8e1b05c976cc5a1cbd492da71eb3bb12/Libraries/Components/Touchable/TouchableOpacity.js#L21) Docs correctly reflected that the component was cloned so didn't affect hierarchy - [25 Jul 2015](https://github.com/facebook/react-native/commit/725053acfeba4c7f2a21ac47ae8100588a710476) Component was changed to being wrapped but docs weren't updated. Went to correct this in the docs and noticed they were a bit inconsistent with each other, so have made them more unified. Each one now clearly warns about: - If it adds a view to the hierarchy, which will affect layout. - If it can only accept a single child. Closes https://github.com/facebook/react-native/pull/12583 Differential Revision: D4619837 Pulled By: ericvicenti fbshipit-source-id: 4d1becd9f290cefcb4548a5ea2878be2d2c315fa --- .../Components/Touchable/TouchableHighlight.js | 16 +++++++++------- .../Touchable/TouchableNativeFeedback.android.js | 8 +++++--- .../Components/Touchable/TouchableOpacity.js | 5 +++-- .../Touchable/TouchableWithoutFeedback.js | 5 ++--- 4 files changed, 19 insertions(+), 15 deletions(-) diff --git a/Libraries/Components/Touchable/TouchableHighlight.js b/Libraries/Components/Touchable/TouchableHighlight.js index cbda37515..4651d9416 100644 --- a/Libraries/Components/Touchable/TouchableHighlight.js +++ b/Libraries/Components/Touchable/TouchableHighlight.js @@ -40,10 +40,15 @@ var PRESS_RETENTION_OFFSET = {top: 20, left: 20, right: 20, bottom: 30}; /** * A wrapper for making views respond properly to touches. * On press down, the opacity of the wrapped view is decreased, which allows - * the underlay color to show through, darkening or tinting the view. The - * underlay comes from adding a view to the view hierarchy, which can sometimes - * cause unwanted visual artifacts if not used correctly, for example if the - * backgroundColor of the wrapped view isn't explicitly set to an opaque color. + * the underlay color to show through, darkening or tinting the view. + * + * The underlay comes from wrapping the child in a new View, which can affect + * layout, and sometimes cause unwanted visual artifacts if not used correctly, + * for example if the backgroundColor of the wrapped view isn't explicitly set + * to an opaque color. + * + * TouchableHighlight must have one child (not zero or more than one). + * If you wish to have several child components, wrap them in a View. * * Example: * @@ -59,9 +64,6 @@ var PRESS_RETENTION_OFFSET = {top: 20, left: 20, right: 20, bottom: 30}; * ); * }, * ``` - * > **NOTE**: TouchableHighlight must have one child (not zero or more than one) - * > - * > If you wish to have several child components, wrap them in a View. */ var TouchableHighlight = React.createClass({ diff --git a/Libraries/Components/Touchable/TouchableNativeFeedback.android.js b/Libraries/Components/Touchable/TouchableNativeFeedback.android.js index d048545df..037a3b85c 100644 --- a/Libraries/Components/Touchable/TouchableNativeFeedback.android.js +++ b/Libraries/Components/Touchable/TouchableNativeFeedback.android.js @@ -45,9 +45,11 @@ var PRESS_RETENTION_OFFSET = {top: 20, left: 20, right: 20, bottom: 30}; /** * A wrapper for making views respond properly to touches (Android only). * On Android this component uses native state drawable to display touch - * feedback. At the moment it only supports having a single View instance as a - * child node, as it's implemented by replacing that View with another instance - * of RCTView node with some additional properties set. + * feedback. + * + * At the moment it only supports having a single View instance as a child + * node, as it's implemented by replacing that View with another instance of + * RCTView node with some additional properties set. * * Background drawable of native feedback touchable can be customized with * `background` property. diff --git a/Libraries/Components/Touchable/TouchableOpacity.js b/Libraries/Components/Touchable/TouchableOpacity.js index ceb99b951..8d3e53312 100644 --- a/Libraries/Components/Touchable/TouchableOpacity.js +++ b/Libraries/Components/Touchable/TouchableOpacity.js @@ -31,8 +31,9 @@ var PRESS_RETENTION_OFFSET = {top: 20, left: 20, right: 20, bottom: 30}; /** * A wrapper for making views respond properly to touches. * On press down, the opacity of the wrapped view is decreased, dimming it. - * This is done without actually changing the view hierarchy, and in general is - * easy to add to an app without weird side-effects. + * + * Opacity is controlled by wrapping the children in an Animated.View, which is + * added to the view hiearchy. Be aware that this can affect layout. * * Example: * diff --git a/Libraries/Components/Touchable/TouchableWithoutFeedback.js b/Libraries/Components/Touchable/TouchableWithoutFeedback.js index d0f825ceb..ed0d92d5c 100755 --- a/Libraries/Components/Touchable/TouchableWithoutFeedback.js +++ b/Libraries/Components/Touchable/TouchableWithoutFeedback.js @@ -28,9 +28,8 @@ const PRESS_RETENTION_OFFSET = {top: 20, left: 20, right: 20, bottom: 30}; * Do not use unless you have a very good reason. All the elements that * respond to press should have a visual feedback when touched. * - * > **NOTE**: TouchableWithoutFeedback supports only one child - * > - * > If you wish to have several child components, wrap them in a View. + * TouchableWithoutFeedback supports only one child. + * If you wish to have several child components, wrap them in a View. */ const TouchableWithoutFeedback = React.createClass({ mixins: [TimerMixin, Touchable.Mixin],