Deprecate removeListener APIs (#2578)

Author: yungsters

docs/accessibilityinfo.md

@@ -21,13 +21,17 @@ const App = () => {
   const [screenReaderEnabled, setScreenReaderEnabled] = useState(false);
 
   useEffect(() => {
-    AccessibilityInfo.addEventListener(
+    const reduceMotionChangedSubscription = AccessibilityInfo.addEventListener(
       "reduceMotionChanged",
-      handleReduceMotionToggled
+      reduceMotionEnabled => {
+        setReduceMotionEnabled(reduceMotionEnabled);
+      }
     );
-    AccessibilityInfo.addEventListener(
+    const screenReaderChangedSubscription = AccessibilityInfo.addEventListener(
       "screenReaderChanged",
-      handleScreenReaderToggled
+      screenReaderEnabled => {
+        setScreenReaderEnabled(screenReaderEnabled);
+      }
     );
 
     AccessibilityInfo.isReduceMotionEnabled().then(
@@ -42,25 +46,11 @@ const App = () => {
     );
 
     return () => {
-      AccessibilityInfo.removeEventListener(
-        "reduceMotionChanged",
-        handleReduceMotionToggled
-      );
-      AccessibilityInfo.removeEventListener(
-        "screenReaderChanged",
-        handleScreenReaderToggled
-      );
+      reduceMotionChangedSubscription.remove();
+      screenReaderChangedSubscription.remove();
     };
   }, []);
 
-  const handleReduceMotionToggled = reduceMotionEnabled => {
-    setReduceMotionEnabled(reduceMotionEnabled);
-  };
-
-  const handleScreenReaderToggled = screenReaderEnabled => {
-    setScreenReaderEnabled(screenReaderEnabled);
-  };
-
   return (
     <View style={styles.container}>
       <Text style={styles.status}>
@@ -101,13 +91,17 @@ class AccessibilityStatusExample extends Component {
   };
 
   componentDidMount() {
-    AccessibilityInfo.addEventListener(
+    this.reduceMotionChangedSubscription = AccessibilityInfo.addEventListener(
       'reduceMotionChanged',
-      this._handleReduceMotionToggled
+      reduceMotionEnabled => {
+        this.setState({ reduceMotionEnabled });
+      }
     );
-    AccessibilityInfo.addEventListener(
+    this.screenReaderChangedSubscription = AccessibilityInfo.addEventListener(
       'screenReaderChanged',
-      this._handleScreenReaderToggled
+      screenReaderEnabled => {
+        this.setState({ screenReaderEnabled });
+      }
     );
 
     AccessibilityInfo.isReduceMotionEnabled().then(reduceMotionEnabled => {
@@ -119,52 +113,37 @@ class AccessibilityStatusExample extends Component {
   }
 
   componentWillUnmount() {
-    AccessibilityInfo.removeEventListener(
-      'reduceMotionChanged',
-      this._handleReduceMotionToggled
-    );
-
-    AccessibilityInfo.removeEventListener(
-      'screenReaderChanged',
-      this._handleScreenReaderToggled
-    );
+    this.reduceMotionChangedSubscription.remove();
+    this.screenReaderChangedSubscription.remove();
   }
 
-  _handleReduceMotionToggled = reduceMotionEnabled => {
-    this.setState({ reduceMotionEnabled });
-  };
-
-  _handleScreenReaderToggled = screenReaderEnabled => {
-    this.setState({ screenReaderEnabled });
-  };
-
   render() {
     return (
-      <View style={this.styles.container}>
-        <Text style={this.styles.status}>
+      <View style={styles.container}>
+        <Text style={styles.status}>
           The reduce motion is{' '}
           {this.state.reduceMotionEnabled ? 'enabled' : 'disabled'}.
         </Text>
-        <Text style={this.styles.status}>
+        <Text style={styles.status}>
           The screen reader is{' '}
           {this.state.screenReaderEnabled ? 'enabled' : 'disabled'}.
         </Text>
       </View>
     );
   }
-
-  styles = StyleSheet.create({
-    container: {
-      flex: 1,
-      alignItems: 'center',
-      justifyContent: 'center',
-    },
-    status: {
-      margin: 30,
-    },
-  });
 }
 
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  status: {
+    margin: 30,
+  },
+});
+
 export default AccessibilityStatusExample;
 ```
 
@@ -273,7 +252,7 @@ Query whether a screen reader is currently enabled. Returns a promise which reso
 static removeEventListener(eventName, handler)
 ```
 
-Remove an event handler.
+> **Deprecated.** Use the `remove()` method on the event subscription returned by [`addEventListener()`](#addeventlistener).
 
 ---
 

docs/appearance.md

@@ -87,4 +87,4 @@ Add an event handler that is fired when appearance preferences change.
 static removeChangeListener(listener)
 ```
 
-Remove an event handler.
+> **Deprecated.** Use the `remove()` method on the event subscription returned by [`addChangeListener()`](#addchangelistener).

docs/appstate.md

@@ -36,26 +36,24 @@ const AppStateExample = () => {
   const [appStateVisible, setAppStateVisible] = useState(appState.current);
 
   useEffect(() => {
-    AppState.addEventListener("change", _handleAppStateChange);
+    const subscription = AppState.addEventListener("change", nextAppState => {
+      if (
+        appState.current.match(/inactive|background/) &&
+        nextAppState === "active"
+      ) {
+        console.log("App has come to the foreground!");
+      }
+
+      appState.current = nextAppState;
+      setAppStateVisible(appState.current);
+      console.log("AppState", appState.current);
+    });
 
     return () => {
-      AppState.removeEventListener("change", _handleAppStateChange);
+      subscription.remove();
     };
   }, []);
 
-  const _handleAppStateChange = (nextAppState) => {
-    if (
-      appState.current.match(/inactive|background/) &&
-      nextAppState === "active"
-    ) {
-      console.log("App has come to the foreground!");
-    }
-
-    appState.current = nextAppState;
-    setAppStateVisible(appState.current);
-    console.log("AppState", appState.current);
-  };
-
   return (
     <View style={styles.container}>
       <Text>Current state is: {appStateVisible}</Text>
@@ -89,23 +87,24 @@ class AppStateExample extends Component {
   };
 
   componentDidMount() {
-    AppState.addEventListener("change", this._handleAppStateChange);
+    this.appStateSubscription = AppState.addEventListener(
+      "change",
+      nextAppState => {
+        if (
+          this.state.appState.match(/inactive|background/) &&
+          nextAppState === "active"
+        ) {
+          console.log("App has come to the foreground!");
+        }
+        this.setState({ appState: nextAppState });
+      }
+    );
   }
 
   componentWillUnmount() {
-    AppState.removeEventListener("change", this._handleAppStateChange);
+    this.appStateSubscription.remove();
   }
 
-  _handleAppStateChange = nextAppState => {
-    if (
-      this.state.appState.match(/inactive|background/) &&
-      nextAppState === "active"
-    ) {
-      console.log("App has come to the foreground!");
-    }
-    this.setState({ appState: nextAppState });
-  };
-
   render() {
     return (
       <View style={styles.container}>
@@ -163,8 +162,6 @@ addEventListener(type, handler);
 
 Add a handler to AppState changes by listening to the `change` event type and providing the handler
 
-TODO: now that AppState is a subclass of NativeEventEmitter, we could deprecate `addEventListener` and `removeEventListener` and use `addListener` and `listener.remove()` directly. That will be a breaking change though, as both the method and event names are different (addListener events are currently required to be globally unique).
-
 ---
 
 ### `removeEventListener()`
@@ -173,7 +170,7 @@ TODO: now that AppState is a subclass of NativeEventEmitter, we could deprecate
 removeEventListener(type, handler);
 ```
 
-Remove a handler by passing the `change` event type and the handler
+> **Deprecated.** Use the `remove()` method on the event subscription returned by [`addEventListener()`](#addeventlistener).
 
 ## Properties
 

docs/dimensions.md

@@ -37,14 +37,15 @@ const screen = Dimensions.get("screen");
 const App = () => {
   const [dimensions, setDimensions] = useState({ window, screen });
 
-  const onChange = ({ window, screen }) => {
-    setDimensions({ window, screen });
-  };
-
   useEffect(() => {
-    Dimensions.addEventListener("change", onChange);
+    const subscription = Dimensions.addEventListener(
+      "change",
+      ({ window, screen }) => {
+        setDimensions({ window, screen });
+      }
+    );
     return () => {
-      Dimensions.removeEventListener("change", onChange);
+      subscription.remove();
     };
   });
 
@@ -90,11 +91,11 @@ class App extends Component {
   };
 
   componentDidMount() {
-    Dimensions.addEventListener("change", this.onChange);
+    this.dimensionsSubscription = Dimensions.addEventListener("change", this.onChange);
   }
 
   componentWillUnmount() {
-    Dimensions.removeEventListener("change", this.onChange);
+    this.dimensionsSubscription.remove();
   }
 
   render() {
@@ -167,7 +168,7 @@ Example: `const {height, width} = Dimensions.get('window');`
 static removeEventListener(type, handler)
 ```
 
-Remove an event handler.
+> **Deprecated.** Use the `remove()` method on the event subscription returned by [`addEventListener()`](#addeventlistener).
 
 ---
 

docs/keyboard.md

@@ -19,21 +19,22 @@ import React, { useState, useEffect } from "react";
 import { Keyboard, Text, TextInput, StyleSheet, View } from "react-native";
 
 const Example = () => {
+  const [keyboardStatus, setKeyboardStatus] = useState(undefined);
+
   useEffect(() => {
-    Keyboard.addListener("keyboardDidShow", _keyboardDidShow);
-    Keyboard.addListener("keyboardDidHide", _keyboardDidHide);
+    const showSubscription = Keyboard.addListener("keyboardDidShow", () => {
+      setKeyboardStatus("Keyboard Shown");
+    });
+    const hideSubscription = Keyboard.addListener("keyboardDidHide", () => {
+      setKeyboardStatus("Keyboard Hidden");
+    });
 
-    // cleanup function
     return () => {
-      Keyboard.removeListener("keyboardDidShow", _keyboardDidShow);
-      Keyboard.removeListener("keyboardDidHide", _keyboardDidHide);
+      showSubscription.remove();
+      hideSubscription.remove();
     };
   }, []);
 
-  const [keyboardStatus, setKeyboardStatus] = useState(undefined);
-  const _keyboardDidShow = () => setKeyboardStatus("Keyboard Shown");
-  const _keyboardDidHide = () => setKeyboardStatus("Keyboard Hidden");
-
   return (
     <View style={style.container}>
       <TextInput
@@ -78,27 +79,23 @@ class Example extends Component {
   };
 
   componentDidMount() {
-    this.keyboardDidShowListener = Keyboard.addListener(
+    this.keyboardDidShowSubscription = Keyboard.addListener(
       'keyboardDidShow',
-      this._keyboardDidShow,
+      () => {
+        this.setState({ keyboardStatus: 'Keyboard Shown' });
+      },
     );
-    this.keyboardDidHideListener = Keyboard.addListener(
+    this.keyboardDidHideSubscription = Keyboard.addListener(
       'keyboardDidHide',
-      this._keyboardDidHide,
+      () => {
+        this.setState({ keyboardStatus: 'Keyboard Hidden' });
+      },
     );
   }
 
   componentWillUnmount() {
-    this.keyboardDidShowListener.remove();
-    this.keyboardDidHideListener.remove();
-  }
-
-  _keyboardDidShow = () => {
-    this.setState({ keyboardStatus: 'Keyboard Shown' });
-  }
-
-  _keyboardDidHide = () => {
-    this.setState({ keyboardStatus: 'Keyboard Hidden' });
+    this.keyboardDidShowSubscription.remove();
+    this.keyboardDidHideSubscription.remove();
   }
 
   render() {
@@ -183,7 +180,7 @@ This can be any of the following:
 static removeListener(eventName, callback)
 ```
 
-Removes a specific listener.
+> **Deprecated.** Use the `remove()` method on the event subscription returned by [`addListener()`](#addlistener).
 
 **Parameters:**
 

docs/linking.md

@@ -377,7 +377,7 @@ The method returns a `Promise` object. If the user confirms the open dialog or t
 removeEventListener(type, handler);
 ```
 
-Remove a handler by passing the `url` event type and the handler.
+> **Deprecated.** Use the `remove()` method on the event subscription returned by [`addEventListener()`](#addeventlistener).
 
 ---