# 画面設計書 29-Dialogs

## 概要

本ドキュメントは、Avalonia ControlCatalogサンプルアプリケーションにおけるDialogsデモページの画面設計を定義するものです。

### 本画面の処理概要

本画面は、Avaloniaの各種ダイアログ機能をデモンストレーションするためのページです。ウィンドウダイアログ、ファイルピッカー、フォルダーピッカー、URIランチャーなど、アプリケーションの対話的なユーザーインタラクションを実装する方法を学習・検証できる環境を提供します。

**業務上の目的・背景**：ダイアログは、ユーザーとの重要なインタラクションを提供するUI要素です。ファイルの選択・保存、確認メッセージの表示、設定変更、モーダルな入力フォームなど、業務アプリケーションの様々な場面で使用されます。Avaloniaでは、クロスプラットフォーム対応のIStorageProvider APIにより、プラットフォームネイティブのファイルダイアログを統一的に使用できます。

**画面へのアクセス方法**：ControlCatalogアプリケーションのメインウィンドウから、HamburgerMenuのナビゲーションで「Dialogs」を選択することでアクセスできます。

**主要な操作・処理内容**：
1. ウィンドウダイアログの表示（装飾付きウィンドウ、通常ダイアログ、タスクバー非表示ダイアログ、所有ウィンドウ）
2. ファイルピッカーAPIによるファイル選択・保存
3. フォルダーピッカーによるフォルダー選択
4. ファイルタイプフィルターの設定
5. ブックマーク機能によるファイル/フォルダーアクセス
6. URIランチャーによる外部リンク・ファイル起動
7. マネージドファイルダイアログの使用

**画面遷移**：MainViewからHamburgerMenuナビゲーションを通じて遷移。各種ダイアログウィンドウを表示。

**権限による表示制御**：特になし（サンプルアプリケーション）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 92 | ManagedFileChooser | 主機能 | ダイアログのデモ。ファイル選択ダイアログ |
| 42 | Window | 補助機能 | ウィンドウダイアログ、所有ウィンドウの表示 |

## 画面種別

デモ / サンプル表示（ダイアログ呼び出し元）

## URL/ルーティング

HamburgerMenu内部ナビゲーション（直接URLルーティングなし）

## 入出力項目

| 項目名 | 種別 | データ型 | 必須 | 説明 |
|--------|------|----------|------|------|
| FilterSelector | 入力 | ComboBoxItem | - | ファイルタイプフィルター選択 |
| UseSuggestedFilter | 入力 | bool | - | 推奨ファイルタイプ使用フラグ |
| SuggestedFilterSelector | 入力 | ComboBoxItem | - | 推奨フィルター選択 |
| ForceManaged | 入力 | bool | - | マネージドダイアログ強制使用 |
| OpenMultiple | 入力 | bool | - | 複数ファイル選択可否 |
| CurrentFolderBox | 入力 | string | - | 開始フォルダーパス/WellKnownFolder名 |
| UriToLaunch | 入力 | string | - | 起動するURI |
| BookmarkContainer | 入出力 | string | - | ブックマーク文字列 |
| OpenedFileContent | 出力 | string | - | 選択ファイルの内容 |

## 表示項目

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| Windows: セクション | TextBlock | ウィンドウダイアログセクション |
| Pickers: セクション | TextBlock | ファイル/フォルダーピッカーセクション |
| Filter ラベル | Label | フィルター選択ラベル |
| PickerLastResults | ItemsControl | 最後のピッカー結果リスト |
| LaunchStatus | TextBlock | URI/ファイル起動結果 |

## イベント仕様

### 1-Decorated windowボタンクリック

DecoratedWindowをnew/Showで非モーダル表示。

### 2-Decorated window (dialog)ボタンクリック

DecoratedWindowをShowDialogでモーダル表示。親ウィンドウに対するダイアログ。

### 3-Dialogボタンクリック

シンプルなWindowをShowDialogで表示（高さ200）。「Click to close」ボタンと「Dialog」ボタン（ネスト可能）を含む。

### 4-Dialog (No taskbar icon)ボタンクリック

ShowInTaskbar=falseのダイアログを表示。タスクバーにアイコンが表示されない。

### 5-Owned windowボタンクリック

所有ウィンドウをShow(owner)で表示。オーナーウィンドウと連動。

### 6-Owned window (No taskbar icon)ボタンクリック

ShowInTaskbar=falseの所有ウィンドウを表示。

### 7-Select Folderボタンクリック

OpenFolderPickerAsyncでフォルダー選択ダイアログを表示。複数選択オプション対応。選択結果をPickerLastResultsに表示。

### 8-Open Fileボタンクリック

OpenFilePickerAsyncでファイル選択ダイアログを表示。フィルター設定、複数選択、推奨ファイルタイプに対応。選択ファイルの内容を読み取りOpenedFileContentに表示。

### 9-Save Fileボタンクリック

SaveFilePickerAsyncでファイル保存ダイアログを表示。OpenedFileContentの内容を書き込み。

### 10-Save File XML or JSONボタンクリック

SaveFilePickerWithResultAsyncでファイル保存。選択されたファイルタイプに応じてXMLまたはJSONフォーマットで保存。

### 11-Open File Bookmarkボタンクリック

BookmarkContainerの値を使用してOpenFileBookmarkAsyncでファイルを開く。

### 12-Open Folder Bookmarkボタンクリック

BookmarkContainerの値を使用してOpenFolderBookmarkAsyncでフォルダーを開く。

### 13-Launch Uriボタンクリック

UriToLaunchのURIをLaunchUriAsyncで起動。デフォルトブラウザで開く。

### 14-Launch Fileボタンクリック

最後に選択されたファイル/フォルダーをLaunchFileAsyncで起動。OSのデフォルトアプリで開く。

### 15-CurrentFolderBoxテキスト変更

WellKnownFolder名またはパスを解析し、lastSelectedDirectoryを更新。

## データベース更新仕様

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

本画面はUIコントロールのデモであり、データベース操作は行いません。

## メッセージ仕様

| 種別 | メッセージID | メッセージ内容 | 表示条件 |
|------|-------------|---------------|----------|
| 情報 | - | Can't bookmark | ブックマーク不可のファイル選択時 |
| 情報 | - | LaunchUriAsync returned {result} | URI起動後 |
| 情報 | - | LaunchFileAsync returned {result} | ファイル起動後 |
| エラー | - | Can't parse the Uri | URI解析失敗時 |
| エラー | - | Please select any file or folder first | ファイル未選択時 |
| 情報 | - | Storage provider is not available: {error} | StorageProvider利用不可時 |

## 例外処理

- ファイル読み取り/書き込み失敗時は例外メッセージをOpenedFileContentに表示
- SecurityException発生時はサイレントに処理
- StorageProvider利用不可時はエラーメッセージを表示

## 備考

- IStorageProviderはクロスプラットフォーム対応のファイルシステムAPI
- WellKnownFolderで標準フォルダー（Desktop, Documents等）にアクセス可能
- ブックマーク機能でファイル/フォルダーへの永続的アクセス権を保存
- ForceManaged=trueでマネージドダイアログ（Avalonia実装）を強制使用

---

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

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

### 推奨読解順序

#### Step 1: 画面レイアウトを理解する

XAMLで各ボタンとコントロールの配置を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DialogsPage.xaml | `samples/ControlCatalog/Pages/DialogsPage.xaml` | StackPanel構造、各ボタンとExpanderの配置、AutoCompleteBoxのWellKnownFolder設定 |

**主要処理フロー**:
1. **行10-21**: Window dialogsセクション（Expander内）
2. **行23-39**: Filters設定セクション
3. **行40-51**: FilePicker APIセクション（Expander内）
4. **行53-60**: Launcher dialogsセクション（Expander内）
5. **行62-73**: CurrentFolderBox（AutoCompleteBox + WellKnownFolder）
6. **行75-84**: 結果表示領域

#### Step 2: コードビハインドを理解する

各ボタンのイベントハンドラと非同期処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | DialogsPage.xaml.cs | `samples/ControlCatalog/Pages/DialogsPage.xaml.cs` | コンストラクタでのイベント登録、各種ピッカー呼び出し、ファイル読み書き |

**主要処理フロー**:
- **行17-33**: 変数初期化、CurrentFolderBox.TextChangedハンドラ
- **行64-101**: BuildFileTypes/GetFileTypes - フィルター構築
- **行160-195**: ウィンドウダイアログ表示（DecoratedWindow、Dialog等）
- **行197-248**: OpenFilePicker/SaveFilePicker
- **行250-293**: SaveFilePickerWithResult（XML/JSON）
- **行294-321**: FolderPicker、Bookmarkからのオープン
- **行323-349**: URI/ファイルランチャー
- **行432-452**: ReadTextFromFile - ファイル内容読み取り

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

```
DialogsPage (UserControl)
    │
    ├─ コンストラクタ
    │      ├─ イベントハンドラ登録
    │      └─ BuildFileTypes() → フィルター初期化
    │
    ├─ ウィンドウダイアログ群
    │      ├─ DecoratedWindow.Click → new DecoratedWindow().Show()
    │      ├─ DecoratedWindowDialog.Click → ShowDialog(owner)
    │      ├─ Dialog.Click → CreateSampleWindow().ShowDialog(owner)
    │      ├─ DialogNoTaskbar.Click → ShowInTaskbar=false
    │      ├─ OwnedWindow.Click → Show(owner)
    │      └─ OwnedWindowNoTaskbar.Click → ShowInTaskbar=false
    │
    ├─ ファイルピッカー群
    │      ├─ OpenFilePicker.Click
    │      │      └─ GetStorageProvider().OpenFilePickerAsync()
    │      │             └─ SetPickerResult()
    │      │
    │      ├─ SaveFilePicker.Click
    │      │      └─ GetStorageProvider().SaveFilePickerAsync()
    │      │             └─ file.OpenWriteAsync() → StreamWriter
    │      │
    │      └─ OpenFolderPicker.Click
    │             └─ GetStorageProvider().OpenFolderPickerAsync()
    │
    ├─ ブックマーク
    │      ├─ OpenFileFromBookmark.Click → OpenFileBookmarkAsync()
    │      └─ OpenFolderFromBookmark.Click → OpenFolderBookmarkAsync()
    │
    └─ ランチャー
           ├─ LaunchUri.Click → Launcher.LaunchUriAsync()
           └─ LaunchFile.Click → Launcher.LaunchFileAsync()
```

### データフロー図

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

ボタンクリック ─────────▶ ピッカーダイアログ表示 ─────────▶ ユーザー選択
                              │
                              └─ ファイル選択 ───────────────▶ IStorageFile
                                     │
                                     ├─ GetBasicPropertiesAsync ──▶ サイズ/日時
                                     ├─ OpenReadAsync → ReadTextFromFile ▶ ファイル内容
                                     └─ SaveBookmarkAsync ────────▶ ブックマーク文字列

フィルター選択 ─────────▶ BuildFileTypes() ─────────────────▶ FilePickerFileType[]
                              │
                              └─ GetSuggestedFileType() ──────▶ 推奨タイプ

URI入力 ────────────────▶ Uri.TryCreate() ─────────────────▶ LaunchUriAsync()
                                                                  │
                                                                  └─ ブラウザ起動
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| DialogsPage.xaml | `samples/ControlCatalog/Pages/DialogsPage.xaml` | XAML | 画面レイアウト定義 |
| DialogsPage.xaml.cs | `samples/ControlCatalog/Pages/DialogsPage.xaml.cs` | ソース | コードビハインド、ダイアログ呼び出しロジック |
| DecoratedWindow.xaml | `samples/ControlCatalog/DecoratedWindow.xaml` | XAML | 装飾付きウィンドウ定義 |
| ManagedStorageProvider.cs | Avalonia.Dialogs内 | ソース | マネージドファイルダイアログ実装 |
