Permalink
Browse files

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](725053a) 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 #12583

Differential Revision: D4619837

Pulled By: ericvicenti

fbshipit-source-id: 4d1becd9f290cefcb4548a5ea2878be2d2c315fa
  • Loading branch information...
jamesisaac authored and facebook-github-bot committed Feb 27, 2017
1 parent 9217ff3 commit 64c8f22343dade4e619709f158e55f0195a4fabf
@@ -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({
@@ -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.
@@ -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:
*
@@ -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],

0 comments on commit 64c8f22

Please sign in to comment.