Events

A feature that provides notifications for significant state changes and animations within the progress control, enabling developers to respond to progress updates and transitions in their applications

Overview

The Events feature exposes several events that allow developers to hook into the control’s lifecycle and respond to key changes. These events include notifications when the progress value changes, when the minimum or maximum boundaries are updated, and when animations (both for value transitions and indeterminate cycles) complete. By subscribing to these events, you can integrate custom logic, update other UI elements, or log progress updates seamlessly.

---

Sections

Key Points

Aspect	Description	Example/Notes
ValueChanged	Fires when the progress value changes, providing the new value in the event arguments.	Subscribe with: progressBar.ValueChanged += OnValueChanged;
MinimumChanged	Fires when the minimum boundary is updated, signaling that the progress range has been altered.	Use to adjust dependent calculations if the minimum value changes.
MaximumChanged	Fires when the maximum boundary is updated, alerting subscribers to changes in the progress range.	Useful for recalibrating UI elements that depend on the maximum value.
AnimationCompleted	Fires once a value transition animation has completed, indicating that the progress has reached its target value.	Ideal for triggering subsequent actions after a smooth animation finishes.
IndeterminateAnimationCompleted	Fires after each cycle of the indeterminate animation completes, allowing developers to monitor or log the progression of ongoing, non-determinate processes.	Can be used to update status indicators or perform periodic checks during an indeterminate operation.

---

Best Practices

Recommendation	Rationale	Code Example
Always unsubscribe from events when no longer needed	Prevents memory leaks and unwanted behavior if the control is disposed or the form is closed.	csharp<br>progressBar.ValueChanged -= OnValueChanged;<br>
Use event arguments to drive dependent UI updates	Ensures that your UI remains in sync with the control’s internal state changes.	csharp<br>private void OnValueChanged(object sender, ValueChangedEventArgs e)<br>{<br> labelStatus.Text = $"Progress: {e.Value}%";<br>}<br>
Chain actions after animations by handling AnimationCompleted	Guarantees that subsequent actions occur only after the progress animation has fully settled.	csharp<br>progressBar.AnimationCompleted += (s, e) => { /* Execute next step */ };<br>
Log or monitor indeterminate cycles for diagnostics	Useful for long-running operations where periodic progress updates help in debugging and user feedback.	csharp<br>progressBar.IndeterminateAnimationCompleted += (s, e) => { Debug.WriteLine("Indeterminate cycle complete."); };<br>

---

Common Pitfalls

Pitfall	Explanation	How to Avoid
Overlooking event unsubscription	Failing to remove event handlers can lead to memory leaks, especially in dynamic or multi-form applications.	Unsubscribe from events when the control or form is disposed.
Ignoring null-checks in event handlers	Directly accessing event data without proper validation might result in runtime errors if the sender is null.	Validate event arguments and sender objects before processing event logic.
Handling too many events simultaneously	Excessive event handling may cause performance degradation if not optimized, especially with rapid value updates.	Debounce event handlers or throttle actions if the event frequency is very high.
Mixing synchronous and asynchronous code in handlers	Synchronous handlers might block the UI thread, leading to a sluggish user experience during animations.	Offload long-running operations to background threads or use asynchronous event patterns.

---

Usage Scenarios

Scenario	How Events Help	Sample Code Example
Updating UI on Progress Changes	Use ValueChanged to update labels, progress bars, or logs elsewhere in your application when progress changes occur.	csharp<br>progressBar.ValueChanged += (s, e) => { uiLabel.Text = $"Progress: {e.Value}%"; };<br>
Reacting to Range Changes	Use MinimumChanged and MaximumChanged to dynamically adjust other controls or calculations when the progress range is modified.	csharp<br>progressBar.MinimumChanged += (s, e) => { /* Update related UI or logic */ };<br>progressBar.MaximumChanged += (s, e) => { /* Update dependent calculations */ };<br>
Triggering Actions After Animations Complete	Handle AnimationCompleted to start subsequent processes only after the progress animation settles at its target value.	csharp<br>progressBar.AnimationCompleted += (s, e) => { StartNextOperation(); };<br>
Monitoring Indeterminate Processes	Subscribe to IndeterminateAnimationCompleted to log or update UI status periodically during a non-determinate operation.	csharp<br>progressBar.IndeterminateAnimationCompleted += (s, e) => { LogCycleCompletion(); };<br>

---

Code Examples and Integration Demos

Example 1: Basic Event Subscription

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

public class EventDemoForm : Form
{
    private Label lblProgress;
    private SiticoneRadialProgressBar progressBar;

    public EventDemoForm()
    {
        // Initialize label for progress display
        lblProgress = new Label
        {
            Location = new Point(20, 200),
            AutoSize = true,
            Font = new Font("Segoe UI", 12)
        };
        this.Controls.Add(lblProgress);

        // Initialize and configure the progress bar
        progressBar = new SiticoneRadialProgressBar
        {
            Size = new Size(160, 160),
            Location = new Point(20, 20),
            Minimum = 0,
            Maximum = 100,
            Value = 0,
            TextFormat = "{0}%"
        };

        // Subscribe to the ValueChanged event
        progressBar.ValueChanged += OnValueChanged;

        // Subscribe to the AnimationCompleted event
        progressBar.AnimationCompleted += (s, e) =>
        {
            MessageBox.Show("Animation completed. Progress has reached the target value.");
        };

        this.Controls.Add(progressBar);

        // Simulate progress updates
        Timer progressTimer = new Timer { Interval = 100 };
        progressTimer.Tick += (s, e) =>
        {
            if (progressBar.Value < progressBar.Maximum)
            {
                progressBar.Value += 5;
            }
            else
            {
                progressTimer.Stop();
            }
        };
        progressTimer.Start();
    }

    private void OnValueChanged(object sender, SiticoneRadialProgressBar.ValueChangedEventArgs e)
    {
        lblProgress.Text = $"Current Progress: {e.Value}%";
    }

    [STAThread]
    static void Main()
    {
        Application.EnableVisualStyles();
        Application.Run(new EventDemoForm());
    }
}

Example 2: Handling Range Changes

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

public class RangeChangeForm : Form
{
    public RangeChangeForm()
    {
        var progressBar = new SiticoneRadialProgressBar
        {
            Size = new Size(160, 160),
            Location = new Point(30, 30),
            Minimum = 0,
            Maximum = 100,
            Value = 50,
            TextFormat = "{0}%"
        };

        // Subscribe to range change events
        progressBar.MinimumChanged += (s, e) =>
        {
            Console.WriteLine($"Minimum value changed to: {e.Value}");
        };

        progressBar.MaximumChanged += (s, e) =>
        {
            Console.WriteLine($"Maximum value changed to: {e.Value}");
        };

        this.Controls.Add(progressBar);
    }

    [STAThread]
    static void Main()
    {
        Application.EnableVisualStyles();
        Application.Run(new RangeChangeForm());
    }
}

---

Review

Review Aspect	Discussion	Recommendations
Flexibility	The control’s events allow integration of custom logic for both visual updates and backend processing.	Subscribe to the events that are most relevant to your application’s needs.
Ease of Integration	Event-driven architecture simplifies the task of synchronizing UI elements and handling state changes.	Use lambda expressions or dedicated methods for clarity and maintainability.
Robustness	Properly managed event subscriptions and unsubscriptions ensure reliable and memory-efficient applications.	Always remove event handlers in disposal or when they are no longer needed.

---

Summary

The Events feature of the SiticoneRadialProgressBar control empowers developers to integrate responsive, event-driven behavior into their applications. By leveraging events such as ValueChanged, MinimumChanged, MaximumChanged, AnimationCompleted, and IndeterminateAnimationCompleted, you can synchronize UI updates, trigger follow-up actions, and monitor control state changes effectively. This comprehensive documentation, along with sample code and best practices, is intended to streamline the integration of these events into your .NET WinForms applications.

---

Additional Useful Sections

Troubleshooting Tips

Issue	Potential Cause	Suggested Resolution
Event handlers not firing	The control may not be properly initialized or subscribed.	Ensure that event subscriptions occur after the control is instantiated and added to the form.
Memory leaks due to lingering event subscriptions	Handlers remain subscribed after the control is disposed.	Unsubscribe from events in the control’s Dispose method or when the form is closing.
Confusing multiple event triggers	Rapid progress updates may cause events to fire in quick succession.	Consider debouncing or throttling event handlers if rapid consecutive triggers become problematic.

FAQs

Question	Answer
How can I access the new progress value from the events?	The event arguments (e.g., ValueChangedEventArgs) provide the updated progress value which can be accessed via the Value property.
What is the difference between AnimationCompleted and ValueChanged?	ValueChanged fires on every progress update, while AnimationCompleted fires only after the animated transition has finished.
Can I subscribe to multiple events simultaneously?	Yes, you can subscribe to any combination of the available events to suit your application’s needs.

---

This comprehensive documentation for the Events feature provides detailed insights, best practices, code examples, and troubleshooting tips to help you effectively integrate event-driven functionality into the SiticoneRadialProgressBar control within your .NET WinForms applications.