debug.dart 2.57 KB
Newer Older
Ian Hickson's avatar
Ian Hickson committed
1
// Copyright 2014 The Flutter Authors. All rights reserved.
2 3 4
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5 6 7 8 9
import 'package:flutter/foundation.dart';

// Any changes to this file should be reflected in the debugAssertAllSchedulerVarsUnset()
// function below.

10
/// Print a banner at the beginning of each frame.
11 12
///
/// Frames triggered by the engine and handler by the scheduler binding will
13
/// have a banner giving the frame number and the time stamp of the frame.
14 15
///
/// Frames triggered eagerly by the widget framework (e.g. when calling
16 17 18
/// [runApp]) will have a label saying "warm-up frame" instead of the time stamp
/// (the time stamp sent to frame callbacks in that case is the time of the last
/// frame, or 0:00 if it is the first frame).
19 20 21 22 23
///
/// To include a banner at the end of each frame as well, to distinguish
/// intra-frame output from inter-frame output, set [debugPrintEndFrameBanner]
/// to true as well.
///
24 25 26 27 28 29 30 31
/// See also:
///
///  * [debugProfilePaintsEnabled], which does something similar for
///    painting but using the timeline view.
///  * [debugPrintLayouts], which does something similar for layout but using
///    console output.
///  * The discussions at [WidgetsBinding.drawFrame] and at
///    [SchedulerBinding.handleBeginFrame].
32
bool debugPrintBeginFrameBanner = false;
33 34 35 36 37 38

/// Print a banner at the end of each frame.
///
/// Combined with [debugPrintBeginFrameBanner], this can be helpful for
/// determining if code is running during a frame or between frames.
bool debugPrintEndFrameBanner = false;
39

40 41
/// Log the call stacks that cause a frame to be scheduled.
///
42
/// This is called whenever [SchedulerBinding.scheduleFrame] schedules a frame. This
43 44 45 46 47 48 49 50
/// can happen for various reasons, e.g. when a [Ticker] or
/// [AnimationController] is started, or when [RenderObject.markNeedsLayout] is
/// called, or when [State.setState] is called.
///
/// To get a stack specifically when widgets are scheduled to be built, see
/// [debugPrintScheduleBuildForStacks].
bool debugPrintScheduleFrameStacks = false;

51 52 53 54 55
/// Returns true if none of the scheduler library debug variables have been changed.
///
/// This function is used by the test framework to ensure that debug variables
/// haven't been inadvertently changed.
///
56 57
/// See [the scheduler library](scheduler/scheduler-library.html) for a complete
/// list.
58 59 60 61
bool debugAssertAllSchedulerVarsUnset(String reason) {
  assert(() {
    if (debugPrintBeginFrameBanner ||
        debugPrintEndFrameBanner) {
62
      throw FlutterError(reason);
63 64
    }
    return true;
65
  }());
66 67
  return true;
}