Add new collection listener properties

examples/dart/test/react_to_changes_test.dart

@@ -2,7 +2,6 @@
 
 import 'package:test/test.dart';
 import 'package:realm_dart/realm.dart';
-import './utils.dart';
 part 'react_to_changes_test.realm.dart';
 
 // :snippet-start: sample-data-models
@@ -117,16 +116,17 @@ void main() {
       // :snippet-start: realm-list-change-listener
       final fellowshipSubscription =
           fellowshipOfTheRing.members.changes.listen((changes) {
-        changes.inserted; // indexes of inserted Realm objects
-        changes.modified; // indexes of modified Realm objects
-        changes.deleted; // indexes of deleted Realm objects
-        changes.newModified; // indexes of modified Realm objects
-        // after deletions and insertions are accounted for
-        changes.moved; // indexes of moved Realm objects
-        changes.list; // the full RealmList of Realm objects
-        // `true` after call to fellowshipOfTheRing.members.clear().
-        // Otherwise false.
-        changes.isCleared;
+        changes.inserted; // Indexes of inserted objects.
+        changes.modified; // Indexes of modified objects.
+        changes.deleted; // Indexes of deleted objects.
+        changes.newModified; // Indexes of modified objects
+        // after deletions and insertions are accounted for.
+        changes.moved; // Indexes of moved objects.
+        changes.list; // The full RealmList of objects.
+        changes.isCleared; // `true` after call to
+        // fellowshipOfTheRing.members.clear(); otherwise, `false`.
+        changes.isCollectionDeleted; // `true` if the collection is deleted;
+        // otherwise, `false`.
       });
       // :snippet-end:
       await Future<void>.delayed(Duration(milliseconds: 10));

source/sdk/flutter/realm-database/react-to-changes.txt

@@ -6,7 +6,7 @@ React to Changes - Flutter SDK
 ==============================
 
 .. meta::
-  :description: SDK notifications allow you to watch for and react to changes in your data.
+  :description: Atlas Device SDK for Flutter notifications allow you to watch for and react to changes in your data.
   :keywords: code example
 
 .. facet::
@@ -19,17 +19,16 @@ React to Changes - Flutter SDK
    :depth: 2
    :class: singlecol
 
-All Realm objects are **live objects**, which means they
-automatically update whenever they're modified. Realm emits a
-notification event whenever any property changes. 
+All Flutter SDK objects are **live objects**, which means they
+automatically update whenever they're modified. The SDK emits a
+notification event whenever any property changes.
 
-When a user adds a new item to a list,
-you may want to update the UI, show a notification, or log a message.
-When someone updates that item, you may want to change its visual state
-or fire off a network request.
-Finally, when someone deletes the item, you probably want to remove it from the UI.
-Realm's notification system allows you to watch for and react to changes in your data,
-independent of the writes that caused the changes.
+When a user adds a new item to a list, you may want to update the UI, show a
+notification, or log a message. When someone updates that item, you may want to
+change its visual state or fire off a network request. Finally, when someone
+deletes the item, you probably want to remove it from the
+UI. The SDK's notification system allows you to watch for and react to changes
+in your data, independent of the writes that caused the changes.
 
 You can subscribe to changes on the following events:
 
@@ -38,19 +37,19 @@ You can subscribe to changes on the following events:
 - :ref:`Collections in a Realm object <flutter-realm-list-change-listener>`
 - :ref:`User instance <flutter-user-change-listener>`
 
-.. example:: About the Examples on This Page
+About the Examples on This Page
+-------------------------------
 
-   The examples in this page use two Realm object types, ``Character`` and
-   ``Fellowship``:
+The examples in this page use two object types, ``Character`` and
+``Fellowship``:
 
-   .. literalinclude:: /examples/generated/flutter/react_to_changes_test.snippet.sample-data-models.dart
-      :language: dart
-
-   The examples have this sample data:
+.. literalinclude:: /examples/generated/flutter/react_to_changes_test.snippet.sample-data-models.dart
+  :language: dart
 
-   .. literalinclude:: /examples/generated/flutter/react_to_changes_test.snippet.sample-data-seed.dart
-      :language: dart
+Additionally, the examples have this sample data:
 
+.. literalinclude:: /examples/generated/flutter/react_to_changes_test.snippet.sample-data-seed.dart
+  :language: dart
 
 .. _flutter-query-change-listener:
 
@@ -63,6 +62,7 @@ which includes description of changes since the last notification.
 ``RealmResultsChanges`` contains the following properties:
 
 .. list-table::
+   :widths: 20 30 50
 
    * - Property
      - Type
@@ -94,8 +94,8 @@ which includes description of changes since the last notification.
 
    * - ``isCleared``
      - *bool*
-     - Deprecated in Realm Flutter SDK v1.1.0. Use ``RealmResultsChanges.results.isEmpty`` instead.
-       Returns ``true`` if the results collection is empty in the notification callback.
+     - Returns ``true`` if the results collection is empty in the notification
+       callback.
 
 .. literalinclude:: /examples/generated/flutter/react_to_changes_test.snippet.query-change-listener.dart
    :language: dart
@@ -112,6 +112,7 @@ which includes description of changes since the last notification.
 ``RealmObjectChanges`` contains the following properties:
 
 .. list-table::
+   :widths: 20 30 50
 
    * - Property
      - Type
@@ -144,14 +145,14 @@ Register Collection Change Listeners
 You can register a notification handler on a collection of any of the
 supported data types within another ``RealmObject``.
 Realm notifies your handler when any of the items in the collection change.
-The handler receives one of the following objects that include a description of 
-changes since the last notification: 
+The handler receives one of the following objects that include a description of
+changes since the last notification:
 
 - :flutter-sdk:`RealmListChanges <realm/RealmListChanges-class.html>` object
-  for ``RealmList`` 
+  for ``RealmList``
 - :flutter-sdk:`RealmSetChanges <realm/RealmSetChanges-class.html>` object
   for ``RealmSet``
-- :flutter-sdk:`RealmMapChanges <realm/RealmMapChanges-class.html>` object for 
+- :flutter-sdk:`RealmMapChanges <realm/RealmMapChanges-class.html>` object for
   ``RealmMap``
 
 .. tabs::
@@ -175,28 +176,37 @@ changes since the last notification:
 
         * - ``modified``
           - *List<int>*
-          -  Indexes of items in the previous version of the list that were modified in this version.
+          -  Indexes of items in the previous version of the list that were
+             modified in this version.
 
         * - ``deleted``
           - *List<int>*
-          -  Indexes of items in the previous version of the list that were removed from this version.
+          -  Indexes of items in the previous version of the list that were
+             removed from this version.
 
         * - ``newModified``
           - *List<int>*
-          - Indexes of modified items after deletions and insertions are accounted for.
+          - Indexes of modified items after deletions and insertions are
+            accounted for.
 
         * - ``moved``
           - *List<int>*
           - Indexes of the items in the list that moved in this version.
 
-        * - ``list`` 
-          - *RealmList<T>* 
+        * - ``list``
+          - *RealmList<T>*
           - ``RealmList`` being monitored for changes.
 
         * - ``isCleared``
           - *boolean*
           - ``true`` when the list has been cleared by calling its
-            :flutter-sdk:`RealmList.clear() <realm/RealmList-class.html>` method.
+            :flutter-sdk:`RealmList.clear() <realm/RealmList-class.html>`
+            method.
+
+        * - ``isCollectionDeleted``
+          - *boolean*
+          - ``true`` when the parent object containing the list has been
+            deleted.
 
    .. tab:: RealmSetChanges
       :tabid: set
@@ -217,15 +227,18 @@ changes since the last notification:
 
         * - ``modified``
           - *List<int>*
-          -  Indexes of the items in the previous version of the set that were modified in this version.
+          -  Indexes of the items in the previous version of the set that were
+             modified in this version.
 
         * - ``deleted``
           - *List<int>*
-          -  Indexes of items in the previous version of the set that were removed from this version.
+          -  Indexes of items in the previous version of the set that were
+             removed from this version.
 
         * - ``newModified``
           - *List<int>*
-          - Indexes of modified items after deletions and insertions are accounted for.
+          - Indexes of modified items after deletions and insertions are
+            accounted for.
 
         * - ``moved``
           - *List<int>*
@@ -237,9 +250,13 @@ changes since the last notification:
 
         * - ``isCleared``
           - *boolean*
-          - ``true`` when a set has been cleared by calling its
+          - ``true`` when the set has been cleared by calling its
             :flutter-sdk:`RealmSet.clear() <realm/RealmSet-class.html>` method.
 
+        * - ``isCollectionDeleted``
+          - *boolean*
+          - ``true`` when the parent object containing the set has been deleted.
+
    .. tab:: RealmMapChanges
       :tabid: map
 
@@ -259,16 +276,27 @@ changes since the last notification:
 
         * - ``modified``
           - *List<String>*
-          -  Keys of the previous version of the map whose corresponding values were modified in this version.
+          -  Keys of the previous version of the map whose corresponding values
+             were modified in this version.
 
         * - ``deleted``
           - *List<String>*
-          -  Keys of the previous version of the map that were removed from this  version.
+          -  Keys of the previous version of the map that were removed from this
+             version.
 
         * - ``map``
-          - *RealmMap<T>* 
+          - *RealmMap<T>*
           - ``RealmMap`` being monitored for changes.
 
+        * - ``isCleared``
+          - *boolean*
+          - ``true`` when the map has been cleared by calling its
+            :flutter-sdk:`RealmMap.clear() <realm/RealmMap-class.html>` method.
+
+        * - ``isCollectionDeleted``
+          - *boolean*
+          - ``true`` when the parent object containing the map has been deleted.
+
 .. literalinclude:: /examples/generated/flutter/react_to_changes_test.snippet.realm-list-change-listener.dart
   :language: dart
 
@@ -279,15 +307,16 @@ Register a User Instance Change Listener
 
 .. versionadded:: 1.9.0
 
-In Flutter SDK version 1.9.0 and later, you can register a notification handler 
+In Flutter SDK version 1.9.0 and later, you can register a notification handler
 on a specific ``User`` instance within a realm.
-Realm notifies your handler when any of the user's properties change (for 
+Realm notifies your handler when any of the user's properties change (for
 example, the user acces token is updated or the user state changes).
-The handler receives a :flutter-sdk:`UserChanges <realm/UserChanges-class.html>` 
+The handler receives a :flutter-sdk:`UserChanges <realm/UserChanges-class.html>`
 object, which includes description of changes since the last notification.
 ``UserChanges`` contains the following property:
 
 .. list-table::
+   :widths: 20 30 50
 
    * - Property
      - Type