syncfusion-winforms-checkbox（同步融合 winforms 复选框）

Implementing CheckBoxAdv in Windows Forms

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

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.

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

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

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

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

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

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

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

Quick Start Example

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

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

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

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

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

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

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

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

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

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

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

Alignment Properties

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

Behavior Properties

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

Common Use Cases

Use Case 1: Settings Dialog

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

Use Case 2: List Item Selection

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

Use Case 3: Form Validation

Create read-only checkboxes to display validation status:

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

Use Case 4: Enhanced UI Design

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

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