[add] Dimensions event listeners

Close #511

docs/storybook/2-apis/Dimensions/DimensionsDocs.js

@@ -4,8 +4,9 @@
  * @flow
  */
 
+import DimensionsChange from './examples/DimensionsChange';
 import { storiesOf } from '@kadira/storybook';
-import UIExplorer, { DocItem } from '../../ui-explorer';
+import UIExplorer, { AppText, Code, DocItem, TextList } from '../../ui-explorer';
 import React from 'react';
 
 const sections = [
@@ -19,6 +20,34 @@ const sections = [
         example={{
           code: "const { height, width } = Dimensions.get('window')"
         }}
+      />,
+      <DocItem
+        name="static addEventLitener"
+        typeInfo="(type: string, handler: function) => void"
+        description={[
+          <AppText>Add an event handler. Supported events:</AppText>,
+
+          <TextList
+            items={[
+              <AppText>
+                <Code>change</Code>: Fires when a property within the <Code>Dimensions</Code> object
+                changes. The argument to the event handler is an object
+                with <Code>window</Code> and <Code>screen</Code> properties whose values are the
+                same as the return values of <Code>Dimensions.get('window')</Code> and{' '}
+                <Code>Dimensions.get('screen')</Code>,
+                respectively.
+              </AppText>
+            ]}
+          />
+        ]}
+        example={{
+          render: () => <DimensionsChange />
+        }}
+      />,
+      <DocItem
+        name="static removeEventLitener"
+        typeInfo="(type: string, handler: function) => void"
+        description="Remove an event handler."
       />
     ]
   }
@@ -29,5 +58,6 @@ storiesOf('APIs', module).add('Dimensions', () =>
     description="Note: dimensions may change (e.g., due to device rotation) so any rendering logic or styles that depend on these constants should try to call this function on every render, rather than caching the value."
     sections={sections}
     title="Dimensions"
+    url="apis/Dimensions"
   />
 );

docs/storybook/2-apis/Dimensions/examples/DimensionsChange.js

@@ -0,0 +1,61 @@
+import { Button, Dimensions, ScrollView, StyleSheet, Text, View } from 'react-native';
+import React, { Component } from 'react';
+
+export default class ChangeEventExample extends Component {
+  state = {
+    listened: false,
+    logs: []
+  };
+
+  componentWillUnmount() {
+    Dimensions.removeEventListener('change', this._handleChange);
+  }
+
+  render() {
+    const { logs, listened } = this.state;
+    const buttonTitle = listened ? 'Remove listener' : 'Add listener';
+    return (
+      <View>
+        <Button onPress={this.toggle} title={buttonTitle} />
+        <ScrollView style={styles.logs}>
+          {logs.map((log, i) => <Text key={i} style={styles.log}>{log}</Text>)}
+        </ScrollView>
+      </View>
+    );
+  }
+
+  toggle = () => {
+    const { listened } = this.state;
+    if (listened) {
+      Dimensions.removeEventListener('change', this._handleChange);
+      this._log('Removed listener');
+    } else {
+      Dimensions.addEventListener('change', this._handleChange);
+      this._log('Added listener');
+    }
+    this.setState(() => ({ listened: !listened }));
+  };
+
+  _handleChange = ({ window, screen }) => {
+    window = JSON.stringify(window, null, 2);
+    screen = JSON.stringify(screen, null, 2);
+    this._log(`Changed\nwindow = ${window}\nscreen = ${screen}`);
+  };
+
+  _log = msg => {
+    this.setState(state => ({
+      logs: [`${new Date().toTimeString()} - ${msg}`, ...state.logs]
+    }));
+  };
+}
+
+const styles = StyleSheet.create({
+  logs: {
+    maxHeight: 256
+  },
+  log: {
+    fontFamily: 'monospace, monospace',
+    marginTop: 8,
+    marginBottom: 8
+  }
+});

docs/storybook/ui-explorer/TextList.js

@@ -26,7 +26,7 @@ const styles = StyleSheet.create({
   bullet: {
     position: 'absolute',
     left: 6,
-    top: '50%',
+    top: '.65625rem',
     marginTop: -2,
     height: 4,
     width: 4,