SemanticZoomController class

Drives a semantic zoom: a continuous zoom value (e.g. 0.0 → 2.0), the discrete level it last settled on, and optional per-item levels.

zoom changes every frame during a pinch; listen to it only from paint or animation code. The controller itself (a ChangeNotifier) notifies only when a committed level changes (the global level or an itemLevel), which is the right hook for persistence, analytics or state management.

Inheritance

Constructors

SemanticZoomController({required TickerProvider vsync, int levelCount = 3, int initialLevel = 0, SpringDescription? spring, List<String>? levelLabels})
Creates a controller with levelCount discrete levels.

Properties

hashCode → int
The hash code for this object.
no setterinherited
hasItemLevels → bool
Whether any item has a level different from the global level.
no setter
hasListeners → bool
Whether any listeners are currently registered.
no setterinherited
isAnimating → bool
Whether a global settle animation is running.
no setter
itemLevels → Map<Object, int>
Items whose level differs from the global level, by item id.
no setter
level → int
The level the zoom last settled on (or is settling towards).
no setter
levelCount → int
Number of discrete levels. Levels are 0 .. levelCount - 1.
final
levelLabels → List<String>?
Optional screen-reader names for each level.
final
maxLevel → int
Highest level index.
no setter
reduceMotion ↔ bool
When true, level changes jump instead of animating. The detector keeps this in sync with MediaQuery.disableAnimations.
getter/setter pair
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
spring → SpringDescription
Spring used by animateToLevel and setItemLevel.
final
value ↔ double
Current continuous zoom value.
getter/setter pair
zoom → Animation<double>
Continuous zoom value. Can briefly exceed 0..maxLevel while rubber-banding.
no setter

Methods

addAnchorClient(SemanticZoomAnchorClient client) → void
Registers a client that keeps content anchored. Called by render objects on attach.
addListener(VoidCallback listener) → void
Register a closure to be called when the object changes.
inherited
anchorAt(Offset globalPosition) → void
Pins the item under globalPosition in every attached list.
anchorLeading() → void
Pins the first visible item in every attached list.
animateToLevel(int target, {double velocity = 0, bool anchor = true, bool? animate}) → Future<void>
Settles every item on target with a spring, carrying velocity (levels/second). Per-item levels are cleared.
beginGesture(Offset focalPoint) → void
Starts a gesture at focalPoint: stops settling, anchors there and returns every item to the global level.
clearItemLevels({bool? animate}) → void
Returns every item to the global level.
dispose() → void
Discards any resources used by the object.
override
endGesture({required double projected, double velocity = 0}) → Future<void>
Ends a gesture, settling on the level projected rounds to.
holdAnchor() → VoidCallback
Keeps the first visible item still until the returned callback is called, for example while an item above it grows because its content finished loading. Holds can overlap; the anchor is released when the last one is. A pinch or level change that starts meanwhile takes over the anchor and releases it itself.
itemLevel(Object id) → int
The committed level of item id: its own level if one was set with setItemLevel, otherwise the global level.
jumpToLevel(int target) → void
Jumps to target without animation.
labelForLevel(int level) → String
Screen-reader text for level.
listenableFor(Object? id) → Listenable
What to listen to for item id's zoom (the global zoom if null).
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners() → void
Call all the registered listeners.
inherited
releaseAnchor() → void
Stops anchoring after the current frame is laid out.
removeAnchorClient(SemanticZoomAnchorClient client) → void
Unregisters an anchor client.
removeListener(VoidCallback listener) → void
Remove a previously registered closure from the list of closures that are notified when the object changes.
inherited
restoreItemLevels(Map<Object, int> levels) → void
Sets item levels immediately, without animating. The counterpart of restoreLevel for itemLevels; listeners are notified after the current frame.
restoreLevel(int level) → void
Sets the level immediately, without animating or anchoring. Meant for restoring saved state while the list is first built (the widgets' restorationId uses it); use jumpToLevel otherwise.
setItemLevel(Object id, int target, {bool? animate}) → void
Moves only item id to target, e.g. on tap. Other items keep the global level. The next pinch or animateToLevel clears it.
stop() → void
Stops any settle animation, e.g. when a new gesture begins.
toString() → String
A string representation of this object.
inherited
valueFor(Object? id) → double
Continuous zoom value for item id (the global value if null).

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Static Properties

defaultSpring → SpringDescription
Slightly under-damped spring used when settling on a level.
final