syncfusion-winforms-radial-slider（同步融合 winforms 径向滑块）

Implementing Radial Sliders (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.

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

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

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

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

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

Quick Start Example

Create a basic RadialSlider for volume control:

C#:

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}";
    }
}

Common Patterns

Pattern 1: Temperature Control with Custom Text

C#:

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.Color.Blue; // Cold
    }
    else if (temp > 33 && temp <= 66)
    {
       e.ForeColor = System.Drawing.Color.Orange; // Warm
    }
    else
    {
        e.ForeColor = System.Drawing.Color.Red; // Hot
    }
}

Key Properties

Common Use Cases

Volume/Audio Controls

Use RadialSlider for volume knobs, audio level controls, or media player controls where circular dials provide intuitive control.

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

• Syncfusion RadialSlider API Reference
• Control Dependencies
• Assembly: Syncfusion.Tools.Windows
• Namespace: Syncfusion.Windows.Forms.Tools