syncfusion-winforms-comboboxbase

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing ComboBoxBase

实现ComboBoxBase

Guides the implementation of the Syncfusion ComboBoxBase control for Windows Forms applications. ComboBoxBase provides a flexible alternative to the standard combo box by separating the edit portion from the drop-down list, enabling pluggable ListControl architecture.
本指南介绍如何在Windows Forms应用中实现Syncfusion ComboBoxBase控件。ComboBoxBase将编辑区域和下拉列表区域分离,支持可插拔的ListControl架构,是标准组合框的灵活替代方案。

When to Use This Skill

适用场景

Use this skill when you need to:
  • Implement a flexible combo box with separated edit and dropdown architecture
  • Use custom ListControl-derived controls in dropdown areas
  • Integrate CheckedListBox for multi-select combo boxes
  • Create multi-column dropdowns using GridListControl
  • Handle complex selection events and dropdown behaviors
  • Need more control than standard Framework combo box provides
  • Build combo boxes with custom popup containers
  • Implement quick selection capability with mouse interactions
Note: If you need a Framework combo box-like object model, consider using ComboBoxAdv (based on ComboBoxBase but with identical object model).
当你需要实现以下需求时可以使用本指南:
  • 实现具备编辑区和下拉区分离架构的灵活组合框
  • 在下拉区域使用自定义的ListControl派生控件
  • 集成CheckedListBox实现多选组合框
  • 使用GridListControl创建多列下拉框
  • 处理复杂的选择事件和下拉行为
  • 需要比标准Framework组合框更强的控制能力
  • 构建带自定义弹出容器的组合框
  • 实现支持鼠标交互的快速选择功能
注意: 如果你需要类似Framework组合框的对象模型,可以考虑使用ComboBoxAdv(基于ComboBoxBase实现,但拥有和标准组合框一致的对象模型)。

Component Overview

组件概览

The ComboBoxBase control separates the edit (TextBox) portion from the drop-down list portion, making the architecture powerful and flexible. You can plug in any ListControl-derived class (ListBox, CheckedListBox, GridListControl) using the
ListControl
property.
Key Capabilities:
  • Pluggable ListControl architecture
  • Support for ListBox, CheckedListBox, custom ListControls
  • Multi-column dropdowns with GridListControl
  • Comprehensive event handling for selection scenarios
  • Style and appearance customization
  • PopupControlContainer integration
  • QuickSelection with mouse interactions
Architecture Differences:
  • Unlike standard combo box, edit and list portions are separate
  • Different object model from Framework combo box
  • Properties like DataSource, ItemHeight set on ListControl, not ComboBoxBase
  • Events like SelectedIndexChanged handled on ListControl
ComboBoxBase控件将编辑(TextBox)部分和下拉列表部分分离,架构强大且灵活。你可以通过
ListControl
属性插入任意ListControl派生类(ListBox、CheckedListBox、GridListControl)。
核心能力:
  • 可插拔的ListControl架构
  • 支持ListBox、CheckedListBox、自定义ListControl
  • 借助GridListControl实现多列下拉框
  • 面向选择场景的全面事件处理
  • 样式和外观自定义
  • 集成PopupControlContainer
  • 支持鼠标交互的快速选择功能
架构差异:
  • 与标准组合框不同,编辑区和列表区是分离的
  • 与Framework组合框的对象模型不同
  • DataSource、ItemHeight等属性需要在ListControl上设置,而非ComboBoxBase
  • SelectedIndexChanged等事件需要在ListControl上处理

Documentation and Navigation Guide

文档导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Installation and assembly references
  • Designer-based setup (drag-and-drop)
  • Code-based instantiation
  • Connecting ListBox to ComboBoxBase
  • DataSource configuration
  • Complete setup examples
📄 阅读: references/getting-started.md
  • 安装与程序集引用
  • 基于设计器的配置(拖拽操作)
  • 基于代码的实例化
  • 将ListBox与ComboBoxBase关联
  • DataSource配置
  • 完整的配置示例

ListControl Architecture

ListControl架构

📄 Read: references/listcontrol-architecture.md
  • ListControl property explained
  • Creating custom ListControl-derived controls
  • Required properties and methods (Items, IndexFromPoint, TopIndex)
  • Collection classes (ObjectCollection, SelectedObjectCollection, SelectedIndexCollection)
  • QuickSelection capability implementation
  • GridListControl for multi-column dropdowns
  • Integration with various list controls
📄 阅读: references/listcontrol-architecture.md
  • ListControl属性详解
  • 创建自定义ListControl派生控件
  • 必需的属性和方法(Items、IndexFromPoint、TopIndex)
  • 集合类(ObjectCollection、SelectedObjectCollection、SelectedIndexCollection)
  • 快速选择功能实现
  • 用于多列下拉框的GridListControl
  • 各类列表控件的集成

Event Handling

事件处理

📄 Read: references/event-handling.md
  • Selection events (SelectionChangedCommitted, SelectedValueChanged, SelectedIndexChanged)
  • Event order and scenarios
  • DropDownCloseOnClick event for CheckedListBox
  • DropDown event for PopupControlContainer
  • Validating/Validated events
  • Complete CheckedListBox integration example
📄 阅读: references/event-handling.md
  • 选择事件(SelectionChangedCommitted、SelectedValueChanged、SelectedIndexChanged)
  • 事件顺序与适用场景
  • 用于CheckedListBox的DropDownCloseOnClick事件
  • 用于PopupControlContainer的DropDown事件
  • Validating/Validated事件
  • 完整的CheckedListBox集成示例

Appearance and Behavior

外观与行为

📄 Read: references/appearance-behavior.md
  • Style and FlatStyle properties
  • Border drawing customization
  • TextBox and dropdown window styling
  • Properties vs Framework combo box
  • ComboBoxAdv comparison
  • Visual styling examples
📄 阅读: references/appearance-behavior.md
  • Style和FlatStyle属性
  • 边框绘制自定义
  • TextBox和下拉窗口样式设置
  • 与Framework组合框的属性对比
  • 与ComboBoxAdv的对比
  • 视觉样式示例

Advanced Scenarios

高级场景

📄 Read: references/advanced-scenarios.md
  • CheckedListBox multi-select pattern
  • Custom PopupControlContainer derivation
  • OnPopup override for focus management
  • Nesting ComboBoxBase in PopupControlContainer
  • PopupParent and CurrentPopupChild relationships
  • Complex dropdown scenarios
📄 阅读: references/advanced-scenarios.md
  • CheckedListBox多选模式
  • 自定义PopupControlContainer派生类
  • 重写OnPopup实现焦点管理
  • 在PopupControlContainer中嵌套ComboBoxBase
  • PopupParent与CurrentPopupChild关系
  • 复杂下拉场景

Quick Start

快速开始

Designer Setup

设计器配置

Step 1: Add ComboBoxBase to Form
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
步骤1:将ComboBoxBase添加到窗体
1. 在Visual Studio中打开你的WinForms项目
2. 从工具箱中将ComboBoxBase拖拽到窗体上
3. 从工具箱中将ListBox拖拽到窗体上
4. 在ComboBoxBase的属性面板中,设置ListControl = listBox1

Code Setup

代码配置

Basic Implementation:
csharp
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:
vb
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
基础实现:
csharp
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代码:
vb
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

Common Patterns

常用模式

Pattern 1: ComboBoxBase with DataSource

模式1:带DataSource的ComboBoxBase

csharp
// 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;
csharp
// 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;

Pattern 2: CheckedListBox Integration

模式2:集成CheckedListBox

csharp
// 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);
};
csharp
// 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);
};

Pattern 3: Custom Object DataSource

模式3:自定义对象DataSource

csharp
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;
csharp
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;

Key Properties

核心属性

ComboBoxBase Properties

ComboBoxBase属性

PropertyTypeDescription
ListControl
IListControlGets or sets the ListControl-derived control for dropdown
TextBox
TextBoxGets the TextBox portion of the control
PopupContainer
PopupControlContainerGets the popup container for dropdown
Style
ComboBoxStyleGets or sets the visual style
FlatStyle
FlatStyleGets or sets the flat style appearance
Size
SizeGets or sets the control size
属性类型描述
ListControl
IListControl获取或设置下拉区域使用的ListControl派生控件
TextBox
TextBox获取控件的TextBox编辑区域
PopupContainer
PopupControlContainer获取下拉区域的弹出容器
Style
ComboBoxStyle获取或设置视觉样式
FlatStyle
FlatStyle获取或设置平面样式外观
Size
Size获取或设置控件尺寸

ListControl Properties (Set on ListBox/CheckedListBox)

ListControl属性(在ListBox/CheckedListBox上设置)

PropertyTypeDescription
Items
ObjectCollectionCollection of items in the list
DataSource
objectData source for the list
DisplayMember
stringProperty to display for objects
ValueMember
stringProperty to use as value
SelectedItem
objectCurrently selected item
SelectedIndex
intCurrently selected index
SelectionMode
SelectionModeSingle or multiple selection
属性类型描述
Items
ObjectCollection列表中的选项集合
DataSource
object列表的数据源
DisplayMember
string对象要显示的属性
ValueMember
string作为值使用的对象属性
SelectedItem
object当前选中的项
SelectedIndex
int当前选中的索引
SelectionMode
SelectionMode单选或多选模式

Important Events

重要事件

EventDescription
SelectionChangedCommitted
Fires when selection is committed by user action
DropDownCloseOnClick
Fires when dropdown is about to close on click (cancellable)
DropDown
Fires when dropdown is opening
Note: Events like
SelectedIndexChanged
are handled on the ListControl (ListBox), not ComboBoxBase.
事件描述
SelectionChangedCommitted
用户操作提交选择时触发
DropDownCloseOnClick
点击触发下拉关闭时触发(可取消)
DropDown
下拉框打开时触发
注意:
SelectedIndexChanged
等事件需要在ListControl(ListBox)上处理,而非ComboBoxBase。

Use Cases

使用场景

Use Case 1: Simple Dropdown List

场景1:简单下拉列表

When you need a basic dropdown with items, use standard ListBox:
  • Display list of options
  • Single selection
  • Simple text items or object binding
当你需要基础的选项下拉列表时,使用标准ListBox:
  • 展示选项列表
  • 单选模式
  • 简单文本选项或对象绑定

Use Case 2: Multi-Select Dropdown

场景2:多选下拉框

When users need to select multiple items, use CheckedListBox:
  • Filter selection (multiple categories)
  • Tag selection
  • Permission checkboxes
  • Multi-value inputs
当用户需要选择多个选项时,使用CheckedListBox:
  • 筛选选择(多个分类)
  • 标签选择
  • 权限复选框
  • 多值输入

Use Case 3: Multi-Column Dropdown

场景3:多列下拉框

When displaying tabular data in dropdown, use GridListControl:
  • Employee selection with ID, Name, Department
  • Product selection with Code, Name, Price
  • Database record selection with multiple fields
当需要在下拉框中展示表格数据时,使用GridListControl:
  • 员工选择(展示ID、姓名、部门)
  • 产品选择(展示编码、名称、价格)
  • 多字段的数据库记录选择

Use Case 4: Custom List Controls

场景4:自定义列表控件

When built-in controls are insufficient, create custom ListControl:
  • Custom rendering with images/icons
  • Complex layouts
  • Specialized interaction patterns
当内置控件无法满足需求时,创建自定义ListControl:
  • 带图片/图标的自定义渲染
  • 复杂布局
  • 特殊交互模式

Decision Guide

选型指南

Choose ComboBoxBase over standard combo box when:
  • Need pluggable ListControl architecture
  • Want to use CheckedListBox or custom controls
  • Require multi-column dropdowns with GridListControl
  • Need fine-grained control over edit and list portions
  • Building complex dropdown scenarios
Choose standard combo box when:
  • Simple dropdown list is sufficient
  • Framework object model is preferred
  • No custom ListControl needed
  • Basic selection scenarios only
Choose ComboBoxAdv when:
  • Need ComboBoxBase flexibility
  • Prefer Framework combo box object model
  • Want both power and familiar API
满足以下条件时选择ComboBoxBase而非标准组合框:
  • 需要可插拔的ListControl架构
  • 想要使用CheckedListBox或自定义控件
  • 需要使用GridListControl实现多列下拉框
  • 需要对编辑区和列表区进行细粒度控制
  • 构建复杂下拉场景
满足以下条件时选择标准组合框:
  • 简单下拉列表即可满足需求
  • 倾向使用Framework的对象模型
  • 不需要自定义ListControl
  • 仅需基础选择场景
满足以下条件时选择ComboBoxAdv:
  • 需要ComboBoxBase的灵活性
  • 倾向使用Framework组合框的对象模型
  • 同时需要强大功能和熟悉的API

Related Skills

相关技能

  • AutoComplete: For auto-complete suggestions in dropdowns
  • ComboBoxAdv: Framework combo box-like API with ComboBoxBase flexibility
  • AutoComplete:用于下拉框的自动补全建议功能
  • ComboBoxAdv:具备ComboBoxBase灵活性,同时提供类似Framework组合框的API

Next Steps

后续步骤

  1. Start with getting-started.md for basic setup
  2. Read listcontrol-architecture.md for ListControl concepts
  3. Review event-handling.md for selection events
  4. Explore advanced-scenarios.md for complex use cases
  1. 首先阅读getting-started.md完成基础配置
  2. 阅读listcontrol-architecture.md了解ListControl相关概念
  3. 查看event-handling.md学习选择事件处理
  4. 探索advanced-scenarios.md了解复杂使用场景