AppFocusManager class Managers

Tracks whether the app is in the foreground, so a mounted QueryClient can refetch stale queries when the user comes back (the refetchOnWindowFocus option) and resume work paused in the background.

Each client owns one, as QueryClient.focusManager. Pure Dart has no notion of focus, so the default is "focused". Nothing is installed for you: changes arrive through setFocused — the Flutter binding's QueryClientProvider maps every AppLifecycleState onto it — or through a setEventListener adapter of your own, for a focus source that is not the app lifecycle.

// By hand, e.g. from a desktop window's focus events:
client.focusManager.setFocused(false);
client.focusManager.setFocused(true); // refetches stale observed queries

// Or with an adapter over some event source:
client.focusManager.setEventListener((setFocused) {
  final subscription = windowFocus.listen(setFocused);
  return subscription.cancel;
});

The two are alternatives, not layers. A setEventListener adapter writes through setFocused exactly as the binding's lifecycle listener does, so with both installed the last writer wins and neither can see the other's verdict. Installing your own adapter therefore goes with QueryClientProvider(observeAppLifecycle: false), which is what turns the lifecycle source off. This mirrors TanStack Query, where the browser's visibilitychange listener is the built-in default and setEventListener is what a React Native app calls with AppState.

Constructors

AppFocusManager({Duration refetchMinBackgroundDuration = Duration.zero})
Creates a manager. refetchMinBackgroundDuration (default zero) suppresses new focus refetches after shorter absences, without blocking paused work resuming. Throws ArgumentError if it is negative.

Properties

hashCode → int
The hash code for this object.
no setterinherited
hasListeners → bool
Whether at least one listener is registered — what tells a manager to keep its platform event source installed.
no setterinherited
listeners → List<void Function(bool focused)>
The listeners currently registered, in subscription order, read-only. Subclasses notifying by hand iterate this; notifyListeners is the loop that skips a listener an earlier one removed.
no setterinherited
refetchMinBackgroundDuration → Duration
Minimum time unfocused before returning to focus starts new refetches.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
shouldRefetchOnFocus → bool
Whether the current focus notification permits new refetches. Paused requests may always continue when focused, regardless of this value.
no setter

Methods

isFocused() → bool
Whether the app is currently in the foreground. Reads the value last set by setFocused, or true when nothing has been set — pure Dart cannot tell, so it assumes the best case.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
notifyListeners(void deliver(void listener(bool focused))) → void
Calls every listener through deliver. See ListenerRegistry.notify: a listener an earlier one removed is skipped, and a throw is reported to the zone rather than escaping into whatever produced the event.
inherited
onFocus({bool refetchQueries = true}) → void
Notifies every listener with the current state. refetchQueries controls new refetches only, never continuation of paused work.
onSubscribe() → void
Reinstalls the event source the last listener's departure tore down.
onUnsubscribe() → void
Called after every unsubscribe. Subclasses use it to tear their event source down once hasListeners turns false.
setEventListener(FocusSetup setup) → void
Replaces the source of focus events.
setFocused(bool? focused) → void
Sets the focus state by hand. Passing null forgets the value set by hand, and isFocused then answers true — pure Dart has nothing to consult (TanStack Query reads document.visibilityState here). An installed event listener reports through this same method (or through onFocus, for a report that is not a bool), so its next report overwrites a value set by hand.
subscribe(void listener(bool focused)) → void Function()
Registers listener and returns the function that removes it again.
inherited
toString() → String
A string representation of this object.
inherited

Operators

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