Progress Display Customization

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

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:

// 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

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

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:

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:

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

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

---

Best Practices

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

---

Common Pitfalls

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

---

Usage Scenarios

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

---

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

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

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.