addPostFrameCallback method

void addPostFrameCallback(
  1. FrameCallback callback, {
  2. String debugLabel = 'callback',
})

Schedule a callback for the end of this frame.

The provided callback is run immediately after a frame, just after the persistent frame callbacks (which is when the main rendering pipeline has been flushed).

This method does not request a new frame. If a frame is already in progress and the execution of post-frame callbacks has not yet begun, then the registered callback is executed at the end of the current frame. Otherwise, the registered callback is executed after the next frame (whenever that may be, if ever).

The callbacks are executed in the order in which they have been added.

Post-frame callbacks cannot be unregistered. They are called exactly once.

In debug mode, if debugTracePostFrameCallbacks is set to true, then the registered callback will show up in the timeline events chart, which can be viewed in DevTools. In that case, the debugLabel argument specifies the name of the callback as it will appear in the timeline. In profile and release builds, post-frame are never traced, and the debugLabel argument is ignored.

See also:

  • scheduleFrameCallback, which registers a callback for the start of the next frame.
  • WidgetsBinding.drawFrame, which explains the phases of each frame for those apps that use Flutter widgets (and where post frame callbacks fit into those phases).

Implementation

void addPostFrameCallback(FrameCallback callback, {String debugLabel = 'callback'}) {
  assert(() {
    if (debugTracePostFrameCallbacks) {
      final FrameCallback originalCallback = callback;
      callback = (Duration timeStamp) {
        Timeline.startSync(debugLabel);
        try {
          originalCallback(timeStamp);
        } finally {
          Timeline.finishSync();
        }
      };
    }
    return true;
  }());
  _postFrameCallbacks.add(callback);
}