syncfusion-winforms-toggle-button

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Windows Forms Toggle Button

实现Syncfusion Windows Forms Toggle Button

Welcome to the Toggle Button implementation guide. The Toggle Button control allows you to toggle between two contrasting states (Active and Inactive) with full customization options.

欢迎来到Toggle Button实现指南。Toggle Button控件支持在两种对立状态（激活/未激活）之间切换，并提供完整的自定义选项。

When to Use This Skill

何时使用本教程

Use this skill when you need to:

Create toggle buttons with two contrasting states (ON/OFF, YES/NO, etc.)
Customize the appearance of active and inactive states
Switch between text and image display modes
Implement custom styling with renderers
Handle toggle events and state changes
Build interactive Windows Forms applications with toggle controls

当你需要实现以下需求时可使用本教程：

创建支持两种对立状态（ON/OFF、YES/NO等）的切换按钮
自定义激活和未激活状态的外观
在文本和图片显示模式之间切换
通过渲染器实现自定义样式
处理切换事件和状态变更
构建带切换控件的交互式Windows Forms应用

Component Overview

组件概述

The Toggle Button is a Windows Forms control that presents two distinct states:

Active State: Typically used for "ON", "YES", or enabled conditions
Inactive State: Typically used for "OFF", "NO", or disabled conditions

Users can toggle between states by clicking the button or pressing the Space key.

Toggle Button是一种Windows Forms控件，提供两种不同的状态：

激活状态：通常用于表示"ON"、"YES"或启用的条件
未激活状态：通常用于表示"OFF"、"NO"或禁用的条件

用户可以通过点击按钮或按下空格键在两种状态之间切换。

Key Capabilities

核心能力

Configurable Active and Inactive states with independent styling
Display modes: Text or Image
Event handling for state changes
Custom rendering support
Full color and border customization per state

可配置的激活和未激活状态，支持独立样式设置
显示模式：文本或图片
状态变更事件处理
支持自定义渲染
支持按状态自定义全量颜色和边框

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Assembly dependencies and NuGet setup
Adding Toggle Button via Designer
Adding Toggle Button via code
Namespace imports and basic initialization

📄 阅读： references/getting-started.md

程序集依赖和NuGet配置
通过设计器添加Toggle Button
通过代码添加Toggle Button
命名空间导入和基础初始化

Toggle States Configuration

切换状态配置

📄 Read: references/toggle-states.md

Understanding Active and Inactive states
Setting the toggle state programmatically
Customizing Active state (colors, text, hover effects)
Customizing Inactive state (colors, text, hover effects)
State transitions and toggling

📄 阅读： references/toggle-states.md

理解激活和未激活状态
通过代码设置切换状态
自定义激活状态（颜色、文本、悬停效果）
自定义未激活状态（颜色、文本、悬停效果）
状态过渡与切换

Display Modes

显示模式

📄 Read: references/display-modes.md

Text display mode configuration
Image display mode configuration
Switching between display modes
Use cases and best practices

📄 阅读： references/display-modes.md

文本显示模式配置
图片显示模式配置
显示模式切换
适用场景与最佳实践

Custom Styling and Renderers

自定义样式与渲染器

📄 Read: references/custom-styling.md

Custom renderer implementation
Implementing the IToggleButtonRenderer interface
Assigning custom renderers
Advanced styling and appearance customization

📄 阅读： references/custom-styling.md

自定义渲染器实现
实现IToggleButtonRenderer接口
分配自定义渲染器
高级样式与外观自定义

Events and Interaction

事件与交互

📄 Read: references/events-and-interaction.md

Handling state change events
Mouse click interactions
Keyboard interactions (Space key)
Event patterns and best practices

📄 阅读： references/events-and-interaction.md

处理状态变更事件
鼠标点击交互
键盘交互（空格键）
事件模式与最佳实践

Quick Start Example

快速入门示例

Here's a minimal example to create and configure a Toggle Button:

csharp

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

// Create and add Toggle Button to form
ToggleButton toggleButton = new ToggleButton();
toggleButton.Location = new System.Drawing.Point(50, 50);
toggleButton.Size = new System.Drawing.Size(100, 40);
toggleButton.Name = "toggleButton1";

// Configure Active state
toggleButton.ActiveState.Text = "ON";
toggleButton.ActiveState.BackColor = Color.FromArgb(1, 115, 199);
toggleButton.ActiveState.ForeColor = Color.White;

// Configure Inactive state
toggleButton.InactiveState.Text = "OFF";
toggleButton.InactiveState.BackColor = Color.White;
toggleButton.InactiveState.ForeColor = Color.FromArgb(80, 80, 80);

// Set initial state
toggleButton.ToggleState = ToggleButtonState.Inactive;

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

以下是创建和配置Toggle Button的最小示例：

csharp

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

// Create and add Toggle Button to form
ToggleButton toggleButton = new ToggleButton();
toggleButton.Location = new System.Drawing.Point(50, 50);
toggleButton.Size = new System.Drawing.Size(100, 40);
toggleButton.Name = "toggleButton1";

// Configure Active state
toggleButton.ActiveState.Text = "ON";
toggleButton.ActiveState.BackColor = Color.FromArgb(1, 115, 199);
toggleButton.ActiveState.ForeColor = Color.White;

// Configure Inactive state
toggleButton.InactiveState.Text = "OFF";
toggleButton.InactiveState.BackColor = Color.White;
toggleButton.InactiveState.ForeColor = Color.FromArgb(80, 80, 80);

// Set initial state
toggleButton.ToggleState = ToggleButtonState.Inactive;

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

Common Patterns

常见使用模式

Pattern 1: Binary State Toggle

模式1：二进制状态切换

Create a simple ON/OFF toggle button for boolean settings:

csharp

toggleButton.ActiveState.Text = "ON";
toggleButton.InactiveState.Text = "OFF";
toggleButton.ToggleState = ToggleButtonState.Inactive;

为布尔类型设置创建简单的ON/OFF切换按钮：

csharp

toggleButton.ActiveState.Text = "ON";
toggleButton.InactiveState.Text = "OFF";
toggleButton.ToggleState = ToggleButtonState.Inactive;

Pattern 2: Yes/No Toggle

模式2：是/否切换

Create a decision toggle:

csharp

toggleButton.ActiveState.Text = "YES";
toggleButton.InactiveState.Text = "NO";

创建决策类切换按钮：

csharp

toggleButton.ActiveState.Text = "YES";
toggleButton.InactiveState.Text = "NO";

Pattern 3: State-Based Colors

模式3：基于状态的颜色

Apply different colors to visually indicate state:

csharp

// Active - Green
toggleButton.ActiveState.BackColor = Color.FromArgb(34, 177, 76);
toggleButton.ActiveState.ForeColor = Color.White;

// Inactive - Red
toggleButton.InactiveState.BackColor = Color.FromArgb(192, 0, 0);
toggleButton.InactiveState.ForeColor = Color.White;

应用不同颜色直观标识状态：

csharp

// Active - Green
toggleButton.ActiveState.BackColor = Color.FromArgb(34, 177, 76);
toggleButton.ActiveState.ForeColor = Color.White;

// Inactive - Red
toggleButton.InactiveState.BackColor = Color.FromArgb(192, 0, 0);
toggleButton.InactiveState.ForeColor = Color.White;

Pattern 4: Custom Text Per State

模式4：各状态自定义文本

Provide descriptive labels for each state:

csharp

toggleButton.ActiveState.Text = "Enabled";
toggleButton.InactiveState.Text = "Disabled";

为每个状态提供描述性标签：

csharp

toggleButton.ActiveState.Text = "Enabled";
toggleButton.InactiveState.Text = "Disabled";

Key Properties

核心属性

Property	Purpose	Common Values
`ToggleState`	Current state of the button	`ToggleButtonState.Active` , `ToggleButtonState.Inactive`
`ActiveState.Text`	Text displayed when active	"ON", "YES", "Enabled"
`InactiveState.Text`	Text displayed when inactive	"OFF", "NO", "Disabled"
`ActiveState.BackColor`	Background color when active	Color values
`InactiveState.BackColor`	Background color when inactive	Color values
`DisplayMode`	What to display	`DisplayType.Text` , `DisplayType.Image`
`Renderer`	Custom appearance rendering	IToggleButtonRenderer implementation

属性	用途	常用值
`ToggleState`	按钮当前状态	`ToggleButtonState.Active` , `ToggleButtonState.Inactive`
`ActiveState.Text`	激活状态下显示的文本	"ON", "YES", "Enabled"
`InactiveState.Text`	未激活状态下显示的文本	"OFF", "NO", "Disabled"
`ActiveState.BackColor`	激活状态下的背景色	颜色值
`InactiveState.BackColor`	未激活状态下的背景色	颜色值
`DisplayMode`	显示内容类型	`DisplayType.Text` , `DisplayType.Image`
`Renderer`	自定义外观渲染	IToggleButtonRenderer实现类

Assembly Dependencies

程序集依赖

To use Toggle Button, add these assemblies to your project:

```
Syncfusion.Grid.Base
```
```
Syncfusion.Grid.Windows
```
```
Syncfusion.Shared.Base
```
```
Syncfusion.Shared.Windows
```
```
Syncfusion.Tools.Base
```
```
Syncfusion.Tools.Windows
```

要使用Toggle Button，请在项目中添加以下程序集：

```
Syncfusion.Grid.Base
```
```
Syncfusion.Grid.Windows
```
```
Syncfusion.Shared.Base
```
```
Syncfusion.Shared.Windows
```
```
Syncfusion.Tools.Base
```
```
Syncfusion.Tools.Windows
```

Next Steps

后续步骤

Start with Getting Started - Install dependencies and add the control
Configure States - Customize active and inactive appearance
Choose Display Mode - Text or image display
Add Styling - Apply custom renderers if needed
Handle Events - Respond to state changes in your application

从入门指南开始 - 安装依赖并添加控件
配置状态 - 自定义激活和未激活状态的外观
选择显示模式 - 文本或图片显示
添加样式 - 按需应用自定义渲染器
处理事件 - 在应用中响应状态变更