Events and Callbacks

Events and Callbacks enable developers to respond to significant control activities by subscribing to notifications such as progress changes, animation completions, and state transitions.

Overview

This section details the events and callback mechanisms built into the control. Developers can subscribe to these events to execute custom logic in response to changes in the progress value, animation lifecycle, or user interactions. These callbacks facilitate synchronization between the control and other components in a .NET WinForms application.

---

Properties, Events, and Methods

The table below summarizes the key events and callback methods provided by the control:

Property/Event/Method	Type / Signature	Description
ProgressChanged (Event)	event EventHandler<ProgressChangedEventArgs>	Occurs when the progress value changes, providing the old and new values along with the difference.
AnimationCompleted (Event)	event EventHandler	Fired when an animation sequence completes, allowing developers to execute logic immediately after the progress animation finishes.
AnimationStateChanged (Event)	event EventHandler<AnimationStateChangedEventArgs>	Notifies subscribers when the animation state changes (i.e., starts or stops), encapsulated within a custom event argument that indicates whether the control is animating.
OnProgressChanged (Callback)	protected virtual void OnProgressChanged(double oldValue, double newValue)	A method that raises the ProgressChanged event; developers can override this method to extend or modify the behavior when progress changes occur.
OnAnimationCompleted (Callback)	protected virtual void OnAnimationCompleted()	A method that triggers the AnimationCompleted event when an animation finishes.

Note: The event argument classes, ProgressChangedEventArgs and AnimationStateChangedEventArgs, encapsulate detailed information about the progress changes and animation state, respectively. These events provide an effective mechanism for decoupling the control's internal logic from application-specific behaviors.

---

Code Examples and Samples

Below are extensive code examples demonstrating how to subscribe to and handle the control's events and callbacks.

Example 1: Handling ProgressChanged

This example demonstrates how to subscribe to the ProgressChanged event to monitor changes in the progress value.

// Instantiate the progress bar control
SiticoneVBarsProgress progressBar = new SiticoneVBarsProgress
{
    Location = new System.Drawing.Point(50, 50),
    Size = new System.Drawing.Size(30, 200),
    Minimum = 0,
    Maximum = 100,
    Value = 20
};

// Subscribe to the ProgressChanged event
progressBar.ProgressChanged += (sender, e) =>
{
    // Custom logic: Log the old and new progress values
    Console.WriteLine($"Progress changed from {e.OldValue} to {e.NewValue}. Difference: {e.ProgressDifference}");
};

// Add the control to the form
this.Controls.Add(progressBar);

// Update the progress value to trigger the event
progressBar.Value = 40;

Example 2: Handling AnimationCompleted

This sample shows how to subscribe to the AnimationCompleted event to perform an action once the animation finishes.

// Subscribe to the AnimationCompleted event
progressBar.AnimationCompleted += (sender, e) =>
{
    // Custom logic: Inform the user that the animation has finished
    MessageBox.Show("Animation has completed successfully!");
};

// Trigger an animation by updating the progress value
progressBar.Value = 80;

Example 3: Handling AnimationStateChanged

This example illustrates how to subscribe to the AnimationStateChanged event to monitor when an animation starts or stops.

// Subscribe to the AnimationStateChanged event
progressBar.AnimationStateChanged += (sender, e) =>
{
    // Log the current animation state
    if (e.IsAnimating)
    {
        Console.WriteLine("Animation started.");
    }
    else
    {
        Console.WriteLine("Animation stopped.");
    }
};

// Start an animation by changing the progress value
progressBar.Value = 90;

Example 4: Overriding OnProgressChanged

Developers can override the OnProgressChanged method in a subclass to customize the behavior when progress changes.

public class CustomProgressBar : SiticoneVBarsProgress
{
    protected override void OnProgressChanged(double oldValue, double newValue)
    {
        base.OnProgressChanged(oldValue, newValue);
        // Custom logic: For example, update a label or trigger additional events
        Console.WriteLine($"[Custom] Progress updated from {oldValue} to {newValue}");
    }
}

---

Key Points

Key Point	Details
Event-Driven Architecture	The control leverages events to inform subscribers of internal changes, promoting loose coupling between the control and application logic.
Detailed Event Arguments	Custom event arguments provide specific details about the progress changes and animation state, facilitating fine-grained control.
Overridable Callbacks	Protected callback methods (OnProgressChanged and OnAnimationCompleted) allow for extensibility, enabling developers to customize behavior without modifying the core logic.

---

Best Practices

Best Practice	Recommendation
Subscribe Early	Attach event handlers during the initialization phase to ensure that changes in progress or animation are consistently monitored.
Unsubscribe Appropriately	Remove event handlers when the control is disposed to prevent memory leaks and unintended side effects.
Use Detailed Logging	Leverage event data provided by ProgressChangedEventArgs and AnimationStateChangedEventArgs to implement robust logging or debugging mechanisms.
Override Callbacks for Custom Logic	When necessary, extend the default behavior by overriding OnProgressChanged or OnAnimationCompleted to integrate tightly with application-specific requirements.

---

Common Pitfalls

Common Pitfall	Solution
Ignoring Event Unsubscription	Failing to unsubscribe event handlers can lead to memory leaks; always remove handlers when the control or form is disposed.
Overcomplicating Event Handling	Avoid performing heavy operations directly within event handlers; delegate complex logic to background threads or separate methods to maintain UI responsiveness.
Overriding Without Calling Base	When overriding OnProgressChanged or OnAnimationCompleted, ensure to call the base implementation to preserve the control's intended behavior.

---

Usage Scenarios

Scenario	Description	Sample Code Snippet
Synchronizing UI Elements	Update other UI elements (e.g., labels, progress bars) in response to progress changes using the ProgressChanged event.	progressBar.ProgressChanged += (s, e) => { myLabel.Text = $"Progress: {e.NewValue}%"; };
Triggering Post-Animation Logic	Execute business logic or UI transitions once an animation completes by subscribing to the AnimationCompleted event.	progressBar.AnimationCompleted += (s, e) => { LoadNextStep(); };
Monitoring Animation Lifecycle	Use the AnimationStateChanged event to adjust application state (e.g., disable buttons during animation) based on whether an animation is currently active.	progressBar.AnimationStateChanged += (s, e) => { myButton.Enabled = !e.IsAnimating; };

---

Review

Events and Callbacks are integral to the control's design, enabling developers to receive real-time notifications about progress updates and animation states. By leveraging these events, applications can remain responsive and synchronized with the control's behavior, thus enhancing user experience and overall functionality.

---

Summary

Events and Callbacks in the control provide:

• Mechanisms to notify subscribers when the progress value changes (ProgressChanged).

• Callbacks to inform when animations start and stop (AnimationStateChanged and AnimationCompleted).

• Overridable methods (OnProgressChanged and OnAnimationCompleted) that allow for customization of the control's internal behavior.

These features help maintain a decoupled architecture, allowing the control to seamlessly integrate with diverse application logics in .NET WinForms applications.

---

Additional Sections

Integration Tips

Tip	Details
Centralize Event Handling	Organize your event handlers in a dedicated section or class to keep the code clean and maintainable.
Leverage Custom Event Args	Use the detailed information provided by the custom event argument classes to implement robust and informative UI feedback or logging.
Test Event-Driven Behavior	Thoroughly test event-driven updates, especially under rapid progress changes, to ensure that the UI remains responsive and accurate.

Demo Application Sample

Below is a complete sample demonstrating how to integrate Events and Callbacks into a basic WinForms application.

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

namespace DemoApplication
{
    public partial class MainForm : Form
    {
        private SiticoneVBarsProgress progressBar;
        private Label progressLabel;

        public MainForm()
        {
            InitializeComponent();
            InitializeProgressBar();
            InitializeEventHandlers();
            InitializeUIElements();
        }

        private void InitializeProgressBar()
        {
            // Instantiate and configure the progress bar control
            progressBar = new SiticoneVBarsProgress
            {
                Location = new Point(50, 50),
                Size = new Size(30, 200),
                Minimum = 0,
                Maximum = 100,
                Value = 20
            };

            // Add the control to the form
            this.Controls.Add(progressBar);
        }

        private void InitializeEventHandlers()
        {
            // Subscribe to the ProgressChanged event
            progressBar.ProgressChanged += (sender, e) =>
            {
                // Update a label with the current progress percentage
                progressLabel.Text = $"Progress: {e.NewValue}%";
            };

            // Subscribe to the AnimationCompleted event
            progressBar.AnimationCompleted += (sender, e) =>
            {
                MessageBox.Show("Animation has finished!");
            };

            // Subscribe to the AnimationStateChanged event
            progressBar.AnimationStateChanged += (sender, e) =>
            {
                Console.WriteLine(e.IsAnimating ? "Animation started." : "Animation stopped.");
            };
        }

        private void InitializeUIElements()
        {
            // Add a label to display progress information
            progressLabel = new Label
            {
                Location = new Point(100, 50),
                Size = new Size(200, 30),
                Text = "Progress: 0%"
            };

            this.Controls.Add(progressLabel);

            // Button to simulate a progress update
            Button btnUpdateProgress = new Button
            {
                Text = "Update Progress",
                Location = new Point(100, 100),
                Size = new Size(120, 30)
            };

            btnUpdateProgress.Click += (sender, e) =>
            {
                // Update progress to a random value to trigger events
                Random rand = new Random();
                progressBar.Value = rand.Next((int)progressBar.Minimum, (int)progressBar.Maximum + 1);
            };

            this.Controls.Add(btnUpdateProgress);
        }
    }
}

This demo illustrates how to initialize the control, subscribe to its events, and handle progress updates and animation completions in a WinForms application.

---

By following this comprehensive guide, developers can fully leverage the Events and Callbacks provided by the control to build responsive and event-driven .NET WinForms applications.