デバッグオーバーレイ

一部のデバッグ機能は、アプリの上に小さなウィジェットを表示します。フレームメーター と タイムライン です。debugDock がそれらを画面に置きます。各機能はどの隅に、どの順番でとだけ伝え、ドック (dock) がそれらが互いを覆わないようにします。

使う理由

一つの隅に二つのオーバーレイがあると、重なって描画されてしまいます。ノートパソコンには上下に並べる余裕がありますが、スマートフォンにはありません。ドックは隅ごとに、画面の余裕から判断し、ウィンドウのサイズが変わったりスマートフォンが回転したりすると判断を変えます。

例

spring:
  flutter:
    debug:
      frame-meter:
        enabled: true
      timeline:
        enabled: true
      overlays:
        layout: auto        # auto | stack | pages
        max-height: 0.4     # auto のための隅の余裕
        margin:
          top: 64           # アプリのヘッダーの下

spring.flutter.frame-meter.position: bottom-left で、両方のウィジェットが左下に置かれます。ノートパソコンでは上下に並び、スマートフォンでは一度に一つずつ、ドット付きで表示されます。

レイアウト

layout 隅の表示
auto (デフォルト) 収まるときは上下に並べる。高さの合計が画面の max-height 以下で、どれも画面の半分より広くない場合。そうでなければ一度に一つ
stack 常に上下に並べる
pages 常に一度に一つ

一度に一つのときは、ドットがどれかを示し、ページは次の操作で切り替えます。

上の隅は下向きに伸び、そのドットはウィジェットの下にあります。下の隅は上向きに伸び、そのドットはウィジェットの上にあります。そのため、ドットが画面の端の下に隠れることはありません。順番は各機能のものです (フレームメーターが先、次にタイムライン)。

ドックは画面のセーフエリア (ノッチ、時計) を自動的に避けます。margin はその外側に余白を加えます。単位は論理ピクセルで、top はヘッダーの下、bottom はタブバーの上です。

デバッグパネル が開いている間、オーバーレイは隠れます。パネルの各機能のセクションが同じものを表示し、パネルを何も覆わないようにするためです。

ドラッグ

オーバーレイの移動は独立したデバッグ機能で、要求したときだけビルドに含まれます。

spring:
  flutter:
    debug:
      drag:
        enabled: true       # なければ、ドラッグのコードもない
      overlays:
        drag:
          snap: corners     # corners | free
          remember: true

各オーバーレイは個別に動きます。フレームメーターは、タイムラインの隅から離れることができます。パネルの overlays セクションは、それらをすべて元に戻します。

独自のオーバーレイ

独自のデバッグ機能は、その Bean が DebugOverlay を実装すると、ドックに表示されます。

final class QueueOverlay extends ChangeNotifier implements DebugOverlay {
  @override
  String get id => 'queue';
  @override
  String get title => 'Queue';
  @override
  DebugOverlayCorner get corner => DebugOverlayCorner.topLeft;
  @override
  int get order => 20;
  @override
  Size get size => const Size(160, 40);

  bool _shown = false;
  @override
  bool get shown => _shown;
  @override
  set shown(bool value) {
    _shown = value;
    notifyListeners();
  }

  @override
  Widget build(BuildContext context) => const QueueGauge();
}

size は、それが取る余裕のおおよその大きさで、auto が合計するものです。オーバーレイを持つ機能がアプリに含まれていれば、ドックもアプリに含まれます。独自の機能は、同じ方法で debugDock Bean を宣言するか、それを宣言するものに依存します。

プロパティ

キー 型 デフォルト 意味
spring.flutter.debug.overlays.layout auto、stack、pages auto 隅のオーバーレイをどう組み合わせるか
spring.flutter.debug.overlays.max-height 割合 0.4 auto のための隅の余裕
spring.flutter.debug.overlays.margin.top / bottom / left / right 論理ピクセル 0 セーフエリアの外側の余白
spring.flutter.debug.drag.enabled bool 未設定: コードなし アプリがオーバーレイをドラッグできるかどうか (ビルドが読む)
spring.flutter.debug.overlays.drag.snap corners、free corners ドロップしたオーバーレイの行き先
spring.flutter.debug.overlays.drag.remember bool true 移動したオーバーレイが、再起動後も置いた場所にあるかどうか

関連項目