[listen] Creates listen package #24
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| .children | ||
| .project | ||
| .DS_Store | ||
| packages | ||
| pubspec.lock | ||
| .pub | ||
| .packages | ||
| .dart_tool | ||
| .idea |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| # Below is a list of people and organizations that have contributed | ||
| # to the project. Names should be added to the list like so: | ||
| # | ||
| # Name/Organization <email address> | ||
|
|
||
| Google Inc. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| ## 1.0.0-beta.1 | ||
|
|
||
| - Adjusts source code to be publishable. | ||
| - Moves source code from `flutter/flutter` to `flutter/core-packages`. | ||
|
Collaborator
There was a problem hiding this comment. This isn't just a move, it's an extraction as a stand-alone package. We should clarify what the full scope of the change is.
Collaborator
There was a problem hiding this comment. I just realized that changing this would require a new CLA override. Feel free to just adjust in in the next PR to this package.
Author
There was a problem hiding this comment. updated since i will have to squash new commits into a single one and will require a CLA override anyway |
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,25 @@ | ||
| Copyright 2013 The Flutter Authors | ||
|
|
||
| Redistribution and use in source and binary forms, with or without modification, | ||
| are permitted provided that the following conditions are met: | ||
|
|
||
| * Redistributions of source code must retain the above copyright | ||
| notice, this list of conditions and the following disclaimer. | ||
| * Redistributions in binary form must reproduce the above | ||
| copyright notice, this list of conditions and the following | ||
| disclaimer in the documentation and/or other materials provided | ||
| with the distribution. | ||
| * Neither the name of Google Inc. nor the names of its | ||
| contributors may be used to endorse or promote products derived | ||
| from this software without specific prior written permission. | ||
|
|
||
| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND | ||
| ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED | ||
| WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE | ||
| DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR | ||
| ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES | ||
| (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; | ||
| LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON | ||
| ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | ||
| (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS | ||
| SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| <?code-excerpt path-base="example/lib"?> | ||
|
|
||
| # listen | ||
|
|
||
| A package to notify state changes to interested listeners in pure Dart. | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Using ValueNotifier | ||
|
|
||
| `ValueNotifier` wraps a single value and notifies listeners whenever the value changes: | ||
|
|
||
| <?code-excerpt "readme_excerpts.dart (ValueNotifier)"?> | ||
| ```dart | ||
| void valueNotifierExample() { | ||
| final counter = ValueNotifier<int>(0); | ||
|
|
||
| counter.addListener(() { | ||
| print('Value changed: ${counter.value}'); | ||
| }); | ||
|
|
||
| counter.value = 5; // Prints: Value changed: 5 | ||
| counter.value = 10; // Prints: Value changed: 10 | ||
| counter.value = 10; // Does not print because the value is == 10 | ||
|
|
||
| counter.dispose(); | ||
| } | ||
|
|
||
| ``` | ||
|
|
||
| ### Using ChangeNotifier | ||
|
|
||
| Extend or mix in `ChangeNotifier` to manage state and notify listeners manually: | ||
|
|
||
| <?code-excerpt "readme_excerpts.dart (ChangeNotifierClass)"?> | ||
| ```dart | ||
| /// A [ChangeNotifier] subclass that encapsulates a list of items and notifies | ||
| /// listeners whenever items are added or removed. | ||
| class ItemListNotifier extends ChangeNotifier { | ||
| final List<String> _items = <String>[]; | ||
|
|
||
| /// The unmodifiable list of current items. | ||
| List<String> get items => List<String>.unmodifiable(_items); | ||
|
|
||
| /// Adds an [item] to the list and notifies listeners. | ||
| void addItem(String item) { | ||
| _items.add(item); | ||
| notifyListeners(); | ||
| } | ||
|
|
||
| /// Removes an [item] from the list and notifies listeners if it was present. | ||
| void removeItem(String item) { | ||
| if (_items.remove(item)) { | ||
| notifyListeners(); | ||
| } | ||
| } | ||
| } | ||
|
|
||
| ``` | ||
|
|
||
| Then, listen to changes and update state: | ||
|
|
||
| <?code-excerpt "readme_excerpts.dart (ChangeNotifierUsage)"?> | ||
| ```dart | ||
| void changeNotifierExample() { | ||
| final listNotifier = ItemListNotifier(); | ||
|
|
||
| listNotifier.addListener(() { | ||
| print('Current items: ${listNotifier.items}'); | ||
| }); | ||
|
|
||
| listNotifier.addItem('Apple'); // Prints: Current items: [Apple] | ||
| listNotifier.addItem('Banana'); // Prints: Current items: [Apple, Banana] | ||
| listNotifier.removeItem('Apple'); // Prints: Current items: [Banana] | ||
|
|
||
| listNotifier.dispose(); | ||
| } | ||
|
|
||
| ``` | ||
|
|
||
| ### Merging listenables | ||
|
|
||
| Use `Listenable.merge` to listen to multiple objects simultaneously: | ||
|
|
||
| <?code-excerpt "readme_excerpts.dart (Merge)"?> | ||
| ```dart | ||
| void mergeExample() { | ||
| final first = ValueNotifier<String>('Hello'); | ||
| final second = ValueNotifier<String>('World'); | ||
|
|
||
| final merged = Listenable.merge(<Listenable>[first, second]); | ||
|
|
||
| merged.addListener(() { | ||
| print('Merged listenable triggered: ${first.value} ${second.value}'); | ||
| }); | ||
|
|
||
| first.value = 'Hi'; // Prints: Merged listenable triggered: Hi World | ||
| second.value = 'Dart'; // Prints: Merged listenable triggered: Hi Dart | ||
|
|
||
| first.dispose(); | ||
| second.dispose(); | ||
| } | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| // Copyright 2013 The Flutter Authors | ||
| // Use of this source code is governed by a BSD-style license that can be | ||
| // found in the LICENSE file. | ||
|
|
||
| // ignore_for_file: avoid_print | ||
|
|
||
| import 'package:listen/listen.dart'; | ||
|
|
||
| /// A simple counter that extends [ChangeNotifier] to notify listeners | ||
| /// whenever its value changes. | ||
| class Counter extends ChangeNotifier { | ||
| int _count = 0; | ||
|
|
||
| /// The current count value. | ||
| int get count => _count; | ||
|
|
||
| /// Increments the count by one and notifies listeners. | ||
| void increment() { | ||
| _count++; | ||
| notifyListeners(); | ||
| } | ||
| } | ||
|
|
||
| void main() { | ||
| final counter = Counter(); | ||
|
|
||
| counter.addListener(() { | ||
| print('Counter value changed to: ${counter.count}'); | ||
| }); | ||
|
|
||
| counter.increment(); // Prints: Counter value changed to: 1 | ||
| counter.increment(); // Prints: Counter value changed to: 2 | ||
|
|
||
| counter.dispose(); | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| // Copyright 2013 The Flutter Authors | ||
| // Use of this source code is governed by a BSD-style license that can be | ||
| // found in the LICENSE file. | ||
|
|
||
| // ignore_for_file: avoid_print | ||
|
|
||
| import 'package:listen/listen.dart'; | ||
|
|
||
| /// A [ChangeNotifier] subclass that encapsulates a list of items and notifies | ||
| /// listeners whenever items are added or removed. | ||
| class ItemListNotifier extends ChangeNotifier { | ||
| final List<String> _items = <String>[]; | ||
|
|
||
| /// The unmodifiable list of current items. | ||
| List<String> get items => List<String>.unmodifiable(_items); | ||
|
|
||
| /// Adds an [item] to the list and notifies listeners. | ||
| void addItem(String item) { | ||
| _items.add(item); | ||
| notifyListeners(); | ||
| } | ||
|
|
||
| /// Removes an [item] from the list and notifies listeners if it was present. | ||
| void removeItem(String item) { | ||
| if (_items.remove(item)) { | ||
| notifyListeners(); | ||
| } | ||
| } | ||
| } | ||
|
|
||
| void main() { | ||
| final listNotifier = ItemListNotifier(); | ||
|
|
||
| listNotifier.addListener(() { | ||
| print('Current items: ${listNotifier.items}'); | ||
| }); | ||
|
|
||
| listNotifier.addItem('Apple'); // Prints: Current items: [Apple] | ||
| listNotifier.addItem('Banana'); // Prints: Current items: [Apple, Banana] | ||
| listNotifier.removeItem('Apple'); // Prints: Current items: [Banana] | ||
|
|
||
| listNotifier.dispose(); | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| // Copyright 2013 The Flutter Authors | ||
| // Use of this source code is governed by a BSD-style license that can be | ||
| // found in the LICENSE file. | ||
|
|
||
| // ignore_for_file: avoid_print | ||
|
|
||
| import 'package:listen/listen.dart'; | ||
|
|
||
| void main() { | ||
| final first = ValueNotifier<String>('Hello'); | ||
| final second = ValueNotifier<String>('World'); | ||
|
|
||
| final merged = Listenable.merge(<Listenable>[first, second]); | ||
|
|
||
| merged.addListener(() { | ||
| print('Merged listenable triggered: ${first.value} ${second.value}'); | ||
| }); | ||
|
|
||
| first.value = 'Hi'; // Prints: Merged listenable triggered: Hi World | ||
| second.value = 'Dart'; // Prints: Merged listenable triggered: Hi Dart | ||
|
|
||
| first.dispose(); | ||
| second.dispose(); | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| // Copyright 2013 The Flutter Authors | ||
| // Use of this source code is governed by a BSD-style license that can be | ||
| // found in the LICENSE file. | ||
|
|
||
| // ignore_for_file: avoid_print | ||
|
|
||
| import 'package:listen/listen.dart'; | ||
|
|
||
| void main() { | ||
| final counter = ValueNotifier<int>(0); | ||
|
|
||
| counter.addListener(() { | ||
| print('Counter changed to: ${counter.value}'); | ||
| }); | ||
|
|
||
| counter.value = 1; // Prints: Counter changed to: 1 | ||
| counter.value = 2; // Prints: Counter changed to: 2 | ||
|
|
||
| counter.dispose(); | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,91 @@ | ||
| // Copyright 2013 The Flutter Authors | ||
| // Use of this source code is governed by a BSD-style license that can be | ||
| // found in the LICENSE file. | ||
|
|
||
| // This file exists solely to host compiled excerpts for README.md, and is not | ||
| // intended for use as an actual example application. | ||
|
|
||
| // ignore_for_file: avoid_print | ||
|
|
||
| import 'package:listen/listen.dart'; | ||
|
|
||
| /// Demonstrates [ValueNotifier] usage for README. | ||
| // #docregion ValueNotifier | ||
| void valueNotifierExample() { | ||
|
Collaborator
There was a problem hiding this comment. Is there a reason this is duplicated almost exactly here from
Author
There was a problem hiding this comment. That will require adding the #docregion identifier on the main.dart, which I think may be confusing for people looking at the example. so I intentionally group all excerpt related code in one file even if I can probably grab the code from some other example. Let me know reducing duplication here is more preferred.
Collaborator
There was a problem hiding this comment. Traditionally we haven't worried about having it in main.dart, and only use readme_excerpts.dart when there were things we wanted to show in the README that weren't in the example. It's not a rule though, so if you are concerned about the comments in the example this is fine. |
||
| final counter = ValueNotifier<int>(0); | ||
|
|
||
| counter.addListener(() { | ||
| print('Value changed: ${counter.value}'); | ||
| }); | ||
|
|
||
| counter.value = 5; // Prints: Value changed: 5 | ||
| counter.value = 10; // Prints: Value changed: 10 | ||
| counter.value = 10; // Does not print because the value is == 10 | ||
|
|
||
| counter.dispose(); | ||
| } | ||
|
|
||
| // #enddocregion ValueNotifier | ||
|
|
||
| // #docregion ChangeNotifierClass | ||
| /// A [ChangeNotifier] subclass that encapsulates a list of items and notifies | ||
| /// listeners whenever items are added or removed. | ||
| class ItemListNotifier extends ChangeNotifier { | ||
| final List<String> _items = <String>[]; | ||
|
|
||
| /// The unmodifiable list of current items. | ||
| List<String> get items => List<String>.unmodifiable(_items); | ||
|
|
||
| /// Adds an [item] to the list and notifies listeners. | ||
| void addItem(String item) { | ||
| _items.add(item); | ||
| notifyListeners(); | ||
| } | ||
|
|
||
| /// Removes an [item] from the list and notifies listeners if it was present. | ||
| void removeItem(String item) { | ||
| if (_items.remove(item)) { | ||
| notifyListeners(); | ||
| } | ||
| } | ||
| } | ||
|
|
||
| // #enddocregion ChangeNotifierClass | ||
|
|
||
| /// Demonstrates [ChangeNotifier] usage for README. | ||
| // #docregion ChangeNotifierUsage | ||
| void changeNotifierExample() { | ||
| final listNotifier = ItemListNotifier(); | ||
|
|
||
| listNotifier.addListener(() { | ||
| print('Current items: ${listNotifier.items}'); | ||
| }); | ||
|
|
||
| listNotifier.addItem('Apple'); // Prints: Current items: [Apple] | ||
| listNotifier.addItem('Banana'); // Prints: Current items: [Apple, Banana] | ||
| listNotifier.removeItem('Apple'); // Prints: Current items: [Banana] | ||
|
|
||
| listNotifier.dispose(); | ||
| } | ||
|
|
||
| // #enddocregion ChangeNotifierUsage | ||
|
|
||
| /// Demonstrates [Listenable.merge] usage for README. | ||
| // #docregion Merge | ||
| void mergeExample() { | ||
| final first = ValueNotifier<String>('Hello'); | ||
| final second = ValueNotifier<String>('World'); | ||
|
|
||
| final merged = Listenable.merge(<Listenable>[first, second]); | ||
|
|
||
| merged.addListener(() { | ||
| print('Merged listenable triggered: ${first.value} ${second.value}'); | ||
| }); | ||
|
|
||
| first.value = 'Hi'; // Prints: Merged listenable triggered: Hi World | ||
| second.value = 'Dart'; // Prints: Merged listenable triggered: Hi Dart | ||
|
|
||
| first.dispose(); | ||
| second.dispose(); | ||
| } | ||
| // #enddocregion Merge | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We never do releases like this, so I'm not entirely sure our CI will handle it correctly. It looks like presubmit is fine, so fingers crossed, but be sure to verify that publishing actually worked after it lands.