From cb37f5c7c2d5e8b79e2992125a62bc200ba2cc29 Mon Sep 17 00:00:00 2001 From: cbullinger Date: Tue, 7 May 2024 23:12:25 -0400 Subject: [PATCH] Add new collection listener properties --- examples/dart/test/react_to_changes_test.dart | 43 +++--- ...est.snippet.pause-resume-subscription.dart | 2 +- ...es_test.snippet.query-change-listener.dart | 16 +-- ...st.snippet.realm-list-change-listener.dart | 18 ++- ....snippet.realm-object-change-listener.dart | 6 +- .../realm-database/react-to-changes.txt | 122 +++++++++++------- 6 files changed, 117 insertions(+), 90 deletions(-) diff --git a/examples/dart/test/react_to_changes_test.dart b/examples/dart/test/react_to_changes_test.dart index 1c27554f08..576a04cb54 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 @@ -71,16 +70,16 @@ void main() { // Listen for changes on whole collection final characters = realm.all(); final subscription = characters.changes.listen((changes) { - 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.results; // the full List of objects + 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 accounting for deletions & insertions. + changes.moved; // Indexes of moved objects. + changes.results; // The full List of objects. + changes.isCleared; // `true` after call to characters.clear(); otherwise, `false`. }); - // Listen for changes on RealmResults + // Listen for changes on RealmResults. final hobbits = fellowshipOfTheRing.members.query('species == "Hobbit"'); final hobbitsSubscription = hobbits.changes.listen((changes) { // ... all the same data as above @@ -89,7 +88,7 @@ void main() { await Future.delayed(Duration(milliseconds: 10)); // :snippet-start: pause-resume-subscription subscription.pause(); - // the changes.listen() method won't fire until the subscription is resumed + // The changes.listen() method won't fire until subscription is resumed. subscription.resume(); // :snippet-end: await Future.delayed(Duration(milliseconds: 10)); @@ -103,9 +102,9 @@ void main() { final frodo = globalFrodo; // :snippet-start: realm-object-change-listener final frodoSubscription = frodo.changes.listen((changes) { - changes.isDeleted; // if the object has been deleted - changes.object; // the RealmObject being listened to, `frodo` - changes.properties; // the changed properties + changes.isDeleted; // If the object has been deleted. + changes.object; // The RealmObject being listened to, `frodo`. + changes.properties; // The changed properties. }); // :snippet-end: await Future.delayed(Duration(milliseconds: 10)); @@ -117,16 +116,14 @@ 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 accounting for deletions & insertions. + 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/examples/generated/flutter/react_to_changes_test.snippet.pause-resume-subscription.dart b/source/examples/generated/flutter/react_to_changes_test.snippet.pause-resume-subscription.dart index 3d1ca6bc95..98323e7956 100644 --- a/source/examples/generated/flutter/react_to_changes_test.snippet.pause-resume-subscription.dart +++ b/source/examples/generated/flutter/react_to_changes_test.snippet.pause-resume-subscription.dart @@ -1,3 +1,3 @@ subscription.pause(); -// the changes.listen() method won't fire until the subscription is resumed +// The changes.listen() method won't fire until subscription is resumed. subscription.resume(); diff --git a/source/examples/generated/flutter/react_to_changes_test.snippet.query-change-listener.dart b/source/examples/generated/flutter/react_to_changes_test.snippet.query-change-listener.dart index 74249f838b..aeff5ec964 100644 --- a/source/examples/generated/flutter/react_to_changes_test.snippet.query-change-listener.dart +++ b/source/examples/generated/flutter/react_to_changes_test.snippet.query-change-listener.dart @@ -1,16 +1,16 @@ // Listen for changes on whole collection final characters = realm.all(); final subscription = characters.changes.listen((changes) { - 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.results; // the full List of objects + 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 accounting for deletions & insertions. + changes.moved; // Indexes of moved objects. + changes.results; // The full List of objects. + changes.isCleared; // `true` after call to characters.clear(); otherwise, `false`. }); -// Listen for changes on RealmResults +// Listen for changes on RealmResults. final hobbits = fellowshipOfTheRing.members.query('species == "Hobbit"'); final hobbitsSubscription = hobbits.changes.listen((changes) { // ... all the same data as above diff --git a/source/examples/generated/flutter/react_to_changes_test.snippet.realm-list-change-listener.dart b/source/examples/generated/flutter/react_to_changes_test.snippet.realm-list-change-listener.dart index e07a2430b9..add5c908dd 100644 --- a/source/examples/generated/flutter/react_to_changes_test.snippet.realm-list-change-listener.dart +++ b/source/examples/generated/flutter/react_to_changes_test.snippet.realm-list-change-listener.dart @@ -1,13 +1,11 @@ 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 accounting for deletions & insertions. + 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`. }); diff --git a/source/examples/generated/flutter/react_to_changes_test.snippet.realm-object-change-listener.dart b/source/examples/generated/flutter/react_to_changes_test.snippet.realm-object-change-listener.dart index f0ad4f5931..9611cb31e8 100644 --- a/source/examples/generated/flutter/react_to_changes_test.snippet.realm-object-change-listener.dart +++ b/source/examples/generated/flutter/react_to_changes_test.snippet.realm-object-change-listener.dart @@ -1,5 +1,5 @@ final frodoSubscription = frodo.changes.listen((changes) { - changes.isDeleted; // if the object has been deleted - changes.object; // the RealmObject being listened to, `frodo` - changes.properties; // the changed properties + changes.isDeleted; // If the object has been deleted. + changes.object; // The RealmObject being listened to, `frodo`. + changes.properties; // The changed properties. }); diff --git a/source/sdk/flutter/realm-database/react-to-changes.txt b/source/sdk/flutter/realm-database/react-to-changes.txt index 5587b70859..dca945152d 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,24 +37,27 @@ 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 +.. literalinclude:: /examples/generated/flutter/react_to_changes_test.snippet.sample-data-models.dart + :language: dart - The examples have this sample data: +Additionally, the examples have this sample data: - .. literalinclude:: /examples/generated/flutter/react_to_changes_test.snippet.sample-data-seed.dart - :language: dart +.. literalinclude:: /examples/generated/flutter/react_to_changes_test.snippet.sample-data-seed.dart + :language: dart +Register a Listener +------------------- .. _flutter-query-change-listener: Register a Query Change Listener --------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can register a notification handler on any query within a Realm. The handler receives a :flutter-sdk:`RealmResultsChanges ` object, @@ -63,6 +65,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 +97,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 @@ -103,7 +106,7 @@ which includes description of changes since the last notification. .. _flutter-realm-object-change-listener: Register a RealmObject Change Listener --------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can register a notification handler on a specific object within a realm. Realm notifies your handler when any of the object's properties change. @@ -112,6 +115,7 @@ which includes description of changes since the last notification. ``RealmObjectChanges`` contains the following properties: .. list-table:: + :widths: 20 30 50 * - Property - Type @@ -136,7 +140,7 @@ which includes description of changes since the last notification. .. _flutter-realm-set-change-listener: Register Collection Change Listeners ------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionchanged:: 1.7.0 Added support for ``RealmMap`` change listeners. @@ -144,14 +148,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 +179,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 +230,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 +253,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,35 +279,47 @@ 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 .. _flutter-user-change-listener: 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