Events and Callbacks

This feature provides a set of events and callbacks that allow developers to respond to spinner state changes, progress updates, and animation milestones in real time.

Overview

The Events and Callbacks feature of the SiticoneLoadingSpinner control enables developers to integrate custom logic at key points in the spinner's lifecycle. The control exposes events for state changes (when the spinner starts or stops), for completing a full rotation, and for progress updates during background operations. These callbacks allow for responsive UI updates, logging, or triggering additional actions in synchronization with the spinner's animation and background processing.

---

Detailed Events and Callbacks

The table below summarizes the primary events available, their descriptions, and the associated event argument types.

Event / Callback	Description	EventArgs Type
SpinnerStateChanged	Raised whenever the spinner starts or stops, allowing developers to react to changes in its running state.	SpinnerStateEventArgs
RotationCompleted	Occurs when the spinner completes a full rotation, which can be used to trigger periodic actions.	EventArgs (typically empty)
ProgressChanged	Raised during background operations to provide progress updates, enabling real-time feedback.	ProgressChangedEventArgs
WorkCompleted	Triggered when a background task finishes, whether through successful completion, cancellation, or error.	RunWorkerCompletedEventArgs

Note: The SpinnerStateEventArgs provides a Boolean property, IsRunning, to indicate whether the spinner is active.

---

Code Examples & Integration Samples

Handling Spinner State Changes

Subscribe to the SpinnerStateChanged event to execute custom logic when the spinner starts or stops:

// Create an instance of the spinner control.
var spinner = new SiticoneLoadingSpinner();

// Subscribe to the SpinnerStateChanged event.
spinner.SpinnerStateChanged += (sender, e) =>
{
    if (e.IsRunning)
    {
        Console.WriteLine("Spinner started.");
    }
    else
    {
        Console.WriteLine("Spinner stopped.");
    }
};

// Start and then stop the spinner.
spinner.Start();
Thread.Sleep(2000);  // Simulate some work.
spinner.Stop();

Responding to Rotation Completion

Utilize the RotationCompleted event to perform actions each time the spinner completes a full cycle:

spinner.RotationCompleted += (sender, e) =>
{
    // Example: Log every completed rotation.
    Console.WriteLine("A full rotation has been completed.");
};
spinner.Start();

Integrating Progress Updates

Leverage the ProgressChanged event to update UI elements or log progress during background tasks:

spinner.ProgressChanged += (sender, e) =>
{
    // Update a status label or log the progress.
    Console.WriteLine($"Progress: {e.ProgressPercentage}%");
};

// Example background task using the synchronous RunWorkerAsync overload.
spinner.RunWorkerAsync((sender, e) =>
{
    for (int i = 0; i <= 100; i++)
    {
        (sender as BackgroundWorker)?.ReportProgress(i);
        Thread.Sleep(50); // Simulate work.
    }
});

Handling Background Work Completion

Subscribe to the WorkCompleted event to determine when background operations have finished:

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

---

Key Points

Aspect	Details
Real-Time State Notifications	The SpinnerStateChanged event provides immediate feedback when the spinner's state changes (start/stop).
Periodic Animation Callbacks	RotationCompleted can be used to trigger actions after every complete rotation, useful for periodic tasks.
Progress Reporting	ProgressChanged and WorkCompleted offer detailed insights into background task execution and progress status.
Standard Event Patterns	Events use standard .NET event argument types, making integration straightforward and familiar to developers.

---

Best Practices

Best Practice	Recommendation
Unsubscribe When Not Needed	To prevent memory leaks, unsubscribe from events when the spinner control is disposed or when event callbacks are no longer necessary.
Use Clear and Concise Handlers	Keep event handlers lightweight to ensure that UI responsiveness is maintained during frequent callback events (e.g., progress updates).
Coordinate with Background Tasks	Ensure that progress reporting is synchronized with long-running operations to provide accurate user feedback without delays.
Log and Debug Effectively	Use event callbacks to log key lifecycle events, which can help diagnose issues during development and in production environments.

---

Common Pitfalls

Common Issue	Explanation & Resolution
Overloading Event Handlers	Implementing heavy logic in event callbacks may cause UI freezes; keep handlers minimal and offload processing if needed.
Memory Leaks from Persistent Subscriptions	Failing to unsubscribe from events when the control is no longer in use can result in memory leaks; ensure proper disposal patterns.
Ignoring Cancellation Feedback	Not checking for cancellation or error states in WorkCompleted may lead to unresponsive or misleading UI updates; always handle these states.
Misinterpreting Progress Values	Ensure that progress values reported via ProgressChanged are correctly interpreted (e.g., converting to percentage if needed).

---

Usage Scenarios

Scenario	Description & Sample Code
UI Status Updates	Update labels or progress bars in your application by handling ProgressChanged, keeping users informed during long operations.
Periodic Task Triggering	Use RotationCompleted to trigger periodic background checks or UI updates (e.g., refreshing data every full rotation).
Debugging Long-Running Tasks	Log events from WorkCompleted and ProgressChanged to help diagnose issues with long-running tasks or to provide feedback to users.
Dynamic UI Adjustments	Change application UI elements (such as enabling/disabling buttons) based on the spinner’s running state via SpinnerStateChanged.

---

Review

The Events and Callbacks feature of the SiticoneLoadingSpinner control offers an event-driven approach to monitor and respond to various aspects of the spinner's operation. By providing clear notifications for state changes, rotation completions, and background progress updates, developers gain the flexibility to integrate custom logic, update UI elements, or log events in real time. This integration ensures that the spinner not only serves as a visual indicator but also as a reliable source of process feedback.

---

Summary

The Events and Callbacks feature empowers developers to harness the full interactivity of the SiticoneLoadingSpinner control. With events such as SpinnerStateChanged, RotationCompleted, ProgressChanged, and WorkCompleted, the control provides timely notifications about its operational state and background tasks. This event-driven model enables dynamic UI responses, efficient logging, and robust error handling, ensuring a seamless and responsive user experience.

---

Additional Tips

Tip	Recommendation
Centralize Event Handling	Consider creating a dedicated event handler class or method for logging and UI updates to keep your code organized and maintainable.
Use Lambda Expressions Judiciously	While lambda expressions can simplify event subscriptions, ensure that they do not obscure the underlying logic for future maintainability.
Test Under Load	Simulate heavy background work to ensure that your event handlers maintain responsiveness and accurately reflect state changes.
Document Event Usage	Clearly document the intended use of each event in your codebase so that future developers understand their roles and interactions.

This comprehensive documentation for the Events and Callbacks feature should enable developers to effectively integrate, monitor, and respond to spinner state changes and background operations within their .NET WinForms applications.