syncfusion-winforms-editable-listbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Windows Forms EditableList

实现Syncfusion Windows Forms EditableList

A comprehensive guide for implementing and customizing the EditableList control - a powerful list box component that enables inline editing, item management, and rich customization options for Windows Forms applications.

这是一份实现和自定义EditableList控件的完整指南，EditableList是功能强大的列表框组件，可为Windows Forms应用提供内联编辑、列表项管理和丰富的自定义选项。

When to Use This Skill

何时使用本技能

Use this skill when the user needs to:

Implement an EditableList control in Windows Forms applications
Enable inline editing of list items directly within the list box
Manage dynamic lists where users can add, edit, or delete items at runtime
Populate lists from DataSource or manual entry
Integrate AutoComplete functionality with the editing TextBox
Customize appearance including embedded controls, scrolling, and layout
Apply modern themes (Metro, Office2016) to the editable list
Handle editing events and user interactions
Configure dock padding and control sizing
Set up embedded controls (Button, TextBox, ListBox) within EditableList

The EditableList control is ideal for scenarios requiring user-editable collections, form data entry, tag management, or any interface where inline list editing improves usability.

当用户需要实现以下需求时可使用本技能：

在Windows Forms应用中实现EditableList控件
支持直接在列表框内对列表项进行内联编辑
管理动态列表，允许用户在运行时新增、编辑或删除列表项
从DataSource或手动录入填充列表内容
为编辑用TextBox集成AutoComplete功能
自定义外观，包括内置控件、滚动效果和布局
为可编辑列表应用现代化主题（Metro、Office2016）
处理编辑事件和用户交互
配置停靠内边距和控件尺寸
在EditableList内设置内置控件（Button、TextBox、ListBox）

EditableList控件非常适合需要用户可编辑集合、表单数据录入、标签管理，或是任何通过内联列表编辑提升易用性的场景。

Component Overview

组件概述

The EditableList (also known as Editable ListBox) is a composite control that combines a ListBox, TextBox, and optional Button to provide inline editing capabilities. Users can select items and edit them directly within the list interface.

Key Capabilities:

Inline Editing: Click an item to edit it directly in-place
DataSource Binding: Connect to data sources or populate manually
Embedded Controls: Access and configure child Button, TextBox, and ListBox
AutoComplete Integration: Add intelligent text suggestions during editing
Modern Styling: Support for Metro and Office2016 themes with color schemes
Flexible Layout: AutoScroll, dock padding, and size configuration
Visual Customization: Control button visibility and appearance

Embedded Controls:

Button: Optional button for additional actions (controlled by WantButton property)
TextBox: Used for inline editing of selected items
ListBox: Contains the list items with full ListBox functionality

EditableList（也叫可编辑列表框）是一个复合控件，组合了ListBox、TextBox和可选Button，可提供内联编辑能力。用户可以选中列表项，直接在列表界面内对其进行编辑。

核心能力：

内联编辑：点击列表项即可直接原地编辑
DataSource绑定：可连接数据源或手动填充内容
内置控件：可访问和配置子Button、TextBox和ListBox
AutoComplete集成：编辑时可添加智能文本建议
现代化样式：支持Metro和Office2016主题及配色方案
灵活布局：支持自动滚动、停靠内边距和尺寸配置
视觉自定义：可控制按钮可见性和外观

内置控件：

Button：用于额外操作的可选按钮（由WantButton属性控制）
TextBox：用于选中项的内联编辑
ListBox：包含列表项，具备完整ListBox功能

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and assembly deployment
Adding control via Visual Studio designer
Adding control programmatically via code
Required namespace imports
Basic initialization and setup
Understanding embedded controls

📄 阅读： references/getting-started.md

安装与程序集部署
通过Visual Studio设计器添加控件
通过代码编程方式添加控件
必要的命名空间导入
基础初始化与搭建
了解内置控件

Populating and Editing the List

列表填充与编辑

📄 Read: references/populating-editing.md

Populating via DataSource binding
Manual population through property editor
Runtime editing workflow
Item selection and inline editing process
ListBox.Items manipulation
Complete code examples (C# and VB.NET)

📄 阅读： references/populating-editing.md

通过DataSource绑定填充内容
通过属性编辑器手动填充
运行时编辑工作流
列表项选择与内联编辑流程
ListBox.Items操作
完整代码示例（C#和VB.NET）

Appearance and Behavior Configuration

外观与行为配置

📄 Read: references/appearance-behavior.md

Embedded controls overview and access
AutoScroll configuration for large lists
Dock padding for layout control
WantButton property for button visibility
Control sizing and positioning
Practical configuration examples

📄 阅读： references/appearance-behavior.md

内置控件概述与访问
长列表的自动滚动配置
用于布局控制的停靠内边距
控制按钮可见性的WantButton属性
控件尺寸与位置设置
实用配置示例

AutoComplete Integration

AutoComplete集成

📄 Read: references/autocomplete-integration.md

Setting up AutoComplete component
Associating AutoComplete with EditableList TextBox
DataSource configuration for suggestions
AutoCompleteModes options
Form load event implementation
Complete integration example

📄 阅读： references/autocomplete-integration.md

AutoComplete组件搭建
将AutoComplete与EditableList的TextBox关联
建议内容的DataSource配置
AutoCompleteModes选项
窗体加载事件实现
完整集成示例

Styling and Theming

样式与主题

📄 Read: references/styling-themes.md

Visual styles (Default, Metro, Office2016)
Applying Style property
Office2016 color schemes (Colorful, White, DarkGray, Black)
Theme consistency across forms
Complete styling code examples

📄 阅读： references/styling-themes.md

视觉样式（默认、Metro、Office2016）
Style属性应用
Office2016配色方案（Colorful、White、DarkGray、Black）
跨窗体主题一致性
完整样式代码示例

Quick Start

快速开始

Basic Implementation (Designer)

基础实现（设计器方式）

Add Control via Toolbox:
- Open your form in Visual Studio designer
- Locate EditableList in the toolbox (Syncfusion Controls section)
- Drag and drop onto your form
- Assemblies are added automatically
Configure in Properties Window:
- Set Size, Location, and other basic properties
- Expand ListBox property to configure items
- Set Style property for modern appearance

通过工具箱添加控件：
- 在Visual Studio设计器中打开你的窗体
- 在工具箱（Syncfusion Controls分类）中找到EditableList
- 拖拽到你的窗体上
- 程序集会自动添加
在属性窗口配置：
- 设置尺寸、位置和其他基础属性
- 展开ListBox属性配置列表项
- 设置Style属性获得现代化外观

Basic Implementation (Code)

基础实现（代码方式）

csharp

using Syncfusion.Windows.Forms.Tools;

namespace MyWinFormsApp
{
    public partial class Form1 : Form
    {
        private EditableList editableList1;
        
        public Form1()
        {
            InitializeComponent();
            SetupEditableList();
        }
        
        private void SetupEditableList()
        {
            // Create and initialize
            this.editableList1 = new EditableList();
            this.editableList1.Location = new System.Drawing.Point(20, 20);
            this.editableList1.Size = new System.Drawing.Size(300, 200);
            
            // Populate items
            this.editableList1.ListBox.Items.AddRange(new object[] {
                "Item 1",
                "Item 2", 
                "Item 3"
            });
            
            // Apply modern style
            this.editableList1.Style = Syncfusion.Windows.Forms.Appearance.Office2016;
            
            // Add to form
            this.Controls.Add(this.editableList1);
        }
    }
}

vbnet

Imports Syncfusion.Windows.Forms.Tools

Public Class Form1
    Private editableList1 As EditableList
    
    Public Sub New()
        InitializeComponent()
        SetupEditableList()
    End Sub
    
    Private Sub SetupEditableList()
        ' Create and initialize
        Me.editableList1 = New EditableList()
        Me.editableList1.Location = New System.Drawing.Point(20, 20)
        Me.editableList1.Size = New System.Drawing.Size(300, 200)
        
        ' Populate items
        Me.editableList1.ListBox.Items.AddRange(New Object() {
            "Item 1",
            "Item 2",
            "Item 3"
        })
        
        ' Apply modern style
        Me.editableList1.Style = Syncfusion.Windows.Forms.Appearance.Office2016
        
        ' Add to form
        Me.Controls.Add(Me.editableList1)
    End Sub
End Class

csharp

using Syncfusion.Windows.Forms.Tools;

namespace MyWinFormsApp
{
    public partial class Form1 : Form
    {
        private EditableList editableList1;
        
        public Form1()
        {
            InitializeComponent();
            SetupEditableList();
        }
        
        private void SetupEditableList()
        {
            // Create and initialize
            this.editableList1 = new EditableList();
            this.editableList1.Location = new System.Drawing.Point(20, 20);
            this.editableList1.Size = new System.Drawing.Size(300, 200);
            
            // Populate items
            this.editableList1.ListBox.Items.AddRange(new object[] {
                "Item 1",
                "Item 2", 
                "Item 3"
            });
            
            // Apply modern style
            this.editableList1.Style = Syncfusion.Windows.Forms.Appearance.Office2016;
            
            // Add to form
            this.Controls.Add(this.editableList1);
        }
    }
}

vbnet

Imports Syncfusion.Windows.Forms.Tools

Public Class Form1
    Private editableList1 As EditableList
    
    Public Sub New()
        InitializeComponent()
        SetupEditableList()
    End Sub
    
    Private Sub SetupEditableList()
        ' Create and initialize
        Me.editableList1 = New EditableList()
        Me.editableList1.Location = New System.Drawing.Point(20, 20)
        Me.editableList1.Size = New System.Drawing.Size(300, 200)
        
        ' Populate items
        Me.editableList1.ListBox.Items.AddRange(New Object() {
            "Item 1",
            "Item 2",
            "Item 3"
        })
        
        ' Apply modern style
        Me.editableList1.Style = Syncfusion.Windows.Forms.Appearance.Office2016
        
        ' Add to form
        Me.Controls.Add(Me.editableList1)
    End Sub
End Class

Common Patterns

常用模式

Pattern 1: DataSource Binding

模式1：DataSource绑定

csharp

// Bind to a data source
List<string> dataSource = new List<string>();
dataSource.Add("Product A");
dataSource.Add("Product B");
dataSource.Add("Product C");

this.editableList1.ListBox.DataSource = dataSource;

csharp

// Bind to a data source
List<string> dataSource = new List<string>();
dataSource.Add("Product A");
dataSource.Add("Product B");
dataSource.Add("Product C");

this.editableList1.ListBox.DataSource = dataSource;

Pattern 2: Runtime Editing Workflow

模式2：运行时编辑工作流

User Interaction:
1. Click on an item to select it
2. Click again to enter edit mode (TextBox appears)
3. Edit the text in the TextBox
4. Change focus (click elsewhere, press Tab)
5. List updates automatically with edited value

用户交互流程：
1. 点击列表项选中
2. 再次点击进入编辑模式（显示TextBox）
3. 在TextBox中编辑文本
4. 切换焦点（点击其他位置、按下Tab键）
5. 列表自动更新为编辑后的值

Pattern 3: Enable AutoScroll for Large Lists

模式3：为长列表启用自动滚动

csharp

// Enable automatic scrollbars
this.editableList1.AutoScroll = true;
this.editableList1.AutoScrollMargin = new System.Drawing.Size(2, 2);
this.editableList1.AutoScrollMinSize = new System.Drawing.Size(3, 3);

csharp

// Enable automatic scrollbars
this.editableList1.AutoScroll = true;
this.editableList1.AutoScrollMargin = new System.Drawing.Size(2, 2);
this.editableList1.AutoScrollMinSize = new System.Drawing.Size(3, 3);

Pattern 4: Show Button While Editing

模式4：编辑时显示按钮

csharp

// Display button on the right during editing
this.editableList1.WantButton = true;

// Handle button click if needed
this.editableList1.Button.Click += (s, e) => {
    MessageBox.Show("Button clicked!");
};

csharp

// Display button on the right during editing
this.editableList1.WantButton = true;

// Handle button click if needed
this.editableList1.Button.Click += (s, e) => {
    MessageBox.Show("Button clicked!");
};

Pattern 5: Apply Modern Theme

模式5：应用现代化主题

csharp

// Apply Office2016 theme with color scheme
this.editableList1.Style = Syncfusion.Windows.Forms.Appearance.Office2016;
this.editableList1.Office2016ColorScheme = ScrollBarOffice2016ColorScheme.Colorful;

csharp

// Apply Office2016 theme with color scheme
this.editableList1.Style = Syncfusion.Windows.Forms.Appearance.Office2016;
this.editableList1.Office2016ColorScheme = ScrollBarOffice2016ColorScheme.Colorful;

Key Properties and Events

核心属性与事件

Essential Properties

常用属性

Property	Description	Example
ListBox	Access to embedded ListBox control	`editableList1.ListBox.Items.Add("Item")`
TextBox	Access to editing TextBox control	`editableList1.TextBox.Text`
Button	Access to optional button control	`editableList1.Button.Click += Handler`
WantButton	Show/hide button during editing	`editableList1.WantButton = true`
AutoScroll	Enable automatic scrollbars	`editableList1.AutoScroll = true`
Style	Visual appearance style	`editableList1.Style = Appearance.Office2016`
DockPadding	Padding for docked controls	`editableList1.DockPadding.All = 5`

属性	描述	示例
ListBox	访问内置ListBox控件	`editableList1.ListBox.Items.Add("Item")`
TextBox	访问编辑用TextBox控件	`editableList1.TextBox.Text`
Button	访问可选按钮控件	`editableList1.Button.Click += Handler`
WantButton	编辑时显示/隐藏按钮	`editableList1.WantButton = true`
AutoScroll	启用自动滚动条	`editableList1.AutoScroll = true`
Style	视觉外观样式	`editableList1.Style = Appearance.Office2016`
DockPadding	停靠控件的内边距	`editableList1.DockPadding.All = 5`

Common Events

常用事件

Access events through embedded controls:

csharp

// ListBox events
this.editableList1.ListBox.SelectedIndexChanged += ListBox_SelectedIndexChanged;
this.editableList1.ListBox.Click += ListBox_Click;

// TextBox events
this.editableList1.TextBox.TextChanged += TextBox_TextChanged;
this.editableList1.TextBox.Leave += TextBox_Leave;

// Button events (if WantButton = true)
this.editableList1.Button.Click += Button_Click;

通过内置控件访问事件：

csharp

// ListBox事件
this.editableList1.ListBox.SelectedIndexChanged += ListBox_SelectedIndexChanged;
this.editableList1.ListBox.Click += ListBox_Click;

// TextBox事件
this.editableList1.TextBox.TextChanged += TextBox_TextChanged;
this.editableList1.TextBox.Leave += TextBox_Leave;

// Button事件（当WantButton = true时可用）
this.editableList1.Button.Click += Button_Click;

Common Use Cases

常见使用场景

Use Case 1: Tag Management System

场景1：标签管理系统

User needs to manage tags where users can add, edit, and remove tags inline. → Use DataSource binding + enable inline editing + add item selection handling

用户需要管理标签，支持内联新增、编辑、删除标签。 → 采用DataSource绑定 + 启用内联编辑 + 添加列表项选中处理逻辑

Use Case 2: Dynamic Category List

场景2：动态分类列表

User wants a settings form where categories can be edited directly in the list. → Use manual item population + WantButton for delete functionality + style for modern UI

用户需要在设置表单中直接编辑列表内的分类。 → 采用手动填充列表项 + WantButton实现删除功能 + 配置样式实现现代化UI

Use Case 3: Email Recipient List

场景3：邮件收件人列表

User needs an editable list of email addresses with autocomplete suggestions. → Use AutoComplete integration + DataSource for suggestions + validation on TextBox.Leave

用户需要可编辑的邮件地址列表，支持自动补全建议。 → 采用AutoComplete集成 + 绑定建议内容DataSource + 在TextBox.Leave事件中添加校验逻辑

Use Case 4: Todo List Manager

场景4：待办事项管理器

User wants a simple todo list with inline editing capabilities. → Use basic setup + runtime editing + handle ListBox events for task completion

用户需要简单的待办列表，支持内联编辑功能。 → 采用基础配置 + 运行时编辑 + 监听ListBox事件处理任务完成状态

Use Case 5: Preferences Editor

场景5：偏好设置编辑器

User needs a form where users can edit configuration values in a list format. → Use DataSource binding + themed appearance + dock padding for layout

用户需要以列表格式编辑配置值的表单。 → 采用DataSource绑定 + 主题化外观 + 配置停靠内边距优化布局

Tips and Best Practices

提示与最佳实践

Use DataSource for Dynamic Data: Bind to collections for automatic updates
Handle TextBox.Leave Event: Validate input when editing completes
Enable AutoScroll: For lists with many items to prevent overflow
Apply Consistent Theming: Use the same Style across all controls in your form
Access Embedded Controls: Configure Button, TextBox, ListBox for full customization
Consider AutoComplete: Improves user experience for predictable inputs
Test Editing Flow: Ensure click-to-edit behavior works smoothly
Set Appropriate Sizes: Give adequate height for comfortable item viewing and editing

动态数据优先使用DataSource绑定：绑定集合可实现自动更新
处理TextBox.Leave事件：编辑完成时对输入内容进行校验
启用自动滚动：列表项较多时避免内容溢出
应用一致的主题：窗体中所有控件使用相同的Style设置
访问内置控件：配置Button、TextBox、ListBox实现完全自定义
考虑添加AutoComplete：对于可预测的输入内容可大幅提升用户体验
测试编辑流程：确保点击编辑的交互流程流畅可用
设置合适的尺寸：预留足够高度保证列表项查看和编辑的舒适度

Troubleshooting

问题排查

Issue: Items not editable → Ensure proper focus handling and check if TextBox is accessible

Issue: Scrollbars not appearing → Set AutoScroll = true and configure AutoScrollMinSize

Issue: Theme not applying → Verify Style property is set and Office2016ColorScheme for Office2016 style

Issue: AutoComplete not working → Check AutoComplete.SetAutoComplete() is called with correct parameters in Form_Load

Issue: Button not visible during editing → Set WantButton = true property

问题：列表项无法编辑 → 确认焦点处理逻辑正确，检查TextBox是否可正常访问

问题：滚动条不显示 → 检查AutoScroll是否设置为true，并配置AutoScrollMinSize参数

问题：主题不生效 → 确认Style属性已正确设置，使用Office2016风格时需配置Office2016ColorScheme参数

问题：AutoComplete不生效 → 检查Form_Load事件中是否以正确参数调用AutoComplete.SetAutoComplete()方法

问题：编辑时按钮不显示 → 确认WantButton属性已设置为true