# 機能設計書 244-GetClipboardText

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるGetClipboardText関数の機能設計について記述する。この関数はシステムクリップボードからテキストデータを取得するためのユーティリティ関数である。

### 本機能の処理概要

GetClipboardText関数は、OSのクリップボードに保存されているテキストデータを取得する機能を提供する。プラットフォームIO（ImGuiPlatformIO）に登録されたコールバック関数を呼び出して、プラットフォーム固有のクリップボードアクセスを実行する。

**業務上の目的・背景**：テキスト編集を伴うGUIアプリケーションでは、クリップボードからのペースト操作は基本的な機能である。ユーザーは他のアプリケーションからテキストをコピーしてImGuiアプリケーション内にペーストしたり、ImGuiアプリケーション内でテキストをコピー・ペーストしたりすることができる。この関数は、そのようなクリップボード操作の基盤を提供する。

**機能の利用シーン**：InputTextウィジェットでのCtrl+Vペースト操作、カスタムテキストエディタでのペースト機能実装、クリップボードの内容を参照する必要がある場合、テキストデータのインポート機能などに使用される。

**主要な処理内容**：
1. グローバルコンテキストを取得
2. Platform_GetClipboardTextFnコールバックが登録されているか確認
3. 登録されている場合はコールバックを呼び出してテキストを取得
4. 登録されていない場合はNULLを返却

**関連システム・外部連携**：バックエンド（プラットフォーム実装）がPlatform_GetClipboardTextFnを実装し、OS固有のクリップボードAPIを呼び出す。Windows ではWin32 API、macOSではNSPasteboard、LinuxではX11/Wayland等を使用する。

**権限による制御**：本機能に権限による制御は存在しない。ただし、OSレベルでクリップボードアクセスが制限される場合がある。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全テキスト入力画面 | 補助機能 | Ctrl+Vでのペースト操作 |

## 機能種別

読取処理 / 外部連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (なし) | - | - | 引数なし | - |

### 入力データソース

- OSクリップボード - プラットフォーム固有のクリップボードストレージ
- Platform_GetClipboardTextFnコールバック経由でアクセス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | const char* | クリップボードのテキスト（NULL終端文字列） |

### 出力先

- 呼び出し元への戻り値として返却
- クリップボードが空、またはテキストデータでない場合はNULL

## 処理フロー

### 処理シーケンス

```
1. グローバルコンテキスト取得
   └─ GImGuiを逆参照
2. コールバック存在確認
   └─ g.PlatformIO.Platform_GetClipboardTextFnがNULLでないか
3. コールバック呼び出しまたはNULL返却
   ├─ コールバック存在: Platform_GetClipboardTextFn(&g)を呼び出し
   └─ コールバック不在: NULLを返却
```

### フローチャート

```mermaid
flowchart TD
    A[GetClipboardText呼び出し] --> B[コンテキスト取得]
    B --> C{Platform_GetClipboardTextFn != NULL?}
    C -->|Yes| D[コールバック呼び出し]
    C -->|No| E[NULL返却]
    D --> F[テキスト文字列返却]
    E --> G[終了]
    F --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-244-1 | テキスト以外は無効 | クリップボードにテキスト以外のデータがある場合はNULLを返す | 非テキストデータ時 |
| BR-244-2 | バックエンド依存 | 実際のクリップボードアクセスはバックエンドに依存 | 常時 |
| BR-244-3 | メモリ管理 | 返却される文字列の所有権はバックエンドにある | 文字列使用時 |

### 計算ロジック

特別な計算処理は行わない。コールバック経由でOSクリップボードにアクセスする。

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NULL戻り値 | 取得失敗 | コールバック未登録、またはクリップボードが空 | 呼び出し元でNULLチェックを実施 |
| - | コンテキスト未初期化 | GImGuiがNULL | CreateContext()を先に呼び出す |

### リトライ仕様

リトライ処理は不要。

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

本機能はトランザクション処理を行わない。

## パフォーマンス要件

- 処理時間: プラットフォーム依存（OSクリップボードアクセスを含む）
- メモリ使用: バックエンド実装に依存
- 呼び出し頻度: ペースト操作時に呼び出し

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

- クリップボードにはセンシティブな情報（パスワード等）が含まれる可能性がある
- 取得したテキストの用途に注意が必要
- クリップボードアクセスはOSのセキュリティポリシーに従う

## 備考

- LogToClipboard()関数でGUIの内容をクリップボードにログ出力可能
- SetClipboardText()関数と対になる読み取り関数
- 返却される文字列の生存期間はバックエンド実装に依存するため、必要に応じてコピーを取ること

---

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

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

### 推奨読解順序

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

クリップボードアクセスに使用されるコールバック関数の定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiPlatformIO構造体のPlatform_GetClipboardTextFn定義（3969行目付近） |
| 1-2 | imgui.h | `imgui.h` | レガシーのImGuiIO::GetClipboardTextFn（2610行目付近） |

**読解のコツ**: ImGui 1.91.1以降、クリップボード関数はImGuiPlatformIOに移動された。レガシー互換性のためImGuiIOにも残っているが、内部的にはリダイレクトされる。

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

関数の実装を確認する。

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

**主要処理フロー**:
1. **5091行目**: グローバルコンテキストを取得
2. **5092行目**: Platform_GetClipboardTextFnの存在確認と呼び出し（三項演算子）

#### Step 3: バックエンド実装を理解する

プラットフォーム固有のクリップボードアクセス実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_impl_win32.cpp | `backends/imgui_impl_win32.cpp` | Win32でのクリップボード取得実装 |
| 3-2 | imgui_impl_glfw.cpp | `backends/imgui_impl_glfw.cpp` | GLFWでのクリップボード取得実装 |
| 3-3 | imgui_impl_sdl2.cpp | `backends/imgui_impl_sdl2.cpp` | SDL2でのクリップボード取得実装 |

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

```
GetClipboardText()
    │
    └─ g.PlatformIO.Platform_GetClipboardTextFn(&g)
           │
           └─ バックエンド実装
                  │
                  ├─ Win32: GetClipboardData(CF_UNICODETEXT)
                  ├─ GLFW: glfwGetClipboardString()
                  ├─ SDL2: SDL_GetClipboardText()
                  └─ macOS: NSPasteboard
```

### データフロー図

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

OSクリップボード            GetClipboardText()        呼び出し元
    │                          │                         │
    └── テキストデータ ──────▶ コールバック呼び出し ────▶ const char*
                               │
                        [Platform_GetClipboardTextFn]
                               │
                        バックエンド実装
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言、ImGuiPlatformIO定義 |
| imgui.cpp | `imgui.cpp` | ソース | GetClipboardText関数の実装 |
| imgui_impl_win32.cpp | `backends/imgui_impl_win32.cpp` | バックエンド | Win32クリップボード実装 |
| imgui_impl_glfw.cpp | `backends/imgui_impl_glfw.cpp` | バックエンド | GLFWクリップボード実装 |
| imgui_impl_sdl2.cpp | `backends/imgui_impl_sdl2.cpp` | バックエンド | SDL2クリップボード実装 |
| imgui_impl_osx.mm | `backends/imgui_impl_osx.mm` | バックエンド | macOSクリップボード実装 |
