# 機能設計書 248-SaveIniSettingsToDisk

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるSaveIniSettingsToDisk関数の機能設計について記述する。この関数はImGuiの設定をディスク上のINIファイルに保存するためのユーティリティ関数である。

### 本機能の処理概要

SaveIniSettingsToDisk関数は、ImGuiの現在の状態（ウィンドウ位置、サイズ、折りたたみ状態など）をINI形式でディスクに保存する機能を提供する。io.IniFilenameが設定されている場合は自動的に呼び出されるが、手動での保存にも使用できる。

**業務上の目的・背景**：アプリケーションの状態永続化は、ユーザー体験の向上に不可欠である。ユーザーがカスタマイズしたウィンドウのレイアウト、サイズ、位置などを保存することで、次回起動時に同じ作業環境を復元できる。この関数は、そのような設定の保存機能を提供する。

**機能の利用シーン**：アプリケーション終了時の設定保存、ユーザーによる明示的な設定保存操作、定期的な自動保存、設定エクスポート機能などに使用される。

**主要な処理内容**：
1. ダーティタイマーをリセット（保存完了を示す）
2. ファイル名がNULLの場合は何もせず復帰
3. SaveIniSettingsToMemoryでINIデータを生成
4. ファイルをオープンしてデータを書き込み
5. ファイルをクローズ

**関連システム・外部連携**：ファイルシステムにアクセスしてINIファイルを書き込む。ImFileOpen/ImFileWrite/ImFileClose関数を使用してプラットフォーム非依存のファイル書き込みを行う。

**権限による制御**：本機能に権限による制御は存在しない。ただし、OSレベルでファイル書き込み権限が必要となる場合がある。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全ウィンドウ | 主機能 | ウィンドウ位置・サイズの保存 |

## 機能種別

書込処理 / ファイル出力 / 設定保存

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ini_filename | const char* | Yes | 保存するINIファイルのパス | - |

### 入力データソース

- ImGuiContext内の設定データ（ウィンドウ位置、サイズ等）
- 各ImGuiSettingsHandlerからの設定データ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | void | 戻り値なし |

### 出力先

- ディスク上のINIファイル
- デフォルトファイル名は"imgui.ini"（io.IniFilenameで設定）

## 処理フロー

### 処理シーケンス

```
1. ダーティタイマーリセット
   └─ g.SettingsDirtyTimer = 0.0f
2. ファイル名確認
   └─ NULLの場合は早期リターン
3. INIデータ生成
   └─ SaveIniSettingsToMemory(&ini_data_size)
4. ファイルオープン
   └─ ImFileOpen(ini_filename, "wt")
5. データ書き込み
   └─ ImFileWrite(ini_data, sizeof(char), ini_data_size, f)
6. ファイルクローズ
   └─ ImFileClose(f)
```

### フローチャート

```mermaid
flowchart TD
    A[SaveIniSettingsToDisk呼び出し] --> B[g.SettingsDirtyTimer = 0.0f]
    B --> C{ini_filename != NULL?}
    C -->|No| D[return]
    C -->|Yes| E[SaveIniSettingsToMemory呼び出し]
    E --> F[ImFileOpen - ファイルオープン]
    F --> G{ファイルオープン成功?}
    G -->|No| D
    G -->|Yes| H[ImFileWrite - データ書き込み]
    H --> I[ImFileClose - ファイルクローズ]
    I --> J[終了]
    D --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-248-1 | 自動保存 | io.IniFilename != NULLで変更後数秒で自動保存 | 設定変更時 |
| BR-248-2 | DestroyContext時保存 | コンテキスト破棄時にも自動呼び出しされる | コンテキスト終了時 |
| BR-248-3 | ダーティフラグ | 設定変更時にSettingsDirtyTimerが設定される | 設定変更時 |
| BR-248-4 | 相対パス注意 | デフォルト"imgui.ini"は現在の作業ディレクトリ相対 | パス指定時 |

### 計算ロジック

特別な計算処理は行わない。SaveIniSettingsToMemoryでデータ生成後、ファイルに書き込む。

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイルオープン失敗 | 書き込み権限がない、パスが無効 | 何もせずに復帰（エラーは報告されない） |
| - | コンテキスト未初期化 | GImGuiがNULL | CreateContext()を先に呼び出す |

### リトライ仕様

リトライ処理は不要。ファイル書き込み失敗時は無視される。

## トランザクション仕様

本機能はトランザクション処理を行わない。ファイル書き込み中に中断すると不完全なファイルが残る可能性がある。

## パフォーマンス要件

- 処理時間: 設定量とディスクI/O性能に依存
- メモリ使用: INIデータサイズに比例（SaveIniSettingsToMemory経由）
- 呼び出し頻度: 設定変更後数秒に1回（自動保存時）

## セキュリティ考慮事項

- INIファイルにはユーザーのウィンドウレイアウト情報が含まれる
- ファイルパスの検証は呼び出し元の責任
- 書き込み先ディレクトリのアクセス権限を確認

## 備考

- 絶対パスの使用が推奨される（デフォルトの"imgui.ini"は相対パス）
- io.IniFilenameをNULLに設定することで自動保存を無効化できる
- 手動でINI設定を管理する場合はio.WantSaveIniSettingsフラグを監視

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

INI設定の保存に関連するデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiContext::SettingsDirtyTimer - 保存トリガーの管理 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiContext::SettingsIniData - INIデータバッファ |
| 1-3 | imgui.h | `imgui.h` | ImGuiIO::WantSaveIniSettings - 手動保存時のフラグ |

**読解のコツ**: SettingsDirtyTimerは設定変更時に設定され、時間経過で減少する。0になると保存処理がトリガーされる。

#### Step 2: エントリーポイントを理解する

関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | SaveIniSettingsToDisk関数の実装（15471-15485行目） |

**主要処理フロー**:
1. **15473行目**: グローバルコンテキスト取得
2. **15474行目**: g.SettingsDirtyTimer = 0.0f でダーティフラグをクリア
3. **15475-15476行目**: ファイル名がNULLの場合は早期リターン
4. **15478-15479行目**: SaveIniSettingsToMemoryでINIデータを生成
5. **15480行目**: ファイルをテキストモードでオープン
6. **15481-15482行目**: オープン失敗時は早期リターン
7. **15483行目**: データを書き込み
8. **15484行目**: ファイルをクローズ

#### Step 3: 呼び出される関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | SaveIniSettingsToMemory関数（15488-15499行目）- INIデータ生成 |
| 3-2 | imgui.cpp | `imgui.cpp` | ImFileOpen/ImFileWrite/ImFileClose - ファイル操作 |

### プログラム呼び出し階層図

```
SaveIniSettingsToDisk(ini_filename)
    │
    ├─ g.SettingsDirtyTimer = 0.0f
    │
    ├─ SaveIniSettingsToMemory(&ini_data_size)
    │      │
    │      └─ foreach (SettingsHandler)
    │             └─ WriteAllFn() - 書き込みコールバック
    │
    ├─ ImFileOpen(ini_filename, "wt")
    │
    ├─ ImFileWrite(ini_data, sizeof(char), ini_data_size, f)
    │
    └─ ImFileClose(f)
```

### データフロー図

```
[入力]                      [処理]                         [出力]

ImGuiContext               SaveIniSettingsToDisk()        INIファイル
    │                            │                           │
    ├─ SettingsWindows ─────────▶ │                           │
    ├─ SettingsHandlers ────────▶ │ SaveIniSettingsToMemory() │
    └─ その他設定 ───────────────▶ │         │                 │
                                  │         ▼                 │
                                  │ INIテキスト生成           │
                                  │         │                 │
                                  │         ▼                 │
                                  │ ファイル書き込み ─────────▶ imgui.ini
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言 |
| imgui.cpp | `imgui.cpp` | ソース | SaveIniSettingsToDisk/ToMemory実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ImGuiContext::SettingsDirtyTimer定義 |
| imgui.ini | `imgui.ini` | 設定ファイル | 出力される設定ファイル |
