lockEvents method

  1. @protected
Future<void> lockEvents(
  1. Future<void> callback()
)

Locks the dispatching of asynchronous events and callbacks until the callback's future completes.

This causes input lag and should therefore be avoided when possible. It is primarily intended for use during non-user-interactive time such as to allow reassembleApplication to block input while it walks the tree (which it partially does asynchronously).

The Future returned by the callback argument is returned by lockEvents.

The gestures binding wraps PlatformDispatcher.onPointerDataPacket in logic that honors this event locking mechanism. Similarly, tasks queued using SchedulerBinding.scheduleTask will only start when events are not locked.

Implementation

@protected
Future<void> lockEvents(Future<void> Function() callback) {
  developer.TimelineTask? debugTimelineTask;
  if (!kReleaseMode) {
    debugTimelineTask = developer.TimelineTask()..start('Lock events');
  }

  _lockCount += 1;
  final Future<void> future = callback();
  future.whenComplete(() {
    _lockCount -= 1;
    if (!locked) {
      if (!kReleaseMode) {
        debugTimelineTask!.finish();
      }
      try {
        unlocked();
      } catch (error, stack) {
        FlutterError.reportError(FlutterErrorDetails(
          exception: error,
          stack: stack,
          library: 'foundation',
          context: ErrorDescription('while handling pending events'),
        ));
      }
    }
  });
  return future;
}