Events and Callbacks

Allows developers to integrate custom logic or update other parts of the application in response to changes in the gauge’s state, etc.

Overview

The Events and Callbacks feature in the SiticoneGaugeClock control exposes public events and virtual callback methods that are triggered during key operations. When the gauge value changes (either through programmatic updates or user interaction), the ValueChanged event is fired. Similarly, when an animated transition completes, the AnimationCompleted event is raised. Additionally, a standard PropertyChanged event is provided for notifying subscribers when a property value changes. These events enable the host application to respond dynamically—for example, by logging changes, updating related UI components, or triggering business logic.

---

Feature Settings and Customization

The table below outlines the available events and their corresponding callback methods, describing their function, default behavior, and sample usage snippets.

Event / Method	Description	Default Behavior / Signature	Sample Usage or Code Snippet
ValueChanged	Fires when the gauge’s value is updated (either through animation or direct assignment).	EventHandler: void(object sender, EventArgs e)	csharp<br/>gauge.ValueChanged += (s, e) => { MessageBox.Show("Gauge value changed."); };<br/>
AnimationCompleted	Fires when an ongoing animation (transition between values) completes.	EventHandler: void(object sender, EventArgs e)	csharp<br/>gauge.AnimationCompleted += (s, e) => { /* Additional logic after animation */ };<br/>
PropertyChanged	Notifies subscribers when a property value has changed; useful for data binding and UI updates.	PropertyChangedEventHandler: void(object sender, PropertyChangedEventArgs e)	csharp<br/>gauge.PropertyChanged += (s, e) => { Console.WriteLine($"{e.PropertyName} updated."); };<br/>
OnValueChanged()	Virtual method that raises the ValueChanged event; can be overridden to inject custom behavior.	protected virtual void OnValueChanged(EventArgs e)	Override this method in a derived control to add custom logic before or after the event is raised.
OnAnimationCompleted()	Virtual method that raises the AnimationCompleted event; can be overridden in a subclass.	protected virtual void OnAnimationCompleted(EventArgs e)	Override to customize the behavior when an animation finishes.

Note: The events are raised by internal logic (e.g., when the value is updated via SetTargetValue or when the animation timer completes), so subscribing to these events allows your application to monitor and react to gauge state changes.

---

Key Points

The table below summarizes the critical aspects of the Events and Callbacks feature.

Aspect	Details
Responsive Updates	Events ensure that any change in the gauge—whether through user interaction or programmatic updates—is immediately notified to subscribers.
Customizability	Virtual callback methods (OnValueChanged and OnAnimationCompleted) can be overridden to customize the control’s behavior.
Integration Flexibility	The events can be used for data binding, logging, triggering further actions, or updating related UI components.

---

Best Practices

Use the following guidelines to ensure effective utilization of events and callbacks.

Practice	Explanation	Code Example
Subscribe Early	Attach event handlers during initialization to capture all changes from the control.	csharp<br/>public MainForm() { InitializeComponent(); <br/> gauge.ValueChanged += Gauge_ValueChanged; }<br/><br/>private void Gauge_ValueChanged(object sender, EventArgs e) { /* Handle event */ }<br/>
Keep Event Handlers Lightweight	Ensure that event handler code executes quickly to avoid UI lag during frequent value updates or animations.	Offload heavy processing to background threads if needed.
Override Virtual Methods When Necessary	For custom behavior that must occur before or after the standard event raising, override OnValueChanged or OnAnimationCompleted.	csharp<br/>protected override void OnValueChanged(EventArgs e) { /* Custom logic */; base.OnValueChanged(e); }<br/>
Unsubscribe When Not Needed	Detach event handlers when the control is disposed or no longer needed to prevent memory leaks.	In the Dispose method, unsubscribe from events.

---

Common Pitfalls

Avoid these common issues when working with events and callbacks.

Pitfall	Description	Recommendation
Neglecting to Unsubscribe	Failure to remove event handlers can lead to memory leaks and unintended behavior when controls are re-created.	Ensure proper unsubscription in Dispose or when the event is no longer needed.
Overly Complex Handlers	Complex or long-running operations inside event handlers may block the UI thread, causing lag.	Keep handlers simple; consider using asynchronous methods or delegating heavy work to background threads.
Overriding Without Calling Base Methods	Overriding OnValueChanged or OnAnimationCompleted without calling the base method may prevent the event from being raised.	Always call base.OnValueChanged(e) or base.OnAnimationCompleted(e) when overriding.

---

Usage Scenarios

The table below outlines typical scenarios where the Events and Callbacks feature is advantageous.

Scenario	Description	Sample Code or Explanation
Real-Time Dashboard Updates	Automatically update other UI elements or trigger analytics when the gauge value changes.	Subscribe to ValueChanged to update a status label with the latest value.
Animation-Driven Actions	Trigger specific actions (such as logging or triggering further animations) once the gauge animation completes.	Subscribe to AnimationCompleted to log the end of an animated transition.
Data Binding and MVVM Integration	Use PropertyChanged events to keep bound view models updated when gauge properties change.	Bind the PropertyChanged event to update a view model property in a data binding scenario.

---

Real Life Usage Scenarios

The table below presents real-world examples demonstrating the application of events and callbacks.

Real Life Scenario	Description	Code Example
Financial Trading Application	Update a summary panel in real time as the gauge (e.g., market index) changes by subscribing to ValueChanged.	csharp<br/>gauge.ValueChanged += (s, e) => { summaryPanel.Update(gauge.Value); };<br/>
Automotive Dashboard	Trigger safety alerts when the speed gauge animation completes, ensuring that alerts are only fired once the transition finishes.	csharp<br/>gauge.AnimationCompleted += (s, e) => { AlertSystem.CheckSpeed(gauge.Value); };<br/>
Industrial Process Control	Use PropertyChanged events to automatically log changes to critical gauge properties for audit and analysis purposes.	csharp<br/>gauge.PropertyChanged += (s, e) => { Logger.Log($"{e.PropertyName} changed."); };<br/>

---

Troubleshooting Tips

If issues arise with event handling or callbacks, consider the following troubleshooting tips.

Issue	Potential Cause	Suggested Resolution
Event Not Firing	The event may not fire if the corresponding property is not updated, or the base method is not called in an override.	Check that properties are updated correctly and that overridden methods call the base implementation.
Memory Leaks	Persistent subscriptions from events can cause memory leaks if not unsubscribed properly.	Unsubscribe from events in the control's Dispose method or when the handler is no longer needed.
Unresponsive UI	Long-running code within an event handler can block the UI thread.	Optimize event handler code; offload heavy work to a background thread or use asynchronous methods.

---

Integration Example

Below is a complete code sample demonstrating how to integrate and handle events and callbacks in a WinForms application using the SiticoneGaugeClock control:

using System;
using System.ComponentModel;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI; // Ensure the namespace matches your project setup

namespace GaugeDemoApp
{
    public class MainForm : Form
    {
        private SiticoneGaugeClock gauge;
        private Label statusLabel;

        public MainForm()
        {
            InitializeComponent();
            RegisterEventHandlers();
        }

        private void InitializeComponent()
        {
            this.gauge = new SiticoneGaugeClock();
            this.statusLabel = new Label();
            this.SuspendLayout();
            // 
            // gauge
            // 
            this.gauge.Location = new Point(30, 30);
            this.gauge.Size = new Size(300, 300);
            // Set an initial value for demonstration
            this.gauge.Value = 50f;
            // 
            // statusLabel
            // 
            this.statusLabel.Location = new Point(30, 340);
            this.statusLabel.Size = new Size(300, 30);
            this.statusLabel.Text = "Gauge value: 50";
            // 
            // MainForm
            // 
            this.ClientSize = new Size(360, 400);
            this.Controls.Add(this.gauge);
            this.Controls.Add(this.statusLabel);
            this.Text = "Gauge Demo - Events and Callbacks";
            this.ResumeLayout(false);
        }

        private void RegisterEventHandlers()
        {
            // Subscribe to ValueChanged to update the status label when the gauge value changes.
            this.gauge.ValueChanged += Gauge_ValueChanged;
            // Subscribe to AnimationCompleted to perform actions after an animation finishes.
            this.gauge.AnimationCompleted += Gauge_AnimationCompleted;
            // Subscribe to PropertyChanged for logging changes.
            this.gauge.PropertyChanged += Gauge_PropertyChanged;
        }

        private void Gauge_ValueChanged(object sender, EventArgs e)
        {
            // Update the status label with the new gauge value.
            statusLabel.Text = $"Gauge value: {gauge.Value:F1}";
        }

        private void Gauge_AnimationCompleted(object sender, EventArgs e)
        {
            // Notify that the animation has completed.
            MessageBox.Show("Animation completed. Gauge value update finished.", "Animation", MessageBoxButtons.OK, MessageBoxIcon.Information);
        }

        private void Gauge_PropertyChanged(object sender, PropertyChangedEventArgs e)
        {
            // Log the property change (could also update other UI elements or trigger further actions).
            Console.WriteLine($"Property {e.PropertyName} has changed.");
        }

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

In this example, the MainForm subscribes to the ValueChanged, AnimationCompleted, and PropertyChanged events. When the gauge value updates, the status label is refreshed; once an animation completes, a message box is displayed; and every property change is logged to the console. This illustrates how to use events and callbacks to integrate gauge state updates with other UI elements and application logic.

---

Review

The Events and Callbacks feature provides a robust mechanism for notifying your application of changes to the gauge. By subscribing to events like ValueChanged and AnimationCompleted, you can seamlessly integrate the gauge with other UI elements and business logic. Overriding virtual methods further enhances customization by allowing you to inject specific behavior into the control’s internal workflow.

---

Summary

The Events and Callbacks feature allows developers to respond dynamically to gauge state changes by subscribing to events and, if needed, overriding virtual callback methods. With events such as ValueChanged, AnimationCompleted, and PropertyChanged, you can update the UI, trigger further actions, and log changes efficiently. Detailed tables, best practices, usage scenarios, troubleshooting tips, and a full integration example have been provided to facilitate smooth implementation and effective customization in your WinForms applications.

---

Additional sections such as Key Points, Best Practices, and Real Life Usage Scenarios further assist in optimizing the use of events and callbacks, ensuring that your application remains responsive and interactive as gauge values change.