syncfusion-winforms-combodropdown

ComboDropDown の実装

このスキルを使用する場面

Windows Forms アプリケーションで Syncfusion ComboDropDown コントロールを実装する必要がある場合に、このスキルを使用します。このスキルは、特に次のようなシナリオ向けに設計されています。

1. 柔軟なドロップダウンのホスト - ドロップダウン領域で、ListBox 派生コントロールに限定されず、任意のコントロール（TreeView、ListView、GridList、DataGrid、カスタムコントロール）をホストします
2. カスタムドロップダウン UI - 標準的なコンボボックスよりも豊かなデータ表示を提供するコントロールを使用して、独自のドロップダウン操作を作成します
3. ツリーに基づく選択 - ドロップダウンで TreeView コントロールを使用して、階層的なナビゲーションを実装します
4. 複数列での選択 - データをグリッド形式または複数列のレイアウトで表示し、閲覧しやすくします
5. 複雑なデータ操作 - 編集部分とドロップダウンコントロールの間でデータを転送するためのカスタムロジックが必要なシナリオ
6. カスタムポップアップ動作 - ドロップダウンの開閉タイミングや方法、およびユーザー操作への応答を完全に制御します
7. 高度なコントロール統合 - 標準的なリスト選択を超える機能を備えた、専用コントロールを統合します
8. 開発者による同期管理 - 自動データバインディングが適さず、手動で制御する必要があるシナリオ

主な違い： ComboBoxBase は（組み込みのデータバインディングを備えた）ListBox 派生コントロールのみをホストしますが、ComboDropDown は任意のコントロールをホストできます。ただし、テキストボックスとホストするコントロール間の操作ロジックは、ユーザーが実装する必要があります。

使用しない場面： ListBox、CheckedListBox、または GridListControl を使ったシンプルなドロップダウンのみが必要で、自動選択処理を使いたい場合は、代わりに ComboBoxBase を使用してください。

コンポーネントの概要

ComboDropDown コントロールは、次の機能を備えた軽量で柔軟なコンボボックスです。

• あらゆるコントロールのホスト - PopupControl プロパティには、任意の Windows Forms コントロールを設定できます
• 分離されたアーキテクチャ - 独立した編集部分（テキストボックス）とドロップダウン部分（任意のコントロール）
• 開発者による操作管理 - 選択内容をテキストに反映する方法、およびその逆を制御できます
• イベント駆動型の同期 - 操作ロジックの実装に使用できる DropDown イベント（表示前）と Popup イベント（表示後）
• 標準的なコンボボックスの外観 - 通常のコンボボックスのように見えながら、ドロップダウンを柔軟に利用できます
• プログラムによるドロップダウン制御 - クローズタイプを指定して、ポップアップを表示または非表示にするメソッド
• 完全なカスタマイズ - 外観、テーマ、テキストの動作、境界線のスタイルを設定できます

アーキテクチャ： ComboDropDown は、独立した次の 2 つの部分で構成されます。

1. 編集部分 - ユーザーが入力したり、選択した値を表示したりするテキストボックス
2. ドロップダウン部分 - 指定した任意のコントロールをホストするポップアップコンテナー

これらの部分をイベントハンドラーで連携させるのは、ユーザーの責任です。

ドキュメントとナビゲーションガイド

はじめに

📄 参照先： references/getting-started.md

ComboDropDown を初めてセットアップする場合に参照してください。次の内容を扱います。

• アセンブリ参照と NuGet パッケージのインストール
• 名前空間のインポート（Syncfusion.Windows.Forms.Tools）
• デザイナーを使ったセットアップ（ドラッグ＆ドロップ、プロパティの設定）
• コードによるセットアップ（プログラムでのインスタンス化）
• コントロールを関連付けるための PopupControl プロパティの設定
• TreeView を使用した基本的な統合例
• 初期設定とトラブルシューティング

イベント処理と操作

📄 参照： references/event-handling.md

コンボボックスのテキストとホストされたコントロール間のデータ連携を実装する場合に参照します。以下を扱います。

• DropDown イベント — ドロップダウンの表示前にテキストをコントロールの選択内容と同期する
• TreeView/ListView の DoubleClick イベント — 選択内容をテキストに反映する
• ドロップダウンをプログラムから閉じる（PopupCloseType.Done）
• Popup イベント — ドロップダウンの表示後にホストされたコントロールにフォーカスを設定する
• TreeView の移動に使用する FindNode 再帰ヘルパー
• TreeView の操作を完全に実装する
• GridList の統合パターン
• SuppressDropDownEvent プロパティ
• イベント駆動型の操作に関するベストプラクティス

テキストの動作と入力の制御

📄 参照： references/text-behavior.md

編集領域でのテキスト入力動作を制御する場合に参照します。以下を扱います。

• CharacterCasing プロパティ（Upper、Lower、Normal）
• NumberOnly プロパティ（数値入力に制限）
• ReadOnly プロパティ（編集を禁止）
• CaseSensitiveAutocomplete プロパティ
• MatchFirstCharacterOnly プロパティ
• バナーテキストのサポート（BannerTextProvider の統合）
• 各動作の完全な例

外観のカスタマイズ

📄 参照： references/appearance-customization.md

コントロールの外観や境界線をカスタマイズする場合に参照します。以下を扱います。

• Border3DStyle プロパティ（10 種類の 3D 境界線スタイル）
• BorderSides プロパティ（境界線を表示する辺を指定）
• FlatStyle プロパティ（Flat、System、Standard モード）
• FlatBorderColor プロパティ
• 編集領域の外観（Font、ForeColor、BackColor）
• ドロップダウンボタンのカスタマイズ
• Style プロパティの依存関係
• スタイル設定の完全な例

テーマとスタイル

📄 参照： references/themes-and-styles.md

ビジュアルテーマや Office スタイルの外観を適用する場合に参照します。以下を扱います。

• Style プロパティ（Office2016 のバリエーション、Metro、Office2010/2007/2003、VS2005、Default）
• Office2007ColorTheme プロパティ（Blue、Silver、Black の配色）
• カスタムカラーのサポート（ApplyManagedColors を使用する Managed テーマ）
• IgnoreThemeBackground プロパティ
• テーマと外観プロパティの相互作用
• 外観の比較とテーマ設定の完全な例

クイックスタートの例

TreeView を使用したデザイナーでの設定

// 1. Drag ComboDropDown and TreeView onto form
// 2. Add nodes to TreeView (in designer or code)
// 3. Set TreeView.HideSelection = false
// 4. Set ComboDropDown.PopupControl = treeView1

// Event handlers for interaction
private void comboDropDown1_DropDown(object sender, EventArgs e)
{
    // Before dropdown shown: select TreeNode matching combo text
    if (!string.IsNullOrEmpty(this.comboDropDown1.Text))
    {
        TreeNode matchedNode = FindNode(this.treeView1.Nodes, this.comboDropDown1.Text);
        this.treeView1.SelectedNode = matchedNode;
    }
}

private void treeView1_DoubleClick(object sender, EventArgs e)
{
    // Transfer selected node text to combo
    if (this.treeView1.SelectedNode != null)
    {
        this.comboDropDown1.Text = this.treeView1.SelectedNode.Text;
    }
    
    // Close the dropdown
    this.comboDropDown1.PopupContainer.HidePopup(PopupCloseType.Done);
}

private TreeNode FindNode(TreeNodeCollection nodes, string text)
{
    // Recursively find matching node
    foreach (TreeNode child in nodes)
    {
        if (child.Text == text) return child;
    }
    foreach (TreeNode child in nodes)
    {
        TreeNode matched = FindNode(child.Nodes, text);
        if (matched != null) return matched;
    }
    return null;
}

コードによる設定

using Syncfusion.Windows.Forms.Tools;

// Create ComboDropDown
ComboDropDown comboDropDown1 = new ComboDropDown();
comboDropDown1.Location = new Point(20, 20);
comboDropDown1.Size = new Size(200, 25);

// Create and configure TreeView
TreeView treeView1 = new TreeView();
treeView1.HideSelection = false;
treeView1.Nodes.Add("Root");
treeView1.Nodes[0].Nodes.Add("Child 1");
treeView1.Nodes[0].Nodes.Add("Child 2");

// Associate TreeView with ComboDropDown
comboDropDown1.PopupControl = treeView1;

// Wire up events
comboDropDown1.DropDown += comboDropDown1_DropDown;
treeView1.DoubleClick += treeView1_DoubleClick;

// Add to form
this.Controls.Add(comboDropDown1);

一般的なパターン

パターン 1：TreeView の階層選択

// Setup
comboDropDown1.PopupControl = treeView1;
treeView1.HideSelection = false;

// Sync text → TreeView selection (before dropdown)
comboDropDown1.DropDown += (s, e) => {
    var node = FindNode(treeView1.Nodes, comboDropDown1.Text);
    treeView1.SelectedNode = node;
};

// Sync TreeView selection → text (on double-click)
treeView1.DoubleClick += (s, e) => {
    if (treeView1.SelectedNode != null)
    {
        comboDropDown1.Text = treeView1.SelectedNode.Text;
        comboDropDown1.PopupContainer.HidePopup(PopupCloseType.Done);
    }
};

パターン 2：複数列グリッドでの選択

// Host a GridList control for multi-column data
GridListControl gridList = new GridListControl();
// Configure grid columns and data...

comboDropDown1.PopupControl = gridList;

// Sync selection to combo text using the grid's current cell/model
gridList.DoubleClick += (s, e) => {
    var cell = gridList.CurrentCell;
    if (cell != null)
    {
        int row = cell.RowIndex;
        // Read display text from the model (adjust column index as needed)
        comboDropDown1.Text = gridList.Model[row, 1].Text;
        comboDropDown1.PopupContainer.HidePopup(PopupCloseType.Done);
    }
};

パターン 3：マウス操作時のフォーカス管理

// Make dropdown control respond to mouse immediately
comboDropDown1.PopupContainer.Popup += (s, e) => {
    // Give focus to hosted control after dropdown shown
    treeView1.Focus();
};

主なプロパティ

PopupControl の設定

プロパティ	型	説明	使用する場面
PopupControl	Control	ドロップダウンに表示されるコントロール	ホストする任意の Windows Forms コントロールを設定します

テキストの動作

プロパティ	型	説明	使用する場面
Text	string	編集領域に表示されるテキスト	コンボボックスの現在のテキスト値を取得または設定します
CharacterCasing	CharacterCasing	Upper、Lower、Normal	入力を大文字または小文字に固定します
NumberOnly	bool	数値の入力に制限します	数値のみを扱う場合
ReadOnly	bool	編集を禁止します	ドロップダウンから選択する表示専用の場合

ドロップダウンコントロール

プロパティ	型	説明	使用する場面
PopupContainer	PopupControlContainer	ポップアップの動作を管理するコンテナー	HidePopup() または Popup イベントにアクセスする場合
SuppressDropDownEvent	bool	DropDown イベントの発生を抑制します	特定の状況で同期処理をスキップする場合

外観

プロパティ	型	説明	使用する場面
Border3DStyle	Border3DStyle	3D ボーダーの外観（10 種類のスタイル）	FlatStyle が Standard の場合にボーダーの外観をカスタマイズする
BorderSides	Border3DSide	ボーダーを表示する辺	カスタムのボーダー設定
FlatStyle	FlatStyle	Flat、System、Standard	全体的な外観モードを制御する
FlatBorderColor	Color	Flat モード時のボーダーの色	ボーダーの色をカスタマイズする

テーマ

プロパティ	型	説明	使用する場面
Style	VisualStyle	Office2016Colorful、Metro、Office2010 など	モダンなビジュアルテーマを適用する
Office2007ColorTheme	Office2007Theme	Blue、Silver、Black の配色	Office 2007 スタイルの外観
IgnoreThemeBackground	bool	テーマの代わりに BackColor を使用する	テーマの背景を上書きする

よくある使用例

1. TreeView を使ったファイルシステムナビゲーター

シナリオ： ユーザーが階層化されたファイル／フォルダー構造を参照する必要がある
解決策： ディレクトリツリーを表示する TreeView をホストし、選択したパスをコンボボックスのテキストに同期する

2. 複数列のグリッドを使ったカテゴリ選択

シナリオ： ユーザーが複数の表示列を持つカテゴリ別データから選択する必要がある
解決策： カテゴリ、名前、説明の列を持つ GridListControl をホストする

3. カレンダーコントロールを使った日付ピッカー

シナリオ： ユーザーが視覚的なカレンダーを使ってカスタムの日付を選択する必要がある
解決策： MonthCalendar またはカスタムのカレンダーコントロールをホストし、選択した日付をテキストに渡す

4. カスタムパネルを使ったカラー ピッカー

シナリオ： ユーザーが視覚的なカラーパレットから色を選択する必要がある
解決策： カラースウォッチを含むカスタムパネルをホストし、色名またはカラーコードをテキストに渡す

ComboDropDown と ComboBoxBase の選択ガイド

次の場合は ComboDropDown を選択します：

• ✅ TreeView、ListView、DataGrid、または任意のカスタムコントロールをホストする必要がある
• ✅ テキストとコントロールの同期ロジックを完全に制御したい
• ✅ 標準的な選択機能を超えるカスタムのポップアップ動作が必要である
• ✅ 階層型ナビゲーションや複雑なデータの可視化を構築する
• ✅ 標準の ListBox 機能では不十分である

次の場合は ComboBoxBase を選択します：

• ❌ ListBox、CheckedListBox、または GridListControl（シンプルなリスト）のみが必要である
• ❌ データバインディングと選択処理を自動化したい
• ❌ 組み込みの SelectionChangedCommitted イベントを使いたい
• ❌ インタラクションロジックを自分で管理する必要がない
• ❌ 標準のドロップダウンリスト機能で十分である

主な違い： ComboDropDown = 最大限の柔軟性と手動実装；ComboBoxBase = ListBox のみと自動処理