diff --git a/examples/dart/test/react_to_changes_test.dart b/examples/dart/test/react_to_changes_test.dart index 1c27554f08..041afb098f 100644 --- a/examples/dart/test/react_to_changes_test.dart +++ b/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.delayed(Duration(milliseconds: 10)); diff --git a/source/sdk/flutter/realm-database/react-to-changes.txt b/source/sdk/flutter/realm-database/react-to-changes.txt index 5587b70859..2f280a697c 100644 --- a/source/sdk/flutter/realm-database/react-to-changes.txt +++ b/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 ` - :ref:`User instance ` -.. 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 ` object - for ``RealmList`` + for ``RealmList`` - :flutter-sdk:`RealmSetChanges ` object for ``RealmSet`` -- :flutter-sdk:`RealmMapChanges ` object for +- :flutter-sdk:`RealmMapChanges ` object for ``RealmMap`` .. tabs:: @@ -175,28 +176,37 @@ changes since the last notification: * - ``modified`` - *List* - - 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* - - 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* - - Indexes of modified items after deletions and insertions are accounted for. + - Indexes of modified items after deletions and insertions are + accounted for. * - ``moved`` - *List* - Indexes of the items in the list that moved in this version. - * - ``list`` - - *RealmList* + * - ``list`` + - *RealmList* - ``RealmList`` being monitored for changes. * - ``isCleared`` - *boolean* - ``true`` when the list has been cleared by calling its - :flutter-sdk:`RealmList.clear() ` method. + :flutter-sdk:`RealmList.clear() ` + 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* - - 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* - - 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* - - Indexes of modified items after deletions and insertions are accounted for. + - Indexes of modified items after deletions and insertions are + accounted for. * - ``moved`` - *List* @@ -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() ` 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* - - 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* - - 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* + - *RealmMap* - ``RealmMap`` being monitored for changes. + * - ``isCleared`` + - *boolean* + - ``true`` when the map has been cleared by calling its + :flutter-sdk:`RealmMap.clear() ` 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 ` +The handler receives a :flutter-sdk:`UserChanges ` object, which includes description of changes since the last notification. ``UserChanges`` contains the following property: .. list-table:: + :widths: 20 30 50 * - Property - Type