MapNotifier<K, V> class

A Map that behaves like ValueNotifier if its data changes.

Notification Modes

  • CustomNotifierMode.normal: Listeners are only notified when a value actually changes. For example, setting a key to the same value it already has will not notify listeners. No-op operations (like removing a non-existent key) also won't notify.

  • CustomNotifierMode.always: Listeners are notified on every operation, even if the value doesn't change. This ensures UI always updates when operations are attempted.

  • CustomNotifierMode.manual: No automatic notifications. You must call notifyListeners manually after making changes.

Bulk Operations

Bulk operations like addAll and addEntries always notify listeners, even with empty input, regardless of notification mode (except manual). This ensures consistent behavior and prevents subtle bugs.

Transactions

Use startTransAction and endTransAction to batch multiple operations into a single notification. This is useful for atomic updates.

Examples

// Normal mode - only notifies on actual changes
final mapNotifier = MapNotifier(
  data: {'one': 1},
  notificationMode: CustomNotifierMode.normal,
);
mapNotifier['one'] = 1;  // No notification (same value)
mapNotifier['one'] = 2;  // Notifies (value changed)
mapNotifier.remove('missing');  // No notification (key doesn't exist)

// Always mode - notifies on every operation
final alwaysMap = MapNotifier(
  data: {'one': 1},
  notificationMode: CustomNotifierMode.always,
);
alwaysMap['one'] = 1;  // Notifies even though value is same
Implemented types
Mixed-in types
Available extensions

Constructors

MapNotifier({Map<K, V>? data, CustomNotifierMode notificationMode = CustomNotifierMode.always, bool customEquality(V? x, V? y)?})
Creates a new listenable Map data optional map that should be used as initial value notificationMode determines whether to notify listeners if an equal value is assigned to a key. To not make users wonder why their UI doesn't update if they assign the same value to a key, the default is always. customEquality can be used to set your own criteria for comparing values, which might be important notificationMode is set to normal.

Properties

customEquality → bool Function(V? x, V? y)?
customEquality can be used to set your own criteria for comparing values, which might be important if notificationMode is set to normal. The function should return a bool that represents if, when compared, two values are equal. If null, the default values equality == is used.
final
entries → Iterable<MapEntry<K, V>>
The map entries of this Map.
no setterinherited
hashCode → int
The hash code for this object.
no setterinherited
hasListeners → bool
Whether any listeners are currently registered.
no setterinherited
isEmpty → bool
Whether there is no key/value pair in the map.
no setterinherited
isNotEmpty → bool
Whether there is at least one key/value pair in the map.
no setterinherited
keys → Iterable<K>
The keys of this Map.
no setterinherited
length → int
The number of key/value pairs in the map.
no setterinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
value → Map<K, V>
Returns an immutable view of the current map state.
no setteroverride
values → Iterable<V>
The values of this Map.
no setterinherited

Methods

addAll(Map<K, V> other) → void
Adds all key/value pairs of other to this map.
addEntries(Iterable<MapEntry<K, V>> entries) → void
Adds all key/value pairs of newEntries to this map.
addListener(VoidCallback listener) → void
Register a closure to be called when the object changes.
inherited
cast<K2, V2>() → Map<K2, V2>
Provides a view of this map as having RK keys and RV instances, if necessary.
inherited
clear() → void
Removes all entries from the map.
containsKey(Object? key) → bool
Whether this map contains the given key.
inherited
containsValue(Object? value) → bool
Whether this map contains the given value.
inherited
debounce(Duration timeOut) → Listenable

Available on Listenable, provided by the FunctionaListener2 extension

dispose() → void
Discards any resources used by the object. After this is called, the object is not in a usable state and should be discarded (calls to addListener will throw after the object is disposed).
inherited
endTransAction() → void
Ends a transaction
forEach(void f(K, V)) → void
Applies action to each key/value pair of the map.
inherited
listen(void handler(ListenableSubscription)) → ListenableSubscription

Available on Listenable, provided by the FunctionaListener2 extension

let you work with a Listenable as it should be by installing a handler function that is called on any value change of this and gets the new value passed as an argument. It returns a subscription object that lets you stop the handler from being called by calling cancel() on the subscription. The handler get the subscription object passed on every call so that it is possible to uninstall the handler from the handler itself.
map<K2, V2>(MapEntry<K2, V2> transform(K, V)) → Map<K2, V2>
Returns a new map where all entries of this map are transformed by the given convert function.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void
Call all the registered listeners.
override
putIfAbsent(K key, V ifAbsent()) → V
Adds key/value pair to the map if key is not already present.
remove(Object? key) → V?
Removes key and its associated value, if present, from the map.
removeListener(VoidCallback listener) → void
Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
removeWhere(bool test(K, V)) → void
Removes all entries of this map that satisfy the given test.
retype<K2, V2>() → Map<K2, V2>
inherited
startTransAction() → void
Starts a transaction that allows to make multiple changes to the Map with only one notification at the end.
toString() → String
A string representation of this object.
inherited
update(K key, V update(V), {V ifAbsent()?}) → V
Updates the value for the provided key.
updateAll(V update(K, V)) → void
Updates all values.

Operators

operator ==(Object other) → bool
The equality operator.
inherited
operator [](Object? key) → V?
The value for the given key, or null if key is not in the map.
operator []=(K key, V value) → void
Associates the key with the given value.