Back to Details

syncfusion-winforms-radial-slider

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Radial Sliders (RadialSlider)

实现径向滑块（RadialSlider）

A circular slider control for Windows Forms that provides visual numeric value selection through a rotating needle around a radial dial with customizable divisions and themes.
这是一款适用于Windows Forms的圆形滑块控件，用户可通过围绕径向刻度盘旋转的指针完成可视化数值选择，支持自定义刻度和主题。

When to Use This Skill

什么时候使用该技能

Use this skill when you need to:
  • Circular Value Selection: Implement dial-based numeric input (like volume knobs, temperature dials)
  • Rotating Controls: Create rotary controls with visual feedback
  • Value Pickers: Build circular value selectors with minimum/maximum ranges
  • Division Markers: Display value divisions around a circular dial
  • Visual Indicators: Show numeric values in a radial/circular format
  • Interactive Dials: Implement knob-style controls (gauges, sliders, rotary switches)
  • Themed Controls: Apply Office 2016 visual themes to circular sliders
  • Custom Value Ranges: Set specific min/max ranges with visual divisions
当你需要实现以下需求时可以使用本技能：
  • 圆形数值选择：实现基于刻度盘的数值输入（比如音量旋钮、温度刻度盘）
  • 旋转类控件：创建带视觉反馈的旋转控制组件
  • 数值选择器：构建带最大/最小值范围的圆形数值选择器
  • 刻度标记：在圆形刻度盘周围展示数值刻度
  • 视觉指示器：以径向/圆形格式展示数值
  • 交互式刻度盘：实现旋钮风格的控件（仪表、滑块、旋转开关）
  • 带主题的控件：为圆形滑块应用Office 2016视觉主题
  • 自定义数值范围：设置带可视化刻度的特定最大/最小值范围

Component Overview

组件概述

The RadialSlider is an advanced circular slider control that provides:
  • Circular/radial value selection with rotating needle
  • Customizable minimum and maximum value ranges
  • Division markers around the dial
  • Two slider styles (Default with hollow circles, Frame with background)
  • Five Office 2016 visual themes plus default style
  • Customizable colors (background, circles, needle, foreground)
  • Two needle types (Straight Line, Dotted Line)
  • ValueChanged event for real-time value tracking
  • Custom text formatting for division labels
Key Capabilities:
  • MinimumValue
    and 
    MaximumValue
    properties for range configuration
  • Value
    property for getting/setting current selection
  • SliderDivision
    property for configuring division markers
  • SliderStyle
    enum (Default, Frame)
  • Style
    property with 6 visual themes
  • NeedleType
    enum (StraightLine, DottedLine)
  • Color customization (BackgroundColor, InnerCircleColor, OuterCircleColor, SliderNeedleColor)
  • ValueChanged
    event for tracking value changes
  • DrawText
    event for custom text formatting
RadialSlider是一款高级圆形滑块控件，提供以下能力：
  • 带旋转指针的圆形/径向数值选择能力
  • 可自定义的最大、最小值范围
  • 刻度盘周围的刻度标记
  • 两种滑块样式（默认空心圆样式、带背景的框架样式）
  • 5种Office 2016视觉主题+默认样式
  • 可自定义颜色（背景、圆形区域、指针、前景色）
  • 两种指针类型（直线、虚线）
  • 用于实时数值追踪的ValueChanged事件
  • 刻度标签的自定义文本格式化能力
核心功能：
  • 用于范围配置的
    MinimumValue
    和
    MaximumValue
    属性
  • 用于获取/设置当前选中值的
    Value
    属性
  • 用于配置刻度标记的
    SliderDivision
    属性
  • SliderStyle
    枚举（默认、框架）
  • 支持6种视觉主题的
    Style
    属性
  • NeedleType
    枚举（直线、虚线）
  • 颜色自定义能力（背景色、内圈颜色、外圈颜色、滑块指针颜色）
  • 用于追踪数值变化的
    ValueChanged
    事件
  • 用于自定义文本格式化的
    DrawText
    事件

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
When to read: Setting up RadialSlider for the first time, adding to forms, basic configuration
Topics covered:
  • Assembly requirements and NuGet installation
  • Designer-based setup (drag-and-drop from toolbox)
  • Programmatic creation and configuration
  • Basic size and property configuration
  • Slider styles (Default vs Frame)
  • ShowOuterCircle property
  • Troubleshooting installation issues
📄 阅读： references/getting-started.md
适用场景： 首次配置RadialSlider、将控件添加到表单、基础配置
涵盖主题：
  • 程序集要求与NuGet安装
  • 设计器配置方式（从工具箱拖拽添加）
  • 编码方式创建与配置
  • 基础尺寸与属性配置
  • 滑块样式（默认vs框架）
  • ShowOuterCircle属性
  • 安装问题排查

Value Configuration

数值配置

📄 Read: references/value-configuration.md
When to read: Configuring value ranges, divisions, handling value changes, custom text formatting
Topics covered:
  • MinimumValue and MaximumValue properties
  • Value property (get/set current value)
  • SliderDivision property for division markers
  • ValueChanged event handling
  • DrawText event for custom text formatting
  • TextType enum (Interval, Pointer, Value)
  • DrawTextEventArgs properties (Text, ForeColor, Font)
  • Practical examples for value tracking
📄 阅读： references/value-configuration.md
适用场景： 配置数值范围、刻度、处理数值变化、自定义文本格式化
涵盖主题：
  • MinimumValue和MaximumValue属性
  • Value属性（获取/设置当前值）
  • 用于配置刻度标记的SliderDivision属性
  • ValueChanged事件处理
  • 用于自定义文本格式化的DrawText事件
  • TextType枚举（间隔、指针、数值）
  • DrawTextEventArgs属性（文本、前景色、字体）
  • 数值追踪的实际示例

Appearance Customization

外观自定义

📄 Read: references/appearance-customization.md
When to read: Applying visual themes, customizing colors, changing needle appearance
Topics covered:
  • BackgroundColor property
  • InnerCircleColor and OuterCircleColor properties
  • SliderNeedleColor property
  • ForeColor property
  • NeedleType enum (StraightLine, DottedLine)
  • Visual styles (6 themes: Default, Office2016Colorful/White/DarkGray/Black)
  • Complete theming examples
  • Color combination best practices
📄 阅读： references/appearance-customization.md
适用场景： 应用视觉主题、自定义颜色、修改指针外观
涵盖主题：
  • BackgroundColor属性
  • InnerCircleColor和OuterCircleColor属性
  • SliderNeedleColor属性
  • ForeColor属性
  • NeedleType枚举（直线、虚线）
  • 视觉样式（6种主题：默认、Office2016彩色/白色/深灰/黑色）
  • 完整的主题示例
  • 颜色搭配最佳实践

Quick Start Example

快速开始示例

Create a basic RadialSlider for volume control:
C#:
csharp
using System;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;

public partial class VolumeControl : Form
{
    private RadialSlider volumeSlider;
    private Label lblVolume;
    
    public VolumeControl()
    {
        InitializeComponent();
        SetupVolumeControl();
    }
    
    private void SetupVolumeControl()
    {
        // Create radial slider
        volumeSlider = new RadialSlider
        {
            Location = new System.Drawing.Point(50, 50),
            Size = new System.Drawing.Size(250, 250),
            MinimumValue = 0,
            MaximumValue = 100,
            Value = 50,
            SliderDivision = 10,
            SliderStyle = SliderStyles.Frame
        };
        
        // Create label for volume display
        lblVolume = new Label
        {
            Location = new System.Drawing.Point(50, 310),
            Size = new System.Drawing.Size(250, 30),
            Text = "Volume: 50",
            TextAlign = System.Drawing.ContentAlignment.MiddleCenter
        };
        
        // Handle value changes
        volumeSlider.ValueChanged += VolumeSlider_ValueChanged;
        
        // Add to form
        this.Controls.Add(volumeSlider);
        this.Controls.Add(lblVolume);
    }
    
    private void VolumeSlider_ValueChanged(object sender, RadialSlider.ValueChangedEventArgs e)
    {
        lblVolume.Text = $"Volume: {volumeSlider.Value}";
    }
}
VB.NET:
vbnet
Imports System
Imports System.Windows.Forms
Imports Syncfusion.Windows.Forms.Tools

Public Partial Class VolumeControl
    Inherits Form
    
    Private volumeSlider As RadialSlider
    Private lblVolume As Label
    
    Public Sub New()
        InitializeComponent()
        SetupVolumeControl()
    End Sub
    
    Private Sub SetupVolumeControl()
        ' Create radial slider
        volumeSlider = New RadialSlider With {
            .Location = New System.Drawing.Point(50, 50),
            .Size = New System.Drawing.Size(250, 250),
            .MinimumValue = 0,
            .MaximumValue = 100,
            .Value = 50,
            .SliderDivision = 10,
            .SliderStyle = SliderStyles.Frame
        }
        
        ' Create label for volume display
        lblVolume = New Label With {
            .Location = New System.Drawing.Point(50, 310),
            .Size = New System.Drawing.Size(250, 30),
            .Text = "Volume: 50",
            .TextAlign = System.Drawing.ContentAlignment.MiddleCenter
        }
        
        ' Handle value changes
        AddHandler volumeSlider.ValueChanged, AddressOf VolumeSlider_ValueChanged
        
        ' Add to form
        Me.Controls.Add(volumeSlider)
        Me.Controls.Add(lblVolume)
    End Sub
    
    Private Sub VolumeSlider_ValueChanged(sender As Object, e As RadialSlider.ValueChangedEventArgs)
        lblVolume.Text = $"Volume: {volumeSlider.Value}"
    End Sub
End Class
创建一个基础的音量控制RadialSlider：
C#:
csharp
using System;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;

public partial class VolumeControl : Form
{
    private RadialSlider volumeSlider;
    private Label lblVolume;
    
    public VolumeControl()
    {
        InitializeComponent();
        SetupVolumeControl();
    }
    
    private void SetupVolumeControl()
    {
        // Create radial slider
        volumeSlider = new RadialSlider
        {
            Location = new System.Drawing.Point(50, 50),
            Size = new System.Drawing.Size(250, 250),
            MinimumValue = 0,
            MaximumValue = 100,
            Value = 50,
            SliderDivision = 10,
            SliderStyle = SliderStyles.Frame
        };
        
        // Create label for volume display
        lblVolume = new Label
        {
            Location = new System.Drawing.Point(50, 310),
            Size = new System.Drawing.Size(250, 30),
            Text = "Volume: 50",
            TextAlign = System.Drawing.ContentAlignment.MiddleCenter
        };
        
        // Handle value changes
        volumeSlider.ValueChanged += VolumeSlider_ValueChanged;
        
        // Add to form
        this.Controls.Add(volumeSlider);
        this.Controls.Add(lblVolume);
    }
    
    private void VolumeSlider_ValueChanged(object sender, RadialSlider.ValueChangedEventArgs e)
    {
        lblVolume.Text = $"Volume: {volumeSlider.Value}";
    }
}
VB.NET:
vbnet
Imports System
Imports System.Windows.Forms
Imports Syncfusion.Windows.Forms.Tools

Public Partial Class VolumeControl
    Inherits Form
    
    Private volumeSlider As RadialSlider
    Private lblVolume As Label
    
    Public Sub New()
        InitializeComponent()
        SetupVolumeControl()
    End Sub
    
    Private Sub SetupVolumeControl()
        ' Create radial slider
        volumeSlider = New RadialSlider With {
            .Location = New System.Drawing.Point(50, 50),
            .Size = New System.Drawing.Size(250, 250),
            .MinimumValue = 0,
            .MaximumValue = 100,
            .Value = 50,
            .SliderDivision = 10,
            .SliderStyle = SliderStyles.Frame
        }
        
        ' Create label for volume display
        lblVolume = New Label With {
            .Location = New System.Drawing.Point(50, 310),
            .Size = New System.Drawing.Size(250, 30),
            .Text = "Volume: 50",
            .TextAlign = System.Drawing.ContentAlignment.MiddleCenter
        }
        
        ' Handle value changes
        AddHandler volumeSlider.ValueChanged, AddressOf VolumeSlider_ValueChanged
        
        ' Add to form
        Me.Controls.Add(volumeSlider)
        Me.Controls.Add(lblVolume)
    End Sub
    
    Private Sub VolumeSlider_ValueChanged(sender As Object, e As RadialSlider.ValueChangedEventArgs)
        lblVolume.Text = $"Volume: {volumeSlider.Value}"
    End Sub
End Class

Common Patterns

常用模式

Pattern 1: Temperature Control with Custom Text

模式1：带自定义文本的温度控制控件

C#:
csharp
private RadialSlider tempSlider;

private void SetupTemperatureControl()
{
    tempSlider = new RadialSlider
    {
        MinimumValue = 0,
        MaximumValue = 100,
        Value = 25,
        SliderDivision = 10,
        Style = RadialSliderStyle.Office2016Colorful
    };
    
    // Custom text formatting with degree symbol
    tempSlider.DrawText += TempSlider_DrawText;
    
    this.Controls.Add(tempSlider);
}

private void TempSlider_DrawText(object sender, RadialSlider.DrawTextEventArgs e)
{
    // Add degree Celsius symbol
    e.Text += "°C";
    
    // Color code by temperature range
    int temp = int.Parse(e.Text.Replace("°C", ""));
    
    if (temp <= 33)
    {
        e.ForeColor = System.Drawing.Brushes.Blue; // Cold
    }
    else if (temp > 33 && temp <= 66)
    {
        e.ForeColor = System.Drawing.Brushes.Orange; // Warm
    }
    else
    {
        e.ForeColor = System.Drawing.Brushes.Red; // Hot
    }
}
C#:
csharp
private RadialSlider tempSlider;

private void SetupTemperatureControl()
{
    tempSlider = new RadialSlider
    {
        MinimumValue = 0,
        MaximumValue = 100,
        Value = 25,
        SliderDivision = 10,
        Style = RadialSliderStyle.Office2016Colorful
    };
    
    // Custom text formatting with degree symbol
    tempSlider.DrawText += TempSlider_DrawText;
    
    this.Controls.Add(tempSlider);
}

private void TempSlider_DrawText(object sender, RadialSlider.DrawTextEventArgs e)
{
    // Add degree Celsius symbol
    e.Text += "°C";
    
    // Color code by temperature range
    int temp = int.Parse(e.Text.Replace("°C", ""));
    
    if (temp <= 33)
    {
        e.ForeColor = System.Drawing.Brushes.Blue; // Cold
    }
    else if (temp > 33 && temp <= 66)
    {
        e.ForeColor = System.Drawing.Brushes.Orange; // Warm
    }
    else
    {
        e.ForeColor = System.Drawing.Brushes.Red; // Hot
    }
}

Pattern 2: Custom Styled Dial Control

模式2：自定义样式的刻度盘控件

C#:
csharp
private void CreateCustomStyledDial()
{
    RadialSlider dial = new RadialSlider
    {
        Size = new System.Drawing.Size(280, 280),
        MinimumValue = 0,
        MaximumValue = 200,
        SliderDivision = 20,
        
        // Custom colors
        BackgroundColor = System.Drawing.Color.FromArgb(30, 30, 30), // Dark background
        InnerCircleColor = System.Drawing.Color.FromArgb(60, 60, 60),
        OuterCircleColor = System.Drawing.Color.FromArgb(80, 80, 80),
        SliderNeedleColor = System.Drawing.Color.LimeGreen,
        ForeColor = System.Drawing.Color.White,
        
        // Dotted needle for modern look
        NeedleType = SliderNeedleType.DottedLine,
        SliderStyle = SliderStyles.Frame
    };
    
    this.Controls.Add(dial);
}
C#:
csharp
private void CreateCustomStyledDial()
{
    RadialSlider dial = new RadialSlider
    {
        Size = new System.Drawing.Size(280, 280),
        MinimumValue = 0,
        MaximumValue = 200,
        SliderDivision = 20,
        
        // Custom colors
        BackgroundColor = System.Drawing.Color.FromArgb(30, 30, 30), // Dark background
        InnerCircleColor = System.Drawing.Color.FromArgb(60, 60, 60),
        OuterCircleColor = System.Drawing.Color.FromArgb(80, 80, 80),
        SliderNeedleColor = System.Drawing.Color.LimeGreen,
        ForeColor = System.Drawing.Color.White,
        
        // Dotted needle for modern look
        NeedleType = SliderNeedleType.DottedLine,
        SliderStyle = SliderStyles.Frame
    };
    
    this.Controls.Add(dial);
}

Pattern 3: Font Size Selector

模式3：字体大小选择器

C#:
csharp
private RadialSlider fontSizeSlider;
private RichTextBox textPreview;

private void SetupFontSizeSelector()
{
    // Create slider for font size selection
    fontSizeSlider = new RadialSlider
    {
        MinimumValue = 8,
        MaximumValue = 72,
        Value = 12,
        SliderDivision = 8
    };
    
    // Create preview textbox
    textPreview = new RichTextBox
    {
        Text = "Sample Text",
        ReadOnly = true
    };
    
    // Update font size on value change
    fontSizeSlider.ValueChanged += (s, e) =>
    {
        textPreview.SelectionFont = new System.Drawing.Font(
            textPreview.Font.Name,
            (float)fontSizeSlider.Value
        );
    };
    
    this.Controls.Add(fontSizeSlider);
    this.Controls.Add(textPreview);
}
C#:
csharp
private RadialSlider fontSizeSlider;
private RichTextBox textPreview;

private void SetupFontSizeSelector()
{
    // Create slider for font size selection
    fontSizeSlider = new RadialSlider
    {
        MinimumValue = 8,
        MaximumValue = 72,
        Value = 12,
        SliderDivision = 8
    };
    
    // Create preview textbox
    textPreview = new RichTextBox
    {
        Text = "Sample Text",
        ReadOnly = true
    };
    
    // Update font size on value change
    fontSizeSlider.ValueChanged += (s, e) =>
    {
        textPreview.SelectionFont = new System.Drawing.Font(
            textPreview.Font.Name,
            (float)fontSizeSlider.Value
        );
    };
    
    this.Controls.Add(fontSizeSlider);
    this.Controls.Add(textPreview);
}

Key Properties

核心属性

PropertyTypeDefaultPurpose
MinimumValue
int
0
Starting value of slider range
MaximumValue
int
10
Ending value of slider range
Value
int
0
Current selected value
SliderDivision
int
10
Number of division markers
SliderStyle
SliderStyles
Default
Visual style (Default, Frame)
Style
RadialSliderStyle
Default
Theme (Default, Office2016*)
BackgroundColor
Color
System defaultBackground color
InnerCircleColor
Color
System defaultInner circle color
OuterCircleColor
Color
System defaultOuter circle color
SliderNeedleColor
Color
System defaultNeedle color
ForeColor
Color
System defaultText color
NeedleType
SliderNeedleType
StraightLine
Needle appearance
ShowOuterCircle
bool
true
Show/hide outer circle
属性类型默认值用途
MinimumValue
int
0
滑块范围的起始值
MaximumValue
int
10
滑块范围的结束值
Value
int
0
当前选中值
SliderDivision
int
10
刻度标记数量
SliderStyle
SliderStyles
Default
视觉样式（默认、框架）
Style
RadialSliderStyle
Default
主题（默认、Office2016系列）
BackgroundColor
Color
系统默认背景色
InnerCircleColor
Color
系统默认内圈颜色
OuterCircleColor
Color
系统默认外圈颜色
SliderNeedleColor
Color
系统默认指针颜色
ForeColor
Color
系统默认文本颜色
NeedleType
SliderNeedleType
StraightLine
指针外观
ShowOuterCircle
bool
true
显示/隐藏外圈

Common Use Cases

常见使用场景

Volume/Audio Controls

音量/音频控制

Use RadialSlider for volume knobs, audio level controls, or media player controls where circular dials provide intuitive control.
将RadialSlider用于音量旋钮、音频电平控制或媒体播放器控件，圆形刻度盘可以提供更直观的控制体验。

Temperature Settings

温度设置

Implement temperature selectors for thermostats, climate controls, or weather applications with color-coded ranges.
为恒温器、气候控制或天气应用实现温度选择器，支持按范围进行颜色标记。

Speed Controls

速度控制

Create speed selectors for motors, fans, or animations with visual feedback through division markers.
为电机、风扇或动画创建速度选择器，通过刻度标记提供视觉反馈。

Brightness/Opacity Adjustments

亮度/透明度调整

Build brightness controls for displays, image editors, or lighting controls with percentage-based ranges.
为显示屏、图像编辑器或照明控制构建亮度控制组件，支持基于百分比的数值范围。

Timer/Duration Selection

计时器/时长选择

Implement countdown timers or duration selectors with minute/second divisions around a circular dial.
实现倒计时计时器或时长选择器，在圆形刻度盘周围设置分钟/秒刻度。

Gauge Displays

仪表展示

Create interactive gauges that users can adjust (fuel gauges, pressure gauges, progress indicators).
创建用户可调整的交互式仪表（燃油表、压力表、进度指示器）。

Settings Panels

设置面板

Use for numeric settings that benefit from visual representation (zoom levels, quality settings, intensity controls).
用于适合可视化展示的数值设置项（缩放级别、质量设置、强度控制）。

Data Visualization

数据可视化

Implement interactive data selectors where circular presentation is preferred over linear sliders.
实现优先使用圆形展示而非线性滑块的交互式数据选择器。

Additional Resources

额外资源