syncfusion-winforms-progress-bar（同步融合 winform 进度条）

Windows Forms Progress Bar (ProgressBarAdv)

The Syncfusion Windows Forms ProgressBarAdv control provides progress information during lengthy operations such as installation, copying, printing, and downloading. It displays progress with customizable text formats, colors, orientations, and visual styles.

When to Use This Skill

Use this skill when you need to:

• Display progress information for lengthy operations (file operations, installations, downloads)
• Show percentage completion or current value out of total
• Implement loading indicators with custom text and animations
• Create progress bars with horizontal or vertical orientation
• Customize progress appearance with colors, gradients, borders, and images
• Apply visual themes (Office 2016, System, Tube, Gradient styles)
• Handle progress events (ValueChanged, custom rendering)
• Display custom text on progress bars (e.g., "Loading...", "Processing...")
• Track time-consuming operations with visual feedback

Component Overview

Key Features:

• Text formats: Percentage, Value, or Custom text display
• Progress images: Use images for progress indication
• Color customization: Foreground, background, gradient, and border colors
• Orientation: Horizontal or vertical progress bars
• Visual styles: Office2016Colorful, Office2016White, Office2016DarkGray, Office2016Black, System, Tube, Gradient
• Events: ValueChanged, DrawWaitingCustomRender for custom rendering
• Themes: Built-in theme support with ThemesEnabled property

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

Read this reference when you need to:

• Install the ProgressBarAdv control via NuGet or designer
• Add the control to a Windows Forms project
• Create a ProgressBarAdv instance programmatically
• Set basic properties (Value, Minimum, Maximum)
• Configure initial progress bar setup
• Understand assembly deployment requirements

Text and Display Settings

📄 Read: references/text-display.md

Read this reference when you need to:

• Configure TextStyle (Percentage, Value, Custom)
• Set custom text with CustomText property
• Adjust text alignment (Left, Center, Right)
• Configure text orientation
• Customize text color and font
• Implement display format patterns

Appearance and Styling

📄 Read: references/appearance-styling.md

Read this reference when you need to:

• Customize foreground colors and gradients
• Set background colors and images
• Configure border settings (style, color, sides)
• Add progress images
• Use ProgressStyle options
• Apply background styles
• Implement color customization patterns

Orientation and Layout

📄 Read: references/orientation-layout.md

Read this reference when you need to:

• Set horizontal or vertical orientation
• Configure progress bar layout
• Handle size and positioning
• Implement responsive design patterns
• Adjust for different form layouts

Themes

📄 Read: references/themes.md

Read this reference when you need to:

• Enable theme support with ThemesEnabled
• Apply built-in visual styles (Office2016Colorful, Office2016White, etc.)
• Configure ProgressStyle options
• Choose appropriate themes for your application
• Understand theme selection guidelines

Events and Advanced Customization

📄 Read: references/events-advanced.md

Read this reference when you need to:

• Handle ValueChanged event
• Implement DrawWaitingCustomRender event
• Create custom rendering patterns
• Use WaitingCustomRender mode
• Configure ProgressFallBackStyle options
• Implement advanced customization scenarios

Quick Start

Basic Progress Bar

using Syncfusion.Windows.Forms.Tools;

// Create ProgressBarAdv instance
ProgressBarAdv progressBarAdv1 = new ProgressBarAdv();
progressBarAdv1.Location = new Point(20, 20);
progressBarAdv1.Size = new Size(300, 30);

// Set range and value
progressBarAdv1.Minimum = 0;
progressBarAdv1.Maximum = 100;
progressBarAdv1.Value = 60;

// Configure text display
progressBarAdv1.TextStyle = ProgressBarTextStyles.Percentage;
progressBarAdv1.TextAlignment = TextAlignment.Center;

// Apply visual style
progressBarAdv1.ProgressStyle = ProgressBarStyles.Office2016Colorful;

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

Common Patterns

Pattern 1: Percentage Progress Bar

// Display progress as percentage
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 45;
progressBar.TextStyle = ProgressBarTextStyles.Percentage;
progressBar.TextAlignment = TextAlignment.Center;

this.Controls.Add(progressBar);

Pattern 2: Custom Text Progress Bar

// Display custom text (e.g., "Loading...")
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 30;
progressBar.TextStyle = ProgressBarTextStyles.Custom;
progressBar.CustomText = "Loading files...";
progressBar.TextAlignment = TextAlignment.Center;

this.Controls.Add(progressBar);

Pattern 3: Value Format Progress Bar

// Display current value out of maximum (e.g., "60/100")
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 60;
progressBar.TextStyle = ProgressBarTextStyles.Value;
progressBar.TextAlignment = TextAlignment.Center;

this.Controls.Add(progressBar);

Pattern 4: Vertical Progress Bar

// Create vertical progress bar
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.ProgressOrientation = Orientation.Vertical;
progressBar.Size = new Size(50, 200);
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 75;
progressBar.TextStyle = ProgressBarTextStyles.Percentage;

this.Controls.Add(progressBar);

Pattern 5: Themed Progress Bar with Custom Colors

// Apply theme and custom colors
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.ProgressStyle = ProgressBarStyles.Office2016Colorful;
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 50;

// Custom colors
progressBar.ForeColor = Color.Blue;
progressBar.BackColor = Color.LightGray;

// Text settings
progressBar.TextStyle = ProgressBarTextStyles.Percentage;
progressBar.TextAlignment = TextAlignment.Center;

this.Controls.Add(progressBar);

Pattern 6: Progress Bar with ValueChanged Event

// Create progress bar with event handling
ProgressBarAdv progressBar = new ProgressBarAdv();
progressBar.Minimum = 0;
progressBar.Maximum = 100;
progressBar.Value = 0;
progressBar.TextStyle = ProgressBarTextStyles.Custom;
progressBar.CustomText = "Starting...";

// Subscribe to ValueChanged event
progressBar.ValueChanged += ProgressBar_ValueChanged;

this.Controls.Add(progressBar);

// Event handler
private void ProgressBar_ValueChanged(object sender, EventArgs e)
{
    ProgressBarAdv pb = sender as ProgressBarAdv;
    if (pb.Value < 100)
    {
        pb.CustomText = $"Processing... {pb.Value}%";
    }
    else
    {
        pb.CustomText = "Complete!";
    }
}

Pattern 7: Simulated Long Operation

// Simulate a long-running operation with progress updates
private async void StartOperation()
{
    ProgressBarAdv progressBar = new ProgressBarAdv();
    progressBar.Location = new Point(20, 20);
    progressBar.Size = new Size(400, 30);
    progressBar.Minimum = 0;
    progressBar.Maximum = 100;
    progressBar.Value = 0;
    progressBar.TextStyle = ProgressBarTextStyles.Percentage;
    progressBar.ProgressStyle = ProgressBarStyles.Office2016Colorful;

    this.Controls.Add(progressBar);

    // Simulate operation
    for (int i = 0; i <= 100; i += 10)
    {
        progressBar.Value = i;
        await Task.Delay(500); // Simulate work
    }

    MessageBox.Show("Operation complete!");
}

Key Properties

Key Events

Text Format Options

Visual Style Options