syncfusion-winforms-checkbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing CheckBoxAdv in Windows Forms

在 Windows Forms 中实现 CheckBoxAdv

When to Use This Skill

何时使用本指南

Use this skill whenever the user needs to:

Implement advanced checkbox controls in Windows Forms applications
Create checkboxes with checked, unchecked, and indeterminate states
Apply gradient backgrounds, custom borders, or shadow text to checkboxes
Configure checkbox and text alignment independently
Associate integer or string values with checkbox states
Handle checkbox state change events
Bind CheckBoxAdv controls to SQL database fields
Customize checkbox appearance beyond standard Windows Forms controls
Implement three-state checkboxes with tristate support
Create read-only or auto-sized checkbox controls

当用户有以下需求时可使用本指南：

在 Windows Forms 应用中实现高级复选框控件
创建包含选中、未选中、不确定三种状态的复选框
为复选框应用渐变背景、自定义边框或阴影文本效果
独立配置复选框和文本的对齐方式
将整数或字符串值与复选框状态关联
处理复选框状态变更事件
将 CheckBoxAdv 控件绑定到 SQL 数据库字段
自定义复选框外观，突破 Windows Forms 标准控件的限制
实现支持三态功能的三态复选框
创建只读或自适应大小的复选框控件

Component Overview

组件概述

The CheckBoxAdv is an advanced checkbox control for Windows Forms that extends the standard CheckBox with enhanced visual and functional capabilities. It supports gradient backgrounds, custom borders (2D and 3D), shadow text, independent text and checkbox alignment, image checkboxes, and comprehensive data binding options.

CheckBoxAdv 是面向 Windows Forms 的高级复选框控件，在标准 CheckBox 的基础上扩展了更强大的视觉和功能能力。它支持渐变背景、自定义边框（2D和3D）、阴影文本、文本与复选框独立对齐、图片复选框以及完善的数据绑定选项。

Key Capabilities

核心能力

Three States: Checked, Unchecked, and Indeterminate with tristate support
Value Association: Bind integer and string values to each state
Visual Customization: Gradient backgrounds, custom borders, shadow text
Flexible Alignment: Independent positioning of text and checkbox
Data Binding: Connect to SQL databases with BoolValue and IntValue properties
Event Handling: Respond to CheckStateChanged and CheckedChanged events
Behavior Control: AutoHeight, ReadOnlyMode, and focus rectangle options

三种状态：支持三态模式，包含选中、未选中、不确定状态
值关联：可为每种状态绑定整数和字符串值
视觉自定义：渐变背景、自定义边框、阴影文本
灵活对齐：文本和复选框可独立定位
数据绑定：通过 BoolValue 和 IntValue 属性连接到 SQL 数据库
事件处理：可响应 CheckStateChanged 和 CheckedChanged 事件
行为控制：支持自适应高度、只读模式、焦点矩形配置

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Assembly deployment and NuGet packages
Adding CheckBoxAdv via designer
Adding CheckBoxAdv programmatically
Required namespaces (Syncfusion.Windows.Forms.Tools)
Basic initialization and setup
Setting initial checkbox state

📄 阅读： references/getting-started.md

程序集部署与 NuGet 包
通过设计器添加 CheckBoxAdv
通过代码方式添加 CheckBoxAdv
所需命名空间（Syncfusion.Windows.Forms.Tools）
基础初始化与配置
设置复选框初始状态

States and Configuration

状态与配置

📄 Read: references/states-and-values.md

CheckState property (Checked, Unchecked, Indeterminate)
Checked property for boolean state
Tristate property for three-state mode
Associating integer values with states (CheckedInt, UncheckedInt, IndeterminateInt)
Associating string values with states (CheckedString, UncheckedString, IndeterminateString)
Using BoolValue, IntValue, and StringValue properties
When to use each value type

📄 阅读： references/states-and-values.md

CheckState 属性（选中、未选中、不确定）
用于布尔状态的 Checked 属性
控制三态模式的 Tristate 属性
为状态关联整数值（CheckedInt、UncheckedInt、IndeterminateInt）
为状态关联字符串值（CheckedString、UncheckedString、IndeterminateString）
BoolValue、IntValue、StringValue 属性的使用
不同值类型的适用场景

Text and Alignment

文本与对齐

📄 Read: references/text-and-alignment.md

Text shadow effects (TextShadow, ShadowColor, ShadowOffset)
Text wrapping with WrapText property
Text alignment options (TextContentAlignment)
CheckBox alignment options (CheckAlign)
Positioning options (TopLeft, MiddleCenter, BottomRight, etc.)
Combining text and checkbox alignment

📄 阅读： references/text-and-alignment.md

文本阴影效果（TextShadow、ShadowColor、ShadowOffset）
通过 WrapText 属性实现文本换行
文本对齐选项（TextContentAlignment）
复选框对齐选项（CheckAlign）
定位选项（TopLeft、MiddleCenter、BottomRight 等）
文本与复选框对齐方式的组合配置

Appearance and Behavior

外观与行为

📄 Read: references/appearance-and-behavior.md

Focus rectangle visibility (DrawFocusRectangle)
Automatic height calculation (AutoHeight)
Read-only mode (ReadOnlyMode)
Gradient backgrounds (BackgroundStyle, GradientStart, GradientEnd)
Border styles (Border3DStyle, BorderStyle, BorderSingle)
Border colors (BorderColor, HotBorderColor)
Mouse hover effects

📄 阅读： references/appearance-and-behavior.md

焦点矩形可见性（DrawFocusRectangle）
自动高度计算（AutoHeight）
只读模式（ReadOnlyMode）
渐变背景（BackgroundStyle、GradientStart、GradientEnd）
边框样式（Border3DStyle、BorderStyle、BorderSingle）
边框颜色（BorderColor、HotBorderColor）
鼠标悬停效果

Events and Interactions

事件与交互

📄 Read: references/events.md

CheckStateChanged event
CheckedChanged event
Event handler patterns
Responding to state changes
Event timing and order
Best practices for event handling

📄 阅读： references/events.md

CheckStateChanged 事件
CheckedChanged 事件
事件处理模式
响应状态变更
事件触发时机与顺序
事件处理最佳实践

Data Binding

数据绑定

📄 Read: references/data-binding.md

Binding to SQL databases
BoolValue property for bit/boolean fields
IntValue property for integer fields
SqlDataAdapter and DataTable usage
Connection string configuration
Common data binding patterns
Troubleshooting binding issues

📄 阅读： references/data-binding.md

绑定到 SQL 数据库
用于位/布尔字段的 BoolValue 属性
用于整数字段的 IntValue 属性
SqlDataAdapter 和 DataTable 用法
连接字符串配置
常见数据绑定模式
绑定问题排查

Quick Start Example

快速入门示例

csharp

using Syncfusion.Windows.Forms.Tools;

// Create CheckBoxAdv instance
CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Enable Feature";
checkBoxAdv1.Size = new Size(150, 25);
checkBoxAdv1.Location = new Point(20, 20);

// Set initial state
checkBoxAdv1.Checked = true;

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

// Handle state changes
checkBoxAdv1.CheckedChanged += (sender, e) => {
    MessageBox.Show($"Checkbox is now: {checkBoxAdv1.Checked}");
};

csharp

using Syncfusion.Windows.Forms.Tools;

// Create CheckBoxAdv instance
CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Enable Feature";
checkBoxAdv1.Size = new Size(150, 25);
checkBoxAdv1.Location = new Point(20, 20);

// Set initial state
checkBoxAdv1.Checked = true;

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

// Handle state changes
checkBoxAdv1.CheckedChanged += (sender, e) => {
    MessageBox.Show($"Checkbox is now: {checkBoxAdv1.Checked}");
};

Common Patterns

常用实现模式

Pattern 1: Three-State Checkbox

模式1：三态复选框

When the user needs a checkbox with checked, unchecked, and indeterminate states:

csharp

CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Select All";
checkBoxAdv1.Tristate = true;
checkBoxAdv1.CheckState = CheckState.Indeterminate;

checkBoxAdv1.CheckStateChanged += (sender, e) => {
    switch(checkBoxAdv1.CheckState) {
        case CheckState.Checked:
            // Select all items
            break;
        case CheckState.Unchecked:
            // Deselect all items
            break;
        case CheckState.Indeterminate:
            // Partial selection
            break;
    }
};

适用场景：需要包含选中、未选中、不确定三种状态的复选框时：

csharp

CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Select All";
checkBoxAdv1.Tristate = true;
checkBoxAdv1.CheckState = CheckState.Indeterminate;

checkBoxAdv1.CheckStateChanged += (sender, e) => {
    switch(checkBoxAdv1.CheckState) {
        case CheckState.Checked:
            // Select all items
            break;
        case CheckState.Unchecked:
            // Deselect all items
            break;
        case CheckState.Indeterminate:
            // Partial selection
            break;
    }
};

Pattern 2: Checkbox with Custom Styling

模式2：自定义样式复选框

When the user needs a visually enhanced checkbox with gradient background and borders:

csharp

CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Styled Checkbox";

// Gradient background
checkBoxAdv1.BackgroundStyle = CheckBoxAdvBackStyle.HorizontalGradient;
checkBoxAdv1.GradientStart = Color.LightBlue;
checkBoxAdv1.GradientEnd = Color.DarkBlue;

// Custom border
checkBoxAdv1.BorderStyle = BorderStyle.FixedSingle;
checkBoxAdv1.BorderColor = Color.Navy;
checkBoxAdv1.HotBorderColor = Color.Red; // On mouse hover

// Shadow text
checkBoxAdv1.TextShadow = true;
checkBoxAdv1.ShadowColor = Color.Gray;
checkBoxAdv1.ShadowOffset = new Point(2, 2);

适用场景：需要带有渐变背景和边框的视觉增强型复选框时：

csharp

CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Styled Checkbox";

// Gradient background
checkBoxAdv1.BackgroundStyle = CheckBoxAdvBackStyle.HorizontalGradient;
checkBoxAdv1.GradientStart = Color.LightBlue;
checkBoxAdv1.GradientEnd = Color.DarkBlue;

// Custom border
checkBoxAdv1.BorderStyle = BorderStyle.FixedSingle;
checkBoxAdv1.BorderColor = Color.Navy;
checkBoxAdv1.HotBorderColor = Color.Red; // On mouse hover

// Shadow text
checkBoxAdv1.TextShadow = true;
checkBoxAdv1.ShadowColor = Color.Gray;
checkBoxAdv1.ShadowOffset = new Point(2, 2);

Pattern 3: Data-Bound Checkbox

模式3：数据绑定复选框

When the user needs to bind a checkbox to a database field:

csharp

// For boolean/bit fields
using (SqlConnection conn = new SqlConnection(connectionString)) {
    conn.Open();
    SqlDataAdapter adapter = new SqlDataAdapter("SELECT * FROM Settings", conn);
    DataTable dataTable = new DataTable();
    adapter.Fill(dataTable);
    
    checkBoxAdv1.DataBindings.Add("BoolValue", dataTable, "IsEnabled");
}

// For integer fields (values: -1, 0, 1)
checkBoxAdv1.DataBindings.Add("IntValue", dataTable, "StatusCode");

适用场景：需要将复选框绑定到数据库字段时：

csharp

// For boolean/bit fields
using (SqlConnection conn = new SqlConnection(connectionString)) {
    conn.Open();
    SqlDataAdapter adapter = new SqlDataAdapter("SELECT * FROM Settings", conn);
    DataTable dataTable = new DataTable();
    adapter.Fill(dataTable);
    
    checkBoxAdv1.DataBindings.Add("BoolValue", dataTable, "IsEnabled");
}

// For integer fields (values: -1, 0, 1)
checkBoxAdv1.DataBindings.Add("IntValue", dataTable, "StatusCode");

Pattern 4: Read-Only Checkbox Display

模式4：只读复选框展示

When the user needs to display checkbox state without allowing user changes:

csharp

CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Read-Only Status";
checkBoxAdv1.Checked = true;
checkBoxAdv1.ReadOnlyMode = true;
checkBoxAdv1.DrawFocusRectangle = false;

适用场景：需要展示复选框状态但不允许用户修改时：

csharp

CheckBoxAdv checkBoxAdv1 = new CheckBoxAdv();
checkBoxAdv1.Text = "Read-Only Status";
checkBoxAdv1.Checked = true;
checkBoxAdv1.ReadOnlyMode = true;
checkBoxAdv1.DrawFocusRectangle = false;

Key Properties

核心属性

State Properties

状态属性

Checked (bool): Gets or sets the checked state (true/false)
CheckState (CheckState): Gets or sets the state (Checked, Unchecked, Indeterminate)
Tristate (bool): Enables three-state mode with user access to indeterminate

Checked（bool）：获取或设置选中状态（true/false）
CheckState（CheckState）：获取或设置状态（Checked、Unchecked、Indeterminate）
Tristate（bool）：开启三态模式，允许用户切换到不确定状态

Value Properties

值属性

BoolValue (bool): Boolean representation of state (for data binding)
IntValue (int): Integer representation of state
StringValue (string): String representation of current state
CheckedInt/UncheckedInt/IndeterminateInt (int): Integer values for each state
CheckedString/UncheckedString/IndeterminateString (string): String values for each state

BoolValue（bool）：状态的布尔表示（用于数据绑定）
IntValue（int）：状态的整数表示
StringValue（string）：当前状态的字符串表示
CheckedInt/UncheckedInt/IndeterminateInt（int）：每种状态对应的整数值
CheckedString/UncheckedString/IndeterminateString（string）：每种状态对应的字符串值

Appearance Properties

外观属性

BackgroundStyle (CheckBoxAdvBackStyle): Background style (Default, HorizontalGradient, VerticalGradient)
GradientStart/GradientEnd (Color): Gradient colors
BorderStyle (BorderStyle): Border style (FixedSingle, Fixed3D, None)
BorderColor/HotBorderColor (Color): Border colors
TextShadow (bool): Enable text shadow
DrawFocusRectangle (bool): Show focus rectangle

BackgroundStyle（CheckBoxAdvBackStyle）：背景样式（Default、HorizontalGradient、VerticalGradient）
GradientStart/GradientEnd（Color）：渐变颜色
BorderStyle（BorderStyle）：边框样式（FixedSingle、Fixed3D、None）
BorderColor/HotBorderColor（Color）：边框颜色
TextShadow（bool）：开启文本阴影
DrawFocusRectangle（bool）：展示焦点矩形

Alignment Properties

对齐属性

TextContentAlignment (ContentAlignment): Text position
CheckAlign (ContentAlignment): Checkbox position

TextContentAlignment（ContentAlignment）：文本位置
CheckAlign（ContentAlignment）：复选框位置

Behavior Properties

行为属性

AutoHeight (bool): Automatically calculate height
ReadOnlyMode (bool): Prevent user interaction
WrapText (bool): Enable text wrapping

AutoHeight（bool）：自动计算高度
ReadOnlyMode（bool）：禁止用户交互
WrapText（bool）：开启文本换行

Common Use Cases

常见使用场景

Use Case 1: Settings Dialog

场景1：设置对话框

Create checkboxes for application settings with state persistence:

Use BoolValue for simple on/off settings
Bind directly to configuration database
Handle CheckedChanged to save settings immediately

为应用设置创建支持状态持久化的复选框：

使用 BoolValue 存储简单开关设置
直接绑定到配置数据库
监听 CheckedChanged 事件即时保存设置

Use Case 2: List Item Selection

场景2：列表项选择

Implement "Select All" with indeterminate state:

Use Tristate property for three-state behavior
CheckState.Indeterminate for partial selections
Update state based on child item selection

实现支持不确定状态的「全选」功能：

使用 Tristate 属性开启三态行为
CheckState.Indeterminate 表示部分选中
根据子项选中状态更新全选框状态

Use Case 3: Form Validation

场景3：表单验证

Create read-only checkboxes to display validation status:

Set ReadOnlyMode = true
Update Checked state programmatically
Use custom colors to indicate status

创建只读复选框展示验证状态：

设置 ReadOnlyMode = true
通过代码更新 Checked 状态
使用自定义颜色标识状态

Use Case 4: Enhanced UI Design

场景4：增强型UI设计

Build visually rich checkboxes matching application theme:

Apply gradient backgrounds
Configure custom borders and hover effects
Add shadow text for depth
Position text and checkbox independently

构建符合应用主题的视觉丰富的复选框：

应用渐变背景
配置自定义边框和悬停效果
添加阴影文本增强层次感
独立定位文本和复选框

Use Case 5: Data Entry Forms

场景5：数据录入表单

Bind checkboxes to database records:

Use IntValue for status codes (0, 1, or -1)
Use BoolValue for yes/no fields
Associate custom integer/string values with states

将复选框绑定到数据库记录：

使用 IntValue 存储状态码（0、1 或 -1）
使用 BoolValue 存储是/否字段
为状态关联自定义整数/字符串值