syncfusion-winforms-comboboxbase

ComboBoxBase の実装

Windows Forms アプリケーション向けに Syncfusion ComboBoxBase コントロールを実装する方法を説明します。ComboBoxBase は、編集部分とドロップダウンリストを分離し、プラグイン可能な ListControl アーキテクチャを実現することで、標準のコンボボックスに代わる柔軟な選択肢を提供します。

このスキルを使用するタイミング

次のような場合に、このスキルを使用してください。

• 編集部分とドロップダウン部分を分離した柔軟なコンボボックスを実装する
• ドロップダウン領域で、ListControl を継承したカスタムコントロールを使用する
• 複数選択可能なコンボボックスに CheckedListBox を統合する
• GridListControl を使用して複数列のドロップダウンを作成する
• 複雑な選択イベントやドロップダウンの動作を処理する
• 標準の Framework コンボボックスよりも細かく制御する必要がある
• カスタムポップアップコンテナーを備えたコンボボックスを構築する
• マウス操作によるクイック選択機能を実装する

注: Framework コンボボックスに似たオブジェクトモデルが必要な場合は、ComboBoxAdv（ComboBoxBase をベースとしながら、同一のオブジェクトモデルを備えています）の使用を検討してください。

コンポーネントの概要

ComboBoxBase コントロールは、編集部分（TextBox）とドロップダウンリスト部分を分離するため、強力で柔軟なアーキテクチャを実現します。ListControl プロパティを使用して、ListBox、CheckedListBox、GridListControl など、ListControl を継承する任意のクラスを組み込めます。

主な機能：

• プラグイン可能な ListControl アーキテクチャ
• ListBox、CheckedListBox、カスタム ListControl のサポート
• GridListControl による複数列のドロップダウン
• 選択シナリオに対応した包括的なイベント処理
• スタイルと外観のカスタマイズ
• PopupControlContainer との統合
• マウス操作による QuickSelection

アーキテクチャの違い：

• 標準のコンボボックスとは異なり、編集部分とリスト部分が分離されています
• Framework コンボボックスとはオブジェクトモデルが異なります
• DataSource や ItemHeight などのプロパティは ComboBoxBase ではなく ListControl に設定します
• SelectedIndexChanged などのイベントは ListControl で処理します

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

はじめに

📄 参照： references/getting-started.md

• インストールとアセンブリ参照
• デザイナーを使用したセットアップ（ドラッグ＆ドロップ）
• コードによるインスタンス化
• ListBox と ComboBoxBase の接続
• DataSource の構成
• セットアップの完全な例

ListControl アーキテクチャ

📄 参照： references/listcontrol-architecture.md

• ListControl プロパティの説明
• ListControl を継承するカスタムコントロールの作成
• 必須のプロパティとメソッド（Items、IndexFromPoint、TopIndex）
• コレクションクラス（ObjectCollection、SelectedObjectCollection、SelectedIndexCollection）
• QuickSelection 機能の実装
• 複数列のドロップダウンに使用する GridListControl
• さまざまなリストコントロールとの統合

イベント処理

📄 参照： references/event-handling.md

• 選択イベント（SelectionChangedCommitted、SelectedValueChanged、SelectedIndexChanged）
• イベントの順序とシナリオ
• CheckedListBox 用の DropDownCloseOnClick イベント
• PopupControlContainer 用の DropDown イベント
• Validating／Validated イベント
• CheckedListBox の完全な統合例

外観と動作

📄 参照： references/appearance-behavior.md

• Style プロパティと FlatStyle プロパティ
• 枠線描画のカスタマイズ
• TextBox とドロップダウンウィンドウのスタイル設定
• Framework コンボボックスとのプロパティの違い
• ComboBoxAdv との比較
• 視覚的なスタイル設定の例

高度なシナリオ

📄 参照： references/advanced-scenarios.md

• CheckedListBox の複数選択パターン
• カスタム PopupControlContainer の派生
• フォーカス管理のための OnPopup のオーバーライド
• PopupControlContainer 内への ComboBoxBase のネスト
• PopupParent と CurrentPopupChild の関係
• 複雑なドロップダウンのシナリオ

クイックスタート

デザイナーでのセットアップ

手順 1：フォームに ComboBoxBase を追加

1. Open your WinForms project in Visual Studio
2. Drag ComboBoxBase from Toolbox to Form
3. Drag ListBox from Toolbox to Form
4. In ComboBoxBase Properties, set ListControl = listBox1

コードでのセットアップ

基本的な実装：

using Syncfusion.Windows.Forms.Tools;
using System.Windows.Forms;

public partial class Form1 : Form
{
    private ComboBoxBase comboBoxBase1;
    private ListBox listBox1;
    
    public Form1()
    {
        InitializeComponent();
        SetupComboBoxBase();
    }
    
    private void SetupComboBoxBase()
    {
        // Create ComboBoxBase and ListBox
        comboBoxBase1 = new ComboBoxBase();
        listBox1 = new ListBox();
        
        // Configure ComboBoxBase
        comboBoxBase1.Size = new Size(200, 25);
        comboBoxBase1.Location = new Point(20, 20);
        comboBoxBase1.ListControl = listBox1; // Connect ListBox
        
        // Add items to ListBox
        listBox1.Items.AddRange(new object[] {
            "Option 1",
            "Option 2",
            "Option 3",
            "Option 4"
        });
        
        // Add to form
        this.Controls.Add(listBox1);
        this.Controls.Add(comboBoxBase1);
    }
}

VB.NET：

Imports Syncfusion.Windows.Forms.Tools
Imports System.Windows.Forms

Public Class Form1
    Private comboBoxBase1 As ComboBoxBase
    Private listBox1 As ListBox
    
    Public Sub New()
        InitializeComponent()
        SetupComboBoxBase()
    End Sub
    
    Private Sub SetupComboBoxBase()
        ' Create ComboBoxBase and ListBox
        comboBoxBase1 = New ComboBoxBase()
        listBox1 = New ListBox()
        
        ' Configure ComboBoxBase
        comboBoxBase1.Size = New Size(200, 25)
        comboBoxBase1.Location = New Point(20, 20)
        comboBoxBase1.ListControl = listBox1 ' Connect ListBox
        
        ' Add items to ListBox
        listBox1.Items.AddRange(New Object() {
            "Option 1",
            "Option 2",
            "Option 3",
            "Option 4"
        })
        
        ' Add to form
        Me.Controls.Add(listBox1)
        Me.Controls.Add(comboBoxBase1)
    End Sub
End Class

よくあるパターン

パターン 1：DataSource を使用する ComboBoxBase

// Create data source
List<string> states = new List<string> 
{ 
    "California", "Texas", "Florida", "New York" 
};

// Set DataSource on ListBox (not ComboBoxBase)
listBox1.DataSource = states;
comboBoxBase1.ListControl = listBox1;

パターン 2：CheckedListBox の統合

// Use CheckedListBox for multi-select
CheckedListBox checkedListBox1 = new CheckedListBox();
checkedListBox1.Items.AddRange(new object[] {
    "Item 1", "Item 2", "Item 3", "Item 4"
});

comboBoxBase1.ListControl = checkedListBox1;

// Handle DropDownCloseOnClick to prevent premature closing
comboBoxBase1.DropDownCloseOnClick += (sender, e) => {
    e.Cancel = true; // Keep dropdown open while selecting
};

// Update text with checked items
checkedListBox1.ItemCheck += (sender, e) => {
    // Build text from checked items
    var checkedItems = checkedListBox1.CheckedItems.Cast<object>();
    comboBoxBase1.TextBox.Text = string.Join(", ", checkedItems);
};

パターン 3：カスタムオブジェクトのデータソース

public class Employee
{
    public int Id { get; set; }
    public string Name { get; set; }
    public override string ToString() => Name;
}

// Create employee list
List<Employee> employees = new List<Employee>
{
    new Employee { Id = 1, Name = "John Doe" },
    new Employee { Id = 2, Name = "Jane Smith" },
    new Employee { Id = 3, Name = "Bob Johnson" }
};

listBox1.DataSource = employees;
listBox1.DisplayMember = "Name"; // Display property
listBox1.ValueMember = "Id";     // Value property

comboBoxBase1.ListControl = listBox1;

主なプロパティ

ComboBoxBase のプロパティ

プロパティ	型	説明
ListControl	IListControl	ドロップダウンに使用する ListControl 派生コントロールを取得または設定します
TextBox	TextBox	コントロールの TextBox 部分を取得します
PopupContainer	PopupControlContainer	ドロップダウンのポップアップコンテナーを取得します
Style	ComboBoxStyle	表示スタイルを取得または設定します
FlatStyle	FlatStyle	フラットスタイルの外観を取得または設定します
Size	Size	コントロールのサイズを取得または設定します

ListControl のプロパティ（ListBox／CheckedListBox に設定）

プロパティ	型	説明
Items	ObjectCollection	リスト内の項目のコレクション
DataSource	object	リストのデータソース
DisplayMember	string	オブジェクトの表示に使用するプロパティ
ValueMember	string	値として使用するプロパティ
SelectedItem	object	現在選択されている項目
SelectedIndex	int	現在選択されているインデックス
SelectionMode	SelectionMode	単一選択または複数選択

重要なイベント

イベント	説明
SelectionChangedCommitted	ユーザー操作によって選択が確定したときに発生します
DropDownCloseOnClick	クリックによってドロップダウンが閉じようとするときに発生します（キャンセル可能）
DropDown	ドロップダウンが開くときに発生します

注： SelectedIndexChanged などのイベントは、ComboBoxBase ではなく ListControl（ListBox）で処理されます。

使用例

使用例 1：シンプルなドロップダウンリスト

項目を含む基本的なドロップダウンが必要な場合は、標準の ListBox を使用します。

• オプションのリストを表示する
• 単一選択
• シンプルなテキスト項目またはオブジェクトのデータバインディング

使用例 2：複数選択ドロップダウン

ユーザーが複数の項目を選択する必要がある場合は、CheckedListBox を使用します。

• フィルターの選択（複数のカテゴリ）
• タグの選択
• 権限のチェックボックス
• 複数値の入力

使用例 3：複数列のドロップダウン

ドロップダウンに表形式のデータを表示する場合は、GridListControl を使用します。

• ID、名前、部署による従業員の選択
• コード、名前、価格による製品の選択
• 複数のフィールドによるデータベースレコードの選択

使用例 4：カスタムリストコントロール

組み込みコントロールでは不十分な場合は、カスタム ListControl を作成します。

• 画像やアイコンを使ったカスタム描画
• 複雑なレイアウト
• 特殊な操作パターン

選択ガイド

次の場合は、標準のコンボボックスではなく ComboBoxBase を選択します。

• ListControl をプラグイン可能なアーキテクチャが必要な場合
• CheckedListBox またはカスタムコントロールを使用したい場合
• GridListControl を使った複数列のドロップダウンが必要な場合
• 編集部分とリスト部分を細かく制御する必要がある場合
• 複雑なドロップダウンを構築する場合

次の場合は、標準のコンボボックスを選択します。

• シンプルなドロップダウンリストで十分な場合
• フレームワークのオブジェクトモデルを優先する場合
• カスタム ListControl が不要な場合
• 基本的な選択シナリオのみの場合

次の場合は、ComboBoxAdv を選択します。

• ComboBoxBase の柔軟性が必要な場合
• フレームワークのコンボボックスのオブジェクトモデルを優先する場合
• 高機能さと使い慣れた API の両方が必要な場合

次のステップ

1. 基本設定については、getting-started.md から始めます
2. ListControl の概念については、listcontrol-architecture.md を読みます
3. 選択イベントについては、event-handling.md を確認します
4. 複雑な使用例については、advanced-scenarios.md をご覧ください