syncfusion-winforms-radio-button

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing RadioButtonAdv in Syncfusion WinForms

在Syncfusion WinForms中实现RadioButtonAdv

This skill guides you in implementing Syncfusion WinForms RadioButtonAdv control—an enhanced radio button with advanced styling options including Office themes, gradient backgrounds, text shadow effects, custom images, and professional appearance features.

本指南将指导你实现 Syncfusion WinForms RadioButtonAdv 控件——这是一款增强型单选按钮，具备高级样式选项，包括Office主题、渐变背景、文字阴影效果、自定义图片等专业外观特性。

When to Use This Skill

何时使用本指南

Use this skill when the user needs to:

Implement enhanced radio buttons with modern styling beyond standard RadioButton
Apply Office themes (Office2007, Office2016 Colorful/White/Black/DarkGray)
Use Metro-style radio buttons for modern UI design
Add text shadow effects with custom colors and offsets
Create gradient backgrounds for radio buttons
Display custom images for different radio button states
Apply 2D or 3D border styles to radio buttons
Configure text and button alignment for custom layouts
Associate integer or string values with radio button states
Build professional forms with consistent Office-style theming
Replace standard RadioButton with visually enhanced alternatives

RadioButtonAdv is ideal when visual appearance and theming are important for radio button controls.

当用户需要完成以下需求时使用本指南：

实现外观远超标准RadioButton的现代化增强型单选按钮
应用Office主题（Office2007、Office2016 多彩/白色/黑色/深灰）
使用Metro风格单选按钮打造现代化UI设计
添加支持自定义颜色和偏移量的文字阴影效果
为单选按钮创建渐变背景
为单选按钮的不同状态展示自定义图片
为单选按钮应用2D或3D边框样式
为自定义布局配置文字与按钮对齐方式
为单选按钮状态关联整数或字符串值
构建具备统一Office风格主题的专业表单
用视觉效果更出色的替代方案替换标准RadioButton

RadioButtonAdv是单选按钮控件的视觉外观和主题效果非常重要时的理想选择。

Component Overview

组件概览

RadioButtonAdv is an advanced radio button control that extends the standard WinForms RadioButton with rich styling capabilities. It provides:

Theme Support: Office2007, Office2016, Metro, and Default themes
Text Effects: Shadow text with color and offset customization
Backgrounds: Gradient backgrounds with custom colors
Borders: 2D and 3D border style options
Images: Custom images for each check state
Alignment: Flexible text and button positioning
Value Association: Integer/string values per state
Behavior Options: Auto-height, focus rectangle, click events

Key Difference from Standard RadioButton: RadioButtonAdv adds visual styling and theming capabilities while maintaining standard radio button functionality.

RadioButtonAdv 是一款高级单选按钮控件，在标准WinForms RadioButton的基础上扩展了丰富的样式能力，它提供：

主题支持：Office2007、Office2016、Metro和默认主题
文字效果：支持颜色和偏移量自定义的阴影文字
背景：支持自定义颜色的渐变背景
边框：2D和3D边框样式选项
图片：每个选中状态对应自定义图片
对齐：灵活的文字和按钮位置设置
值关联：每个状态可关联整数/字符串值
行为选项：自动高度、焦点框、点击事件

与标准RadioButton的核心差异： RadioButtonAdv在保留标准单选按钮功能的同时，新增了视觉样式和主题能力。

Documentation and Navigation Guide

文档与导航指南

Getting Started and Basic Setup

入门与基础设置

📄 Read: references/getting-started.md

Read this reference when users need:

Assembly dependencies and NuGet package installation
Creating RadioButtonAdv via designer or code
Basic properties (Text, Font, ForeColor, BackColor)
Adding RadioButtonAdv to forms
Understanding control hierarchy
Complete minimal working example

📄 阅读： references/getting-started.md

当用户需要以下内容时阅读此参考：

程序集依赖项和NuGet包安装
通过设计器或代码创建RadioButtonAdv
基础属性（Text、Font、ForeColor、BackColor）
向表单添加RadioButtonAdv
理解控件层级结构
完整的最小可运行示例

Themes and Visual Styles

主题与视觉样式

📄 Read: references/themes-and-styles.md

Read this reference when users need:

Enabling themes with ThemesEnabled property
Applying Style property (Default, Office2007, Metro, Office2016 variants)
Office2007ColorScheme (Managed, Blue, Silver, Black)
Custom managed colors for Office2007 theme
Complete themed examples
Professional Office-style appearance

📄 阅读： references/themes-and-styles.md

当用户需要以下内容时阅读此参考：

通过ThemesEnabled属性启用主题
应用Style属性（默认、Office2007、Metro、Office2016变体）
Office2007ColorScheme（托管、蓝色、银色、黑色）
为Office2007主题自定义托管颜色
完整的主题示例
专业的Office风格外观

Text Settings and Effects

文字设置与效果

📄 Read: references/text-settings.md

Read this reference when users need:

TextShadow property for shadow effects
ShadowColor customization
ShadowOffset positioning
WrapText for long text handling
Text effect examples
Text styling best practices

📄 阅读： references/text-settings.md

当用户需要以下内容时阅读此参考：

用于阴影效果的TextShadow属性
ShadowColor自定义
ShadowOffset位置设置
处理长文本的WrapText
文字效果示例
文字样式最佳实践

Appearance Customization

外观自定义

📄 Read: references/appearance-customization.md

Read this reference when users need:

Gradient backgrounds with custom colors
Border styles (2D and 3D options)
Alignment settings for text and button
Custom images for different states
Complete appearance customization
Advanced styling patterns

📄 阅读： references/appearance-customization.md

当用户需要以下内容时阅读此参考：

自定义颜色的渐变背景
边框样式（2D和3D选项）
文字和按钮的对齐设置
不同状态的自定义图片
完整的外观自定义
高级样式模式

Behavior Settings

行为设置

📄 Read: references/behavior-settings.md

Read this reference when users need:

AutoHeight for automatic height calculation
DrawFocusRectangle visibility control
RaiseEventOnClick event behavior
RadioButtonAdv Settings (integer/string value association)
Behavior configuration options

📄 阅读： references/behavior-settings.md

当用户需要以下内容时阅读此参考：

用于自动计算高度的AutoHeight
DrawFocusRectangle可见性控制
RaiseEventOnClick事件行为
RadioButtonAdv设置（整数/字符串值关联）
行为配置选项

Events

事件

📄 Read: references/events.md

Read this reference when users need:

Available RadioButtonAdv events
Click event handling
CheckedChanged event
Event best practices
Common event patterns

📄 阅读： references/events.md

当用户需要以下内容时阅读此参考：

RadioButtonAdv可用事件
Click事件处理
CheckedChanged事件
事件最佳实践
通用事件模式

Quick Start Example

快速入门示例

Here's a minimal example creating themed RadioButtonAdv controls:

csharp

using Syncfusion.Windows.Forms.Tools;
using System;
using System.Drawing;
using System.Windows.Forms;

public class RadioButtonExample : Form
{
    private RadioButtonAdv radioButtonAdv1;
    private RadioButtonAdv radioButtonAdv2;
    private RadioButtonAdv radioButtonAdv3;
    
    public RadioButtonExample()
    {
        // Create first radio button
        radioButtonAdv1 = new RadioButtonAdv();
        radioButtonAdv1.Text = "Option 1";
        radioButtonAdv1.Location = new Point(20, 20);
        radioButtonAdv1.Size = new Size(120, 21);
        radioButtonAdv1.Style = RadioButtonAdvStyle.Office2016Colorful;
        radioButtonAdv1.Checked = true;
        
        // Create second radio button
        radioButtonAdv2 = new RadioButtonAdv();
        radioButtonAdv2.Text = "Option 2";
        radioButtonAdv2.Location = new Point(20, 50);
        radioButtonAdv2.Size = new Size(120, 21);
        radioButtonAdv2.Style = RadioButtonAdvStyle.Office2016Colorful;
        
        // Create third radio button
        radioButtonAdv3 = new RadioButtonAdv();
        radioButtonAdv3.Text = "Option 3";
        radioButtonAdv3.Location = new Point(20, 80);
        radioButtonAdv3.Size = new Size(120, 21);
        radioButtonAdv3.Style = RadioButtonAdvStyle.Office2016Colorful;
        
        // Add to form
        this.Controls.Add(radioButtonAdv1);
        this.Controls.Add(radioButtonAdv2);
        this.Controls.Add(radioButtonAdv3);
        
        this.Text = "RadioButtonAdv Example";
        this.Size = new Size(300, 200);
    }
}

Result: Three Office2016-themed radio buttons with modern appearance.

以下是创建带主题的RadioButtonAdv控件的最小示例：

csharp

using Syncfusion.Windows.Forms.Tools;
using System;
using System.Drawing;
using System.Windows.Forms;

public class RadioButtonExample : Form
{
    private RadioButtonAdv radioButtonAdv1;
    private RadioButtonAdv radioButtonAdv2;
    private RadioButtonAdv radioButtonAdv3;
    
    public RadioButtonExample()
    {
        // Create first radio button
        radioButtonAdv1 = new RadioButtonAdv();
        radioButtonAdv1.Text = "Option 1";
        radioButtonAdv1.Location = new Point(20, 20);
        radioButtonAdv1.Size = new Size(120, 21);
        radioButtonAdv1.Style = RadioButtonAdvStyle.Office2016Colorful;
        radioButtonAdv1.Checked = true;
        
        // Create second radio button
        radioButtonAdv2 = new RadioButtonAdv();
        radioButtonAdv2.Text = "Option 2";
        radioButtonAdv2.Location = new Point(20, 50);
        radioButtonAdv2.Size = new Size(120, 21);
        radioButtonAdv2.Style = RadioButtonAdvStyle.Office2016Colorful;
        
        // Create third radio button
        radioButtonAdv3 = new RadioButtonAdv();
        radioButtonAdv3.Text = "Option 3";
        radioButtonAdv3.Location = new Point(20, 80);
        radioButtonAdv3.Size = new Size(120, 21);
        radioButtonAdv3.Style = RadioButtonAdvStyle.Office2016Colorful;
        
        // Add to form
        this.Controls.Add(radioButtonAdv1);
        this.Controls.Add(radioButtonAdv2);
        this.Controls.Add(radioButtonAdv3);
        
        this.Text = "RadioButtonAdv Example";
        this.Size = new Size(300, 200);
    }
}

效果： 三个具备现代化外观的Office2016主题单选按钮。

Common Patterns

通用模式

Themed Radio Button Group

带主题的单选按钮组

Pattern: Create a group of radio buttons with consistent Office2016 theming.

csharp

// Create GroupBox for radio buttons
GroupBox groupBox = new GroupBox();
groupBox.Text = "Select Option";
groupBox.Location = new Point(10, 10);
groupBox.Size = new Size(200, 120);

// Create themed radio buttons
string[] options = { "Small", "Medium", "Large" };
int yPos = 20;

foreach (string option in options)
{
    RadioButtonAdv radio = new RadioButtonAdv();
    radio.Text = option;
    radio.Location = new Point(10, yPos);
    radio.Style = RadioButtonAdvStyle.Office2016Colorful;
    radio.ThemesEnabled = true;
    groupBox.Controls.Add(radio);
    yPos += 30;
}

this.Controls.Add(groupBox);

When: User needs multiple related options with consistent theming.

模式： 创建一组具备统一Office2016主题的单选按钮。

csharp

// Create GroupBox for radio buttons
GroupBox groupBox = new GroupBox();
groupBox.Text = "Select Option";
groupBox.Location = new Point(10, 10);
groupBox.Size = new Size(200, 120);

// Create themed radio buttons
string[] options = { "Small", "Medium", "Large" };
int yPos = 20;

foreach (string option in options)
{
    RadioButtonAdv radio = new RadioButtonAdv();
    radio.Text = option;
    radio.Location = new Point(10, yPos);
    radio.Style = RadioButtonAdvStyle.Office2016Colorful;
    radio.ThemesEnabled = true;
    groupBox.Controls.Add(radio);
    yPos += 30;
}

this.Controls.Add(groupBox);

适用场景： 用户需要多个具备统一主题的关联选项。

Radio Button with Text Shadow

带文字阴影的单选按钮

Pattern: Add visual emphasis with text shadow effects.

csharp

RadioButtonAdv shadowRadio = new RadioButtonAdv();
shadowRadio.Text = "Important Option";
shadowRadio.TextShadow = true;
shadowRadio.ShadowColor = Color.Gold;
shadowRadio.ShadowOffset = new Point(2, 2);
shadowRadio.Font = new Font("Segoe UI", 10, FontStyle.Bold);
shadowRadio.Location = new Point(20, 20);

When: User wants to emphasize specific radio button options.

模式： 通过文字阴影效果增加视觉强调。

csharp

RadioButtonAdv shadowRadio = new RadioButtonAdv();
shadowRadio.Text = "Important Option";
shadowRadio.TextShadow = true;
shadowRadio.ShadowColor = Color.Gold;
shadowRadio.ShadowOffset = new Point(2, 2);
shadowRadio.Font = new Font("Segoe UI", 10, FontStyle.Bold);
shadowRadio.Location = new Point(20, 20);

适用场景： 用户希望突出特定单选按钮选项。

Custom Gradient Background

自定义渐变背景

Pattern: Create radio buttons with gradient backgrounds for modern appearance.

csharp

RadioButtonAdv gradientRadio = new RadioButtonAdv();
gradientRadio.Text = "Premium Option";
// Gradient properties set via designer or property grid
// GradientStart, GradientEnd, GradientStyle
gradientRadio.Location = new Point(20, 20);

When: User needs custom branded or styled radio buttons.

模式： 创建具备渐变背景的单选按钮，实现现代化外观。

csharp

RadioButtonAdv gradientRadio = new RadioButtonAdv();
gradientRadio.Text = "Premium Option";
// Gradient properties set via designer or property grid
// GradientStart, GradientEnd, GradientStyle
gradientRadio.Location = new Point(20, 20);

适用场景： 用户需要自定义品牌或样式的单选按钮。

Key Properties

核心属性

Theme and Style Properties

主题与样式属性

Property	Type	Description	When to Use
`Style`	RadioButtonAdvStyle	Office2007, Metro, Office2016 variants	Apply modern themes
`ThemesEnabled`	bool	Enable/disable theming	Control theme application
`Office2007ColorScheme`	Office2007Theme	Blue, Silver, Black, Managed	Office2007 color variants

属性	类型	描述	适用场景
`Style`	RadioButtonAdvStyle	Office2007、Metro、Office2016变体	应用现代化主题
`ThemesEnabled`	bool	启用/禁用主题	控制主题应用
`Office2007ColorScheme`	Office2007Theme	蓝色、银色、黑色、托管	Office2007颜色变体

Text Properties

文字属性

Property	Type	Description	When to Use
`TextShadow`	bool	Enable text shadow effect	Add visual depth to text
`ShadowColor`	Color	Shadow color	Customize shadow appearance
`ShadowOffset`	Point	Shadow position offset	Control shadow placement
`WrapText`	bool	Enable text wrapping	Handle long text labels

属性	类型	描述	适用场景
`TextShadow`	bool	启用文字阴影效果	为文字增加视觉深度
`ShadowColor`	Color	阴影颜色	自定义阴影外观
`ShadowOffset`	Point	阴影位置偏移	控制阴影位置
`WrapText`	bool	启用文字换行	处理长文本标签

Appearance Properties

外观属性

Property	Type	Description	When to Use
`DrawFocusRectangle`	bool	Show/hide focus rectangle	Control focus indicator
`AutoHeight`	bool	Auto-calculate height	Adjust to content size
`BackColor`	Color	Background color	Custom backgrounds
`ForeColor`	Color	Text color	Custom text colors

属性	类型	描述	适用场景
`DrawFocusRectangle`	bool	显示/隐藏焦点框	控制焦点指示器
`AutoHeight`	bool	自动计算高度	根据内容尺寸调整
`BackColor`	Color	背景颜色	自定义背景
`ForeColor`	Color	文字颜色	自定义文字颜色

Behavior Properties

行为属性

Property	Type	Description	When to Use
`RaiseEventOnClick`	bool	Fire OnClick event	Control click behavior
`Checked`	bool	Radio button state	Set default selection

属性	类型	描述	适用场景
`RaiseEventOnClick`	bool	触发OnClick事件	控制点击行为
`Checked`	bool	单选按钮状态	设置默认选中项

Common Use Cases

常见用例

Settings Dialog

设置对话框

Create a settings form with themed radio buttons:

Group related options (Theme, Size, Layout)
Apply consistent Office2016 theming
Professional appearance matching application style

创建带主题单选按钮的设置表单：

对关联选项分组（主题、尺寸、布局）
应用统一的Office2016主题
符合应用风格的专业外观

Wizard Step Selection

向导步骤选择

Radio buttons for wizard navigation:

Metro or Office2016 style for modern look
Text shadow for emphasis on current step
Clear visual hierarchy

用于向导导航的单选按钮：

Metro或Office2016风格实现现代化外观
文字阴影突出当前步骤
清晰的视觉层级

Survey/Questionnaire Forms

调研/问卷表单

Multiple-choice questions with styled radio buttons:

Consistent theming across all questions
Text wrapping for long option labels
Professional survey appearance

带样式单选按钮的多选题：

所有问题统一主题
长选项标签支持文字换行
专业的调研外观

Preference Configuration

偏好配置

User preference selection:

Gradient backgrounds for premium options
Custom images per state for visual indicators
Value association for easy preference storage

用户偏好选择：

高级选项使用渐变背景
不同状态对应自定义图片作为视觉指示器
值关联便于偏好存储

Implementation Checklist

实现检查清单

When implementing RadioButtonAdv, ensure:

✅ Required assemblies referenced (Syncfusion.Tools.Windows.dll, etc.)
✅ Namespace included (Syncfusion.Windows.Forms.Tools)
✅ RadioButtonAdv instances created and configured
✅ Style/Theme applied for consistent appearance
✅ Text properties set (Text, Font, optional shadow)
✅ Location and Size specified for layout
✅ Event handlers added for CheckedChanged or Click
✅ Radio button groups properly configured (only one selected per group)
✅ Default selection set with Checked property
✅ Testing with different themes and styles

实现RadioButtonAdv时，请确保：

✅ 已引用所需程序集（Syncfusion.Tools.Windows.dll等）
✅ 已引入命名空间（Syncfusion.Windows.Forms.Tools）
✅ 已创建并配置RadioButtonAdv实例
✅ 已应用样式/主题保证外观统一
✅ 已设置文字属性（Text、Font、可选阴影）
✅ 已指定布局所需的位置和尺寸
✅ 已为CheckedChanged或Click添加事件处理程序
✅ 已正确配置单选按钮组（每组仅可选中一个）
✅ 已通过Checked属性设置默认选中项
✅ 已使用不同主题和样式完成测试

Troubleshooting Quick Reference

故障排查快速参考

Issue: Theme not applying

Set
```
ThemesEnabled = true
```
Ensure
```
Style
```
property is set to desired theme
Check if custom BackColor overrides theme

Issue: Text shadow not visible

Set
```
TextShadow = true
```
Choose contrasting
```
ShadowColor
```
Adjust
```
ShadowOffset
```
for visibility

Issue: Radio buttons not mutually exclusive

Ensure radio buttons are in same container (Form, Panel, GroupBox)
Only radio buttons in same parent container are grouped

Issue: Focus rectangle always visible

Set
```
DrawFocusRectangle = false
```
to hide
Check if form-level setting overrides control

Issue: Height not adjusting to text

Set
```
AutoHeight = true
```
Ensure
```
WrapText
```
is configured if text is long

问题： 主题不生效

设置
```
ThemesEnabled = true
```
确保
```
Style
```
属性已设置为所需主题
检查自定义BackColor是否覆盖了主题

问题： 文字阴影不可见

设置
```
TextShadow = true
```
选择对比度高的
```
ShadowColor
```
调整
```
ShadowOffset
```
提升可见性

问题： 单选按钮不互斥

确保单选按钮在同一个容器内（Form、Panel、GroupBox）
只有同一父容器内的单选按钮才会被归为一组

问题： 焦点框始终可见

设置
```
DrawFocusRectangle = false
```
隐藏
检查表单级设置是否覆盖了控件设置

问题： 高度没有根据文字调整

设置
```
AutoHeight = true
```
如果文字较长，确保已配置
```
WrapText
```

Summary

总结

RadioButtonAdv provides enhanced radio button functionality with:

Professional Themes: Office2007, Office2016, Metro styles
Text Effects: Shadow with custom colors and offsets
Visual Customization: Gradients, borders, images
Flexible Styling: Alignment, appearance, and behavior options

Use RadioButtonAdv when visual appearance and theming are important for creating professional, modern WinForms applications.

RadioButtonAdv提供的增强型单选按钮功能包括：

专业主题：Office2007、Office2016、Metro风格
文字效果：支持自定义颜色和偏移量的阴影
视觉自定义：渐变、边框、图片
灵活样式：对齐、外观和行为选项

当视觉外观和主题对于打造专业、现代化的WinForms应用非常重要时，请使用RadioButtonAdv。