---
description: >-
  This feature allows developers to customize how progress information is
  displayed on the spinner, including text formatting, font styling, and color
  adjustments.
---

# Progress Display Customization

## Overview

The Progress Display Customization feature in the SiticoneLoadingSpinner control enables developers to display and format progress information directly on the spinner. By configuring properties such as ShowProgressText, ProgressFormat, ProgressFont, and ProgressTextColor, developers can provide clear, real-time feedback to users regarding task completion. Additionally, the control supports a progressive mode that visually represents progress through animation.

***

### Detailed Progress Display Settings

The table below summarizes the key progress display properties and settings available for customization, along with their descriptions and default values.

| Property / Setting | Description                                                                                                                     | Valid Values / Defaults                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| ShowProgressText   | Determines whether progress text is displayed in the center of the spinner.                                                     | Boolean (default: false)                                        |
| ProgressFormat     | Defines the format string used to display the progress value (e.g., "{0}%" to show percentage complete).                        | String (default: "{0}%")                                        |
| ProgressFont       | Sets the font used for rendering the progress text.                                                                             | Font (default: a regular 10pt font based on the control's Font) |
| ProgressTextColor  | Specifies the color of the progress text.                                                                                       | Color (default: Color.FromArgb(50, 0, 0, 0))                    |
| UseProgressiveMode | Enables a progressive mode where the progress state drives the spinner’s animation, typically filling the spokes incrementally. | Boolean (default: false)                                        |
| IsBusy (read-only) | Indicates whether the control is currently running a background task with progress updates.                                     | Boolean (derived from the background worker's state)            |

Additionally, the control exposes the following progress-related events for enhanced integration:

| Event           | Description                                                                         | EventArgs Type              |
| --------------- | ----------------------------------------------------------------------------------- | --------------------------- |
| ProgressChanged | Raised when progress is updated by the background worker.                           | ProgressChangedEventArgs    |
| WorkCompleted   | Raised when the background task has finished, either by completion or cancellation. | RunWorkerCompletedEventArgs |

***

### Code Examples & Integration Samples

#### Enabling Progress Text Display

To show the progress text (e.g., a percentage) at the center of the spinner, set the ShowProgressText property to true and adjust the format as needed:

```csharp
// Create and configure the spinner control.
var spinner = new SiticoneLoadingSpinner();

// Enable the progress text display.
spinner.ShowProgressText = true;

// Set the progress format to display as a percentage.
spinner.ProgressFormat = "{0}%";

// Optionally, customize the font and text color.
spinner.ProgressFont = new Font("Segoe UI", 12f, FontStyle.Bold);
spinner.ProgressTextColor = Color.DarkSlateGray;

// Start the spinner to begin progress display.
spinner.Start();
```

#### Integrating Background Task Progress Updates

Use the background worker integration to update the progress displayed on the spinner:

**Synchronous Progress Updates**

```csharp
spinner.RunWorkerAsync((sender, e) =>
{
    for (int i = 0; i <= 100; i++)
    {
        // Report progress as a value between 0 and 100.
        (sender as BackgroundWorker)?.ReportProgress(i);
        Thread.Sleep(50); // Simulate work.
    }
});
```

**Asynchronous Progress Updates**

```csharp
spinner.RunWorkerAsync(async (progress, token) =>
{
    for (int i = 0; i <= 100; i++)
    {
        if (token.IsCancellationRequested)
            token.ThrowIfCancellationRequested();

        // Report progress as a fraction.
        progress.Report(i / 100.0);
        await Task.Delay(50, token); // Simulate asynchronous work.
    }
});
```

#### Enabling Progressive Mode

Progressive mode adjusts the spinner’s animation based on progress, gradually illuminating spokes to indicate task completion:

```csharp
spinner.UseProgressiveMode = true;
// This setting automatically changes the animation style to Progressive.
spinner.ProgressiveSteps = 6;  // The number of spokes activated based on progress.
spinner.Start();
```

#### Handling Progress Events

Subscribe to progress-related events to update other parts of your UI or log progress updates:

```csharp
spinner.ProgressChanged += (s, e) =>
{
    Console.WriteLine($"Current progress: {e.ProgressPercentage}%");
};

spinner.WorkCompleted += (s, e) =>
{
    if (e.Cancelled)
        Console.WriteLine("Task was cancelled.");
    else if (e.Error != null)
        Console.WriteLine("An error occurred: " + e.Error.Message);
    else
        Console.WriteLine("Task completed successfully.");
};
```

***

### Key Points

<table><thead><tr><th width="270">Key Aspect</th><th>Details</th></tr></thead><tbody><tr><td>Progress Text Display</td><td>Use ShowProgressText to toggle visibility and ProgressFormat to customize how the progress is displayed.</td></tr><tr><td>Font and Color Customization</td><td>Adjust ProgressFont and ProgressTextColor to ensure the displayed text matches your application's style.</td></tr><tr><td>Progressive Mode</td><td>Enable UseProgressiveMode to have the spinner visually reflect progress by incrementally filling spokes.</td></tr><tr><td>Background Integration</td><td>Utilize the provided background worker methods to update progress in real time through ProgressChanged events.</td></tr></tbody></table>

***

### Best Practices

<table><thead><tr><th width="356">Best Practice</th><th>Recommendation</th></tr></thead><tbody><tr><td>Clear Communication</td><td>Use clear, readable fonts and colors for progress text to ensure that users can easily understand task progress.</td></tr><tr><td>Consistent Formatting</td><td>Standardize on a progress format (e.g., "{0}%") across your application to maintain consistency in user feedback.</td></tr><tr><td>Efficient Background Handling</td><td>Always check for cancellation requests in background tasks to ensure that progress updates are responsive and do not block the UI.</td></tr><tr><td>Synchronized Animation and Text Display</td><td>When using progressive mode, ensure that the number of ProgressiveSteps correlates with the overall design of the spinner.</td></tr></tbody></table>

***

### Common Pitfalls

<table><thead><tr><th width="337">Common Issue</th><th>Explanation &#x26; Resolution</th></tr></thead><tbody><tr><td>Overcomplicating the Progress Format</td><td>Avoid using overly complex format strings that may confuse users; stick to simple, intuitive formats like "{0}%".</td></tr><tr><td>Ignoring Text Readability</td><td>Ensure that the selected font size and color provide sufficient contrast against the spinner’s background.</td></tr><tr><td>Misalignment with Animation</td><td>When enabling UseProgressiveMode, ensure that the visual progress (animated spokes) aligns well with the numerical progress displayed.</td></tr><tr><td>Inconsistent Progress Updates</td><td>Ensure that background tasks consistently report progress to avoid flickering or stalled progress displays.</td></tr></tbody></table>

***

### Usage Scenarios

<table><thead><tr><th width="254">Scenario</th><th>Description &#x26; Sample Code</th></tr></thead><tbody><tr><td>Task Progress Indicator</td><td>Display progress text during file uploads or data processing to inform users of task completion status.</td></tr><tr><td>Real-Time Status Feedback</td><td>Combine progress text with progressive animation for a more engaging user experience in long-running operations.</td></tr><tr><td>Custom UI Feedback</td><td>Customize progress display properties to match your application's theme, ensuring that the progress indicator is visually cohesive with other UI elements.</td></tr><tr><td>Debugging and Logging</td><td>Subscribe to ProgressChanged and WorkCompleted events to log progress information and diagnose long-running tasks.</td></tr></tbody></table>

***

### Review

The Progress Display Customization feature of the SiticoneLoadingSpinner control provides comprehensive options for presenting task progress directly on the spinner. With customizable text formatting, font styling, and color settings, developers can ensure that progress information is clear and aesthetically pleasing. In addition, the integration with background tasks through synchronous or asynchronous methods and the use of progressive mode make it a versatile solution for real-time progress feedback.

***

### Summary

Progress Display Customization in the SiticoneLoadingSpinner control enables developers to visually represent task progress through customizable text display and progressive animations. By adjusting properties such as ShowProgressText, ProgressFormat, ProgressFont, and ProgressTextColor, and leveraging background task integration, developers can provide clear, engaging feedback to users during long-running operations. This feature, when combined with best practices, ensures a consistent and responsive user experience.

***

### Additional Tips

<table><thead><tr><th width="250">Tip</th><th>Recommendation</th></tr></thead><tbody><tr><td>Test with Real Data</td><td>Simulate realistic progress updates to ensure that the progress text and animation accurately reflect task status.</td></tr><tr><td>Consistent UI Elements</td><td>Keep the progress display consistent with other UI feedback elements in your application for a unified look and feel.</td></tr><tr><td>Monitor Performance</td><td>Check that enabling progress updates does not adversely affect UI responsiveness, especially in high-frequency update scenarios.</td></tr><tr><td>Document Customizations</td><td>Comment your progress display customizations in the code to facilitate future adjustments and maintenance.</td></tr></tbody></table>

This comprehensive documentation for the Progress Display Customization feature should guide developers in effectively integrating and customizing progress feedback within the SiticoneLoadingSpinner control for .NET WinForms applications.
