
# デバッグオーバーレイ

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

## 使う理由

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

## 例

```yaml
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` はタブバーの上です。

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

## ドラッグ

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

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

- **マウス**では、オーバーレイはすぐにドラッグできます。カーソルが移動できることを示します。
- **タッチスクリーン**では、長押しの後にドラッグします。そのため、タップとページ間のスワイプはこれまで通りです。
- **`snap: corners`** (デフォルト): ドロップすると、最も近い隅に入り、その隅のスタックまたはページに加わります。
- **`snap: free`**: ドロップした場所にとどまり、画面内に保たれます。
- **`remember`**: 場所は次の起動まで保持されます。選んだテーマが保持されるのと同じ仕組みです (Web ではブラウザーのストレージ、デバイスではファイル)。オーバーレイが移動されるまでは、設定の隅がその場所です。

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

## 独自のオーバーレイ

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

```dart
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` | 移動したオーバーレイが、再起動後も置いた場所にあるかどうか |

## 関連項目

- [フレームメーター](frame-meter.md)
- [タイムライン](timeline.md)
- [デバッグパネル](debug-panel.md)
