syncfusion-winforms-comboboxbase
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing 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 property.
ListControlKey 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派生类(ListBox、CheckedListBox、GridListControl)。
ListControl核心能力:
- 可插拔的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 = listBox1Code 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 ClassCommon 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属性
| Property | Type | Description |
|---|---|---|
| IListControl | Gets or sets the ListControl-derived control for dropdown |
| TextBox | Gets the TextBox portion of the control |
| PopupControlContainer | Gets the popup container for dropdown |
| ComboBoxStyle | Gets or sets the visual style |
| FlatStyle | Gets or sets the flat style appearance |
| Size | Gets or sets the control size |
| 属性 | 类型 | 描述 |
|---|---|---|
| IListControl | 获取或设置下拉区域使用的ListControl派生控件 |
| TextBox | 获取控件的TextBox编辑区域 |
| PopupControlContainer | 获取下拉区域的弹出容器 |
| ComboBoxStyle | 获取或设置视觉样式 |
| FlatStyle | 获取或设置平面样式外观 |
| Size | 获取或设置控件尺寸 |
ListControl Properties (Set on ListBox/CheckedListBox)
ListControl属性(在ListBox/CheckedListBox上设置)
| Property | Type | Description |
|---|---|---|
| ObjectCollection | Collection of items in the list |
| object | Data source for the list |
| string | Property to display for objects |
| string | Property to use as value |
| object | Currently selected item |
| int | Currently selected index |
| SelectionMode | Single or multiple selection |
| 属性 | 类型 | 描述 |
|---|---|---|
| ObjectCollection | 列表中的选项集合 |
| object | 列表的数据源 |
| string | 对象要显示的属性 |
| string | 作为值使用的对象属性 |
| object | 当前选中的项 |
| int | 当前选中的索引 |
| SelectionMode | 单选或多选模式 |
Important Events
重要事件
| Event | Description |
|---|---|
| Fires when selection is committed by user action |
| Fires when dropdown is about to close on click (cancellable) |
| Fires when dropdown is opening |
Note: Events like are handled on the ListControl (ListBox), not ComboBoxBase.
SelectedIndexChanged| 事件 | 描述 |
|---|---|
| 用户操作提交选择时触发 |
| 点击触发下拉关闭时触发(可取消) |
| 下拉框打开时触发 |
注意: 等事件需要在ListControl(ListBox)上处理,而非ComboBoxBase。
SelectedIndexChangedUse 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
后续步骤
- Start with getting-started.md for basic setup
- Read listcontrol-architecture.md for ListControl concepts
- Review event-handling.md for selection events
- Explore advanced-scenarios.md for complex use cases
- 首先阅读getting-started.md完成基础配置
- 阅读listcontrol-architecture.md了解ListControl相关概念
- 查看event-handling.md学习选择事件处理
- 探索advanced-scenarios.md了解复杂使用场景